goose Custom Provider 设置

goose 官方为 Custom Provider 提供 Desktop、CLI 和配置文件三条路径。TokenHub 使用 OpenAI Compatible；在 goose 的自定义 Provider 中，API URL 按官方 JSON 结构填写完整 Chat Completions 地址 https://us-api.tokenhub.com/v1/chat/completions。

goose Desktop 的官方入口

1. 点击左上角侧栏按钮。
2. 进入 Settings → Models。
3. 点击 Configure providers。
4. 滚动到底部，点击 Add Custom Provider。
5. Provider Type 选择 OpenAI Compatible。
6. Display Name 填 TokenHub。
7. API URL 填 https://us-api.tokenhub.com/v1/chat/completions。
8. 保持 This provider requires an API key 开启，填入 TokenHub API Key。Desktop 会把 Key 放进系统 keychain；keyring 不可用时写入 secrets.yaml。
9. Available Models 填用英文逗号分隔的 TokenHub Model ID。
10. 开启 Streaming Support，点击 Create Provider。

Desktop 当前不能添加自定义 headers；需要额外 header 时，应创建后再编辑 Provider JSON。

goose CLI 的官方入口

运行：

goose configure

随后严格按菜单选择：

1. Custom Providers (Add custom provider with compatible API)。
2. Add A Custom Provider。
3. API Type 选择 OpenAI Compatible。
4. Name 填 TokenHub，API URL 填完整 Chat Completions 地址。
5. Authentication Required 选 Yes，再选 Static API key 并粘贴 TokenHub Key。
6. Available Models 输入逗号分隔的准确 Model ID。
7. 开启 Streaming Support；只有确实需要时才添加 Custom Headers。

CLI 还支持 Command (refreshable) 获取短期凭证，但普通 TokenHub API Key 不需要这条路径。

核对 goose 生成的 Provider 文件

macOS/Linux 文件位于 ~/.config/goose/custom_providers/；Windows 位于 %APPDATA%\Block\goose\config\custom_providers\。生成结果应与以下关键字段一致：

{
  "name": "tokenhub",
  "engine": "openai",
  "display_name": "TokenHub",
  "api_key_env": "TOKENHUB_API_KEY",
  "base_url": "__API_BASE_URL__/v1/chat/completions",
  "models": [
    {
      "name": "YOUR_TOKENHUB_MODEL_ID",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

手写 JSON 时才需要 api_key_env；通过 Desktop/CLI 输入的静态 Key 由 goose 安全存储。context_limit 必须替换成模型真实上限。

切换模型并让变更生效

Desktop 进入 Settings → Models → Switch models，选择 TokenHub Provider 和模型，点击 Select model。修改自定义 Provider 后，官方说明变更在下一个 goose session 生效，因此不要用旧会话判断配置失败。

新会话先执行只读代码任务，在 TokenHub 日志确认完整 /v1/chat/completions 路径。404 时核对 API URL；模型不可见时检查逗号分隔列表或 models[].name；能聊天但 Agent 不执行工具时，换用能够返回结构化 tool calls 的模型。

官方资料

• goose：Configure LLM Provider