# goose 接入 QCode

> **最后核实**：2026-10-13 · 📄 依据官方文档（goose v1.54.0）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（`Anthropic` provider）· GPT ✅ 与国产模型 ✅（OpenAI 兼容侧）· Gemini ❌：QCode 暂不提供 Gemini 系列，请改用 Claude、GPT 或国产模型 |
| 协议与 Base URL | Anthropic Messages：`https://api.qcode.cc/api` · OpenAI Chat Completions：`https://api.qcode.cc/openai/v1` |
| 配置入口 | 终端里的 `goose configure`；goose Desktop → Settings → Models；或环境变量（`ANTHROPIC_HOST`、`OPENAI_HOST`、`OPENAI_BASE_PATH`、`GOOSE_PROVIDER__HOST`） |
| 官方文档 | [goose-docs.ai — Configure LLM Provider](https://goose-docs.ai/docs/getting-started/providers) |

goose 对自己的描述是 "your native open source AI agent — desktop app, CLI, and API"。它现在归 Agentic AI Foundation，文档站已迁到 `goose-docs.ai`（原 `block.github.io/goose` 地址只剩跳转），仓库是 `aaif-goose/goose`，但 Homebrew 的 formula 名仍是 `block-goose-cli`。本页对齐的稳定版是 2026-10-08 发布的 `v1.54.0`。

## 用哪条协议

| 想用的模型 | goose 的 provider / API 类型 | 填进去的地址 |
|---|---|---|
| Claude | 内置 `Anthropic` provider（`ANTHROPIC_HOST`），或 API 类型选 `Anthropic Compatible` 的自定义 provider | `https://api.qcode.cc/api` |
| GPT 与国产模型 | 内置 `OpenAI` provider（`OPENAI_HOST` + `OPENAI_BASE_PATH`），或 API 类型选 `OpenAI Compatible` 的自定义 provider | `https://api.qcode.cc/openai/v1`（请求路径 `/openai/v1/chat/completions`） |

**绝不要用 OpenAI 兼容端点调 Claude。** QCode 只在 Anthropic Messages 端点上提供 `claude-*`，OpenAI 兼容端点会直接拒绝（`model_not_available_on_endpoint`）。请配两个 provider 而不是一个，每次会话用 `goose run --provider … --model …` 选。细节见[接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

**这些字段叫 HOST，不叫 base_url。** goose 问的是 `ANTHROPIC_HOST`、`OPENAI_HOST`、`GOOSE_PROVIDER__HOST`。只填主机加路径前缀——不要把 `/v1/messages` 写进字段。OpenAI 侧的请求路径另有官方字段：官方表格里 `OPENAI_BASE_PATH` 的说明是 "Request path appended to the host (defaults to v1/chat/completions)"。至于 `ANTHROPIC_HOST` 与消息路径具体怎么拼，官方文档没有写明，因此本页只给出 QCode 侧的取值，不声称任何实测结果。

## 安装

CLI 用 Homebrew 或官方脚本：

```bash
brew install block-goose-cli

# 或
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

goose update
goose --version
```

桌面版：macOS 用 Homebrew 或下载按钮；Linux 官方提供 .deb / .rpm / Flatpak 包：

```bash
brew install --cask block-goose
```

## 配置 Claude（Anthropic provider）

交互式按官方提示走：

```bash
goose configure
# Configure Providers (Change provider or update credentials)  -> 选 Anthropic
# Provider Anthropic requires ANTHROPIC_API_KEY, please enter a value  -> 你的 QCode 密钥
# Enter your desired ANTHROPIC_HOST or press Enter to use the default.  -> https://api.qcode.cc/api
```

不想走向导，就用官方环境变量页里归在自定义端点下的那几个变量：

```bash
export GOOSE_PROVIDER="anthropic"
export GOOSE_MODEL="claude-sonnet-5"
export GOOSE_PROVIDER__TYPE="anthropic"
export GOOSE_PROVIDER__HOST="https://api.qcode.cc/api"
export GOOSE_PROVIDER__API_KEY="cr_your_qcode_key"
```

`config.yaml`（macOS/Linux 为 `~/.config/goose/config.yaml`）里 provider 设置放在 `active_provider` 与 `providers` 两个键下：

```yaml
active_provider: anthropic
providers:
  anthropic:
    enabled: true
    model: claude-sonnet-5
    configured: true
```

- 密钥不要写进这个文件：官方原句是 "Provider API keys do not go in config.yaml"。请存进 keyring（由 `goose configure` 写入）、`secrets.yaml`，或用 provider 的环境变量。
- 区域节点：把 host 换成 `https://asia.qcode.cc/api` 或 `https://us.qcode.cc/api`，同一把密钥照用。
- QCode 侧可用的 Claude 模型：`claude-sonnet-5`、`claude-sonnet-5-5`、`claude-opus-5`、`claude-opus-5-5`、`claude-haiku-5-5`、`claude-haiku-4-5-20251001`、`claude-sonnet-4-6`、`claude-fable-5`、`claude-fable-5-1`。按 token 计费，各模型单价见 https://qcode.cc/models

## 配置 GPT 与国产模型（OpenAI 兼容）

官方说法是内置 OpenAI provider "can connect to OpenAI's official API (api.openai.com) or any OpenAI-compatible endpoint"，而对这类网关，官方给的配法是 "set OPENAI_HOST to your proxy's root (no trailing path) and OPENAI_BASE_PATH to the path it serves (usually v1/chat/completions)"：

```bash
export OPENAI_API_KEY="cr_your_qcode_key"
export OPENAI_HOST="https://api.qcode.cc"
export OPENAI_BASE_PATH="openai/v1/chat/completions"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-6.1-sol"
```

另一种写法是保留官方默认路径、把前缀挪进 host：`export OPENAI_HOST="https://api.qcode.cc/openai"`，`OPENAI_BASE_PATH` 留作默认的 `v1/chat/completions`。两种写法最终都指向官方端点 `/openai/v1/chat/completions`。

### 具名自定义 provider

运行 `goose configure`，选 **Custom Providers**，再选 **Add A Custom Provider**（菜单原句 "Add a new OpenAI/Anthropic/Ollama compatible Provider"）：

| 交互提示 | 填什么 |
|---|---|
| API Type | `OpenAI Compatible (most common)` |
| Name | 自己起名，例如 `qcode` |
| API URL | `https://api.qcode.cc/openai/v1/chat/completions`——官方把这一步写成 "The base URL of the API endpoint"，而同一个字段的 JSON 示例里带的就是完整请求路径 |
| Authentication Required | 选 Yes，再填静态 API key |
| Available Models | 逗号分隔的模型名列表，如 `gpt-6.1-sol,gpt-5.6-terra,gpt-5.5,deepseek-v4.1-flash,glm-5.3,kimi-k3` |
| Streaming Support | 打开 |

密钥由你给这个 provider 指定的环境变量提供。官方原句是 "Then use the api_key_env to set the key for your session"，示例是：

```bash
export CUSTOM_CORP_API_API_KEY="your-api-key"
goose session start --provider custom_corp_api
```

把 `custom_corp_api` 与 `CUSTOM_CORP_API_API_KEY` 换成你自己起的名字。若你愿意手写 JSON，文件放在 `macOS/Linux: ~/.config/goose/custom_providers/`。两点提醒：官方写明 "Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats."；而官方示例里 `engine` 只出现过 `"engine": "openai"`，Anthropic 一侧该填什么官方没给，所以 Anthropic 兼容的自定义 provider 请用 `goose configure` 生成，让 goose 自己写这一行。

QCode 的国产模型 ID：`deepseek-v4.1-flash`、`deepseek-v4-flash`、`deepseek-v4-pro`、`glm-5.3`、`glm-5.2`、`qwen3.8-max`、`qwen3.8-flash`、`qwen3.7-plus`、`kimi-k3`，详见[国产模型接入](/docs/usage/cn-models)。

## 验证

```bash
goose info
goose run --provider anthropic --model claude-sonnet-5 -t "ping"
```

官方对 `goose info` 的说明是 "Shows goose information, including the version, configuration file location, session storage, and logs."；`goose run` 的 `--provider` 与 `--model` 分别是 "Specify the provider to use for this session (overrides environment variable)" 和 "Specify the model to use for this session (overrides environment variable)"。

先排除端点侧的问题，再看 goose 的设置：

```bash
KEY="cr_your_qcode_key"
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

返回的 JSON 里出现 `content` 就说明端点侧正常，剩下的问题在 goose 自己的配置。本页只依据官方文档整理，没有测试密钥，因此页内任何请求都没有在 QCode 上实测过。

## 已知限制

| 现象或限制 | 官方怎么说，怎么办 |
|---|---|
| `goose configure` 的模型列表里没有你要的 ID | 官方原句："goose configure doesn't support entering custom model names. To use a model not in the provider's list, use goose Desktop or edit the GOOSE_MODEL variable in your config.yaml directly." Desktop 的模型选择器可以 "choose Use custom model to enter a specific model name"。 |
| OpenAI 侧报 404 | 官方原句："A 404 usually means OPENAI_BASE_PATH is wrong for your proxy." QCode 的 chat completions 在 `/openai/v1/chat/completions`。 |
| `No api key passed in` | 官方原句："goose does not read provider API keys from config.yaml. A key placed there is ignored, which typically surfaces as an authentication failure such as No api key passed in." 用 `goose configure` 重新录入密钥。 |
| 容器或无桌面环境里密钥环报错 | 官方原句：goose "tries to use the system keyring (keychain on macOS) to store secrets by default"，取不到密钥环时 "please try setting secret key(s) via environment variables"，或运行 `GOOSE_DISABLE_KEYRING=1 goose configure`。 |
| 需要额外请求头 | 官方原句："Currently, custom headers can only be defined for OpenAI compatible providers in the CLI. For Anthropic or Ollama compatible providers, edit the provider configuration file after creation." |
| QCode 不受理的模型 ID | QCode 暂不提供 Gemini 系列，也不提供 gpt-6-luna / gpt-5.6-luna，请改用其他 GPT 模型（gpt-6.1-sol / gpt-6-sol / gpt-5.6-terra）或 Claude、国产模型。Haiku 4.5 的 ID 必须写全称 `claude-haiku-4-5-20251001`。 |
| 429 | 官方原句："goose may encounter a 429 error (rate limit exceeded) when interacting with LLM providers." 模型清单见[模型怎么选](/docs/usage/model-selection)，站内排查顺序见[故障排查](/docs/reference/troubleshooting)。 |

计费只有一句：按 token 计费，各模型单价见 https://qcode.cc/models

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)：协议 × 模型族
- [工具兼容总览](/docs/ide/tool-compatibility)：哪些工具走哪条协议
- [OpenCode 接入](/docs/ide/opencode)：同为终端 agent，两个端点一致
- [Crush 接入](/docs/ide/crush)：同样是两个 provider，但改 JSON 配置
- [Aider 集成](/docs/ide/aider)：两个端点都支持，按模型名选
- [模型怎么选](/docs/usage/model-selection)
- [国产模型接入](/docs/usage/cn-models)