Goose Agent 接入

Goose 是运行在本机的通用 Agent，可用于编码、研究、自动化和数据处理。官方同时提供 CLI、Desktop 和 API；CLI 与 Desktop 会识别同一目录中的自定义提供方定义，但凭证的来源可以不同。

开始前，请安装 Goose，并在 Lumoswitch 中创建使用 OpenAI-compatible 输出的配置 API。

方式总览

方式	是否支持	说明
从空白环境仅本次启动	不支持	Goose 的自定义 Base URL 与模型必须先注册为 JSON 提供方；CLI 没有完整的单次提供方定义参数
已注册后临时换 Key / 模型	支持	只给当前 Goose 进程传入环境变量
永久使用	支持	写入 Goose 原生提供方、用户环境与可选维护启动器
清除接入	支持	官方移除流程可同时删除提供方和 Keychain 凭证

准备连接信息

占位符	应填写的内容
`{{api_base_url}}`	配置 API 的下游地址，包含 `/v1`，末尾不要带 `/`
`{{access_key}}`	当前配置使用的 Lumoswitch Access Key
`{{model}}`	配置 API 显示的下游模型名称
`{{goose_provider_json}}`	包含全部下游模型的 Goose 提供方定义

永久使用

下面的命令创建 Goose 原生 Lumoswitch 提供方文件，并把 Key 保存到仅当前用户可读的受管环境文件中。不会覆盖 Goose 的 config.yaml 或其他提供方。

set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/goose"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-goose"
mkdir -p "$LUMOSWITCH_ROOT" "$(dirname "$LUMOSWITCH_LAUNCHER")"
umask 077

if [ -f "$LUMOSWITCH_LAUNCHER" ]; then
  LUMOSWITCH_BACKUP="$LUMOSWITCH_LAUNCHER.backup.$(date +%Y%m%d-%H%M%S)-$$"
  cp "$LUMOSWITCH_LAUNCHER" "$LUMOSWITCH_BACKUP"
  chmod 600 "$LUMOSWITCH_BACKUP"
fi

LUMOSWITCH_GOOSE_PROVIDER="$HOME/.config/goose/custom_providers/lumoswitch.json"
mkdir -p "$(dirname "$LUMOSWITCH_GOOSE_PROVIDER")"
cat > "$LUMOSWITCH_GOOSE_PROVIDER" <<'LUMOSWITCH_CONFIG_EOF'
{{goose_provider_json}}
LUMOSWITCH_CONFIG_EOF

cat > "$LUMOSWITCH_ENV" <<'LUMOSWITCH_ENV_EOF'
export LUMOSWITCH_GOOSE_API_KEY="{{access_key}}"
export GOOSE_PROVIDER="lumoswitch"
export GOOSE_MODEL="{{model}}"
LUMOSWITCH_ENV_EOF

case "$SHELL" in
  */zsh) LUMOSWITCH_PROFILE="$HOME/.zshrc" ;;
  */bash) LUMOSWITCH_PROFILE="$HOME/.bashrc" ;;
  *) LUMOSWITCH_PROFILE="$HOME/.profile" ;;
esac
touch "$LUMOSWITCH_PROFILE"
LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: goose'
LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/goose/env.sh" ] && . "$HOME/.config/lumoswitch/agents/goose/env.sh"'
if ! grep -Fqx "$LUMOSWITCH_SOURCE_LINE" "$LUMOSWITCH_PROFILE"; then
  printf '\n%s\n%s\n' "$LUMOSWITCH_PROFILE_MARKER" "$LUMOSWITCH_SOURCE_LINE" >> "$LUMOSWITCH_PROFILE"
fi
printf '%s\n' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_ROOT/profile-path"

cat > "$LUMOSWITCH_LAUNCHER" <<'LUMOSWITCH_LAUNCHER_EOF'
#!/usr/bin/env bash
set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/goose"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-goose"

if [ "$1" = "--lumoswitch-clean" ]; then
  if [ -f "$LUMOSWITCH_ROOT/profile-path" ]; then
    LUMOSWITCH_PROFILE="$(cat "$LUMOSWITCH_ROOT/profile-path")"
    if [ -f "$LUMOSWITCH_PROFILE" ]; then
      LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: goose'
      LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/goose/env.sh" ] && . "$HOME/.config/lumoswitch/agents/goose/env.sh"'
      LUMOSWITCH_PROFILE_TMP="$LUMOSWITCH_PROFILE.lumoswitch.$$"
      awk -v marker="$LUMOSWITCH_PROFILE_MARKER" -v source="$LUMOSWITCH_SOURCE_LINE" '$0 != marker && $0 != source' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_PROFILE_TMP"
      mv "$LUMOSWITCH_PROFILE_TMP" "$LUMOSWITCH_PROFILE"
    fi
  fi
  rm -f "$HOME/.config/goose/custom_providers/lumoswitch.json"
  if [ -d "$LUMOSWITCH_ROOT" ]; then
    find "$LUMOSWITCH_ROOT" -depth \( -type f -o -type l \) -delete
    find "$LUMOSWITCH_ROOT" -depth -type d -exec rmdir {} \; 2>/dev/null || true
  fi
  find "$(dirname "$LUMOSWITCH_LAUNCHER")" -maxdepth 1 -type f -name 'lumoswitch-goose.backup.*' -delete
  rm -f "$LUMOSWITCH_LAUNCHER"
  printf '%s\n' 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
fi

if [ -f "$LUMOSWITCH_ENV" ]; then . "$LUMOSWITCH_ENV"; fi
exec goose session start "$@"
LUMOSWITCH_LAUNCHER_EOF

chmod 600 "$LUMOSWITCH_ENV"
find "$LUMOSWITCH_ROOT" -type f -exec chmod 600 {} \;
chmod 700 "$LUMOSWITCH_LAUNCHER"
. "$LUMOSWITCH_ENV"
printf '%s\n' 'Native Lumoswitch setup saved. Future command: goose session start'
printf '%s\n' 'Optional maintenance launcher: ~/.local/bin/lumoswitch-goose'
goose session start

以后运行：

goose session start

context_limit 必须按真实模型能力调整；错误的值会影响 Goose 的上下文管理。

已注册后仅本次启动

完成一次永久注册后，可以临时使用另一个 Key 或模型，而不改写持久化配置：

env \
  LUMOSWITCH_GOOSE_API_KEY="{{access_key}}" \
  GOOSE_MODEL="{{model}}" \
  goose session start --provider lumoswitch

退出后这两个值立即失效，但 lumoswitch.json 仍然保留。它不是从空白环境开始的完整临时接入，因为 Goose 官方要求先存在自定义提供方定义。

Windows PowerShell 原生导入

以下命令在 Windows PowerShell 中原生运行，不需要 WSL。它们与本页的 macOS/Linux 模板使用同一组连接值。

永久使用（Windows）

该命令会备份已有的 Lumoswitch 专用文件，并为配置和启动器收紧当前用户的访问权限。

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\goose'
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-goose.ps1'
  $lumoswitchBackupSuffix = (Get-Date -Format 'yyyyMMdd-HHmmss') + '-' + $PID

  function Protect-LumoswitchFile([string] $Path) {
    $lumoswitchSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
    & icacls.exe $Path '/inheritance:r' '/grant:r' ('*' + $lumoswitchSid + ':(F)') '*S-1-5-18:(F)' '*S-1-5-32-544:(F)' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw "Could not restrict access to $Path" }
  }

  function Install-LumoswitchFile([string] $Path, [string] $Content) {
    [IO.Directory]::CreateDirectory((Split-Path -Parent $Path)) | Out-Null
    if (Test-Path -LiteralPath $Path) {
      $lumoswitchItem = Get-Item -LiteralPath $Path -Force
      if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
        throw "Lumoswitch refused to replace a directory or link: $Path"
      }
      $lumoswitchBackup = $Path + '.backup.' + $lumoswitchBackupSuffix
      Copy-Item -LiteralPath $Path -Destination $lumoswitchBackup
      Protect-LumoswitchFile $lumoswitchBackup
    }
    $lumoswitchTemporary = $Path + '.' + [Guid]::NewGuid().ToString('N') + '.tmp'
    try {
      [IO.File]::WriteAllText($lumoswitchTemporary, $Content, [Text.UTF8Encoding]::new($false))
      Move-Item -LiteralPath $lumoswitchTemporary -Destination $Path -Force
      Protect-LumoswitchFile $Path
    } finally {
      Remove-Item -LiteralPath $lumoswitchTemporary -Force -ErrorAction SilentlyContinue
    }
  }

  [IO.Directory]::CreateDirectory($lumoswitchRoot) | Out-Null
  $lumoswitchGooseProvider = Join-Path $env:APPDATA 'Block\goose\config\custom_providers\lumoswitch.json'
  $lumoswitchProviderContent = @'
{{goose_provider_json}}
'@
  Install-LumoswitchFile $lumoswitchGooseProvider $lumoswitchProviderContent

  $lumoswitchEnvironment = [ordered]@{}
  $lumoswitchEnvironment['LUMOSWITCH_GOOSE_API_KEY'] = '{{access_key}}'
  $lumoswitchEnvironment['GOOSE_PROVIDER'] = 'lumoswitch'
  $lumoswitchEnvironment['GOOSE_MODEL'] = '{{model}}'
  foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
  }

  $lumoswitchLauncherContent = @'
param([Parameter(ValueFromRemainingArguments = $true)][string[]] $AgentArgs)
$ErrorActionPreference = 'Stop'
$lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\goose'
$lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-goose.ps1'

function Remove-LumoswitchFile([string] $Path) {
  if (-not (Test-Path -LiteralPath $Path)) { return }
  $lumoswitchItem = Get-Item -LiteralPath $Path -Force
  if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
    throw "Lumoswitch refused to remove a directory or link: $Path"
  }
  Remove-Item -LiteralPath $Path -Force
}

if ($AgentArgs.Count -gt 0 -and $AgentArgs[0] -eq '--lumoswitch-clean') {
  foreach ($lumoswitchName in @('LUMOSWITCH_GOOSE_API_KEY', 'GOOSE_PROVIDER', 'GOOSE_MODEL')) {
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'Process')
  }
  Remove-LumoswitchFile (Join-Path $env:APPDATA 'Block\goose\config\custom_providers\lumoswitch.json')
  if (Test-Path -LiteralPath $lumoswitchRoot -PathType Container) {
    $lumoswitchRootItem = Get-Item -LiteralPath $lumoswitchRoot -Force
    if ($lumoswitchRootItem.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Lumoswitch refused to clean through a linked directory.' }
    foreach ($lumoswitchFile in @(Get-ChildItem -LiteralPath $lumoswitchRoot -File -Recurse -Force)) { Remove-LumoswitchFile $lumoswitchFile.FullName }
    foreach ($lumoswitchDirectory in @(Get-ChildItem -LiteralPath $lumoswitchRoot -Directory -Recurse -Force | Sort-Object FullName -Descending)) {
      if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchDirectory.FullName -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchDirectory.FullName -Force }
    }
    if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchRoot -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchRoot -Force }
  }
  $lumoswitchBin = Split-Path -Parent $lumoswitchLauncher
  if (Test-Path -LiteralPath $lumoswitchBin -PathType Container) {
    foreach ($lumoswitchBackup in @(Get-ChildItem -LiteralPath $lumoswitchBin -Filter 'lumoswitch-goose.ps1.backup.*' -File -Force)) { Remove-LumoswitchFile $lumoswitchBackup.FullName }
  }
  Remove-LumoswitchFile $lumoswitchLauncher
  Write-Host 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
}

$lumoswitchEnvironment = [ordered]@{}
$lumoswitchEnvironment['LUMOSWITCH_GOOSE_API_KEY'] = '{{access_key}}'
$lumoswitchEnvironment['GOOSE_PROVIDER'] = 'lumoswitch'
$lumoswitchEnvironment['GOOSE_MODEL'] = '{{model}}'
foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
  [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
}
$lumoswitchExecutable = Get-Command 'goose.cmd' -CommandType Application -ErrorAction SilentlyContinue
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'goose.exe' -CommandType Application -ErrorAction SilentlyContinue }
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'goose' -CommandType Application -ErrorAction Stop }
$lumoswitchArguments = @('session', 'start')
& $lumoswitchExecutable.Path @lumoswitchArguments @AgentArgs
if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }
'@
  Install-LumoswitchFile $lumoswitchLauncher $lumoswitchLauncherContent
  Write-Host 'Native Lumoswitch setup saved. Future command: goose session start'
  Write-Host 'Optional maintenance launcher:' $lumoswitchLauncher
  $lumoswitchExecutable = Get-Command 'goose.cmd' -CommandType Application -ErrorAction SilentlyContinue
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'goose.exe' -CommandType Application -ErrorAction SilentlyContinue }
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'goose' -CommandType Application -ErrorAction Stop }
  $lumoswitchArguments = @('session', 'start')
  & $lumoswitchExecutable.Path @lumoswitchArguments
  if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { throw 'goose exited with code ' + $LASTEXITCODE }
}

导入会写入 Agent 支持的持久化配置，并直接启动 goose session start。保存的 Lumoswitch 维护脚本不是启动 Agent 的必需入口；需要恢复或移除此接入时，运行它并追加 --lumoswitch-clean。

清除 Lumoswitch 接入

Windows PowerShell

先退出该 Agent 的所有 Lumoswitch 会话，再运行下面的命令。可选维护启动器会删除受管原生配置、恢复已保留的共享文件、清除 Lumoswitch 用户环境变量，并移除自身。

& {
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-goose.ps1'
  if (-not (Test-Path -LiteralPath $lumoswitchLauncher -PathType Leaf)) {
    throw 'The optional Lumoswitch maintenance launcher is missing. Run persistent import again before cleanup.'
  }
  & powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File $lumoswitchLauncher --lumoswitch-clean
}

macOS / Linux

如果曾在 Goose Desktop 或 goose configure 中保存过 Key，先运行官方移除流程：

goose configure

选择 Custom Providers → Remove Custom Provider → Lumoswitch。官方流程会删除提供方文件，并从 Keychain（或禁用 Keychain 时的 secrets.yaml）移除对应 Key。

再运行下面的命令清除本文创建的专属文件与现有备份：

"$HOME/.local/bin/lumoswitch-goose" --lumoswitch-clean

这些路径都由本文专门为 Lumoswitch 创建；命令不会删除 Goose 的 config.yaml、会话、扩展或其他提供方。

Goose Desktop 是官方桌面应用，支持 macOS、Linux 和 Windows。它会看到同一份 lumoswitch.json，但不会读取 CLI 启动器里的 Key。要在 Desktop 使用，请打开 Settings → Models → Configure providers，选择 Lumoswitch 并保存 Key；Key 会进入系统 Keychain，Keychain 不可用时才回退到 secrets.yaml。

Desktop 只有永久接入，没有终端式临时命令，因为应用不会继承当前 Shell 的 LUMOSWITCH_GOOSE_API_KEY。删除时使用 Desktop 的 Delete Provider，或使用上面的 goose configure 流程，以便同时清理凭证。

Goose 没有单独维护一套 Lumoswitch 配置的官方 IDE 扩展；它可以作为 ACP Agent 接入支持 ACP 的编辑器。此时模型请求仍由 Goose 处理，继续使用同一自定义提供方。

验证与排查

API URL 必须指向 .../v1/chat/completions；本文会在 {{api_base_url}} 后追加该路径。
Goose 自定义提供方的 engine 使用 openai，表示 OpenAI-compatible 请求格式。
先测试普通消息，再验证工具调用、流式输出和长上下文。

参考：Goose 官方简介、自定义提供方和官方仓库。最近核验：2026-08-27。

维护者发布字段

平台 ID：goose
展示名称：Goose CLI
下游协议：openai-compatible
临时模式：关闭；从空白环境无法只靠单次命令注册完整自定义提供方，commandTemplate 不适用
永久策略：native
persistentCommandTemplate：复制「永久使用」代码框的完整内容
futureCommand：goose session start
展示顺序：130
最近核验：2026-08-27