# Goose Provider Setup

> **Last verified**: 2026-10-13 · 📄 Per official docs (goose v1.54.0)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ through the `Anthropic` provider · GPT ✅ and Chinese models ✅ through the OpenAI-compatible side · Gemini ❌ — QCode does not offer the Gemini series, please use Claude, GPT or a Chinese model |
| Protocol & Base URL | Anthropic Messages: `https://api.qcode.cc/api` · OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` |
| Where to configure | `goose configure` in the terminal, goose Desktop → Settings → Models, or environment variables (`ANTHROPIC_HOST`, `OPENAI_HOST`, `OPENAI_BASE_PATH`, `GOOSE_PROVIDER__HOST`) |
| Official docs | [goose-docs.ai — Configure LLM Provider](https://goose-docs.ai/docs/getting-started/providers) |

goose describes itself as "your native open source AI agent — desktop app, CLI, and API". It is now an Agentic AI Foundation project, so the documentation lives at `goose-docs.ai` (the former `block.github.io/goose` address only redirects) and the repository is `aaif-goose/goose`, while the Homebrew formula is still called `block-goose-cli`. The version referenced on this page is the stable release `v1.54.0`, published 2026-10-08.

## Which protocol

| Models you want | goose provider / API type | Endpoint you enter |
|---|---|---|
| Claude | built-in `Anthropic` provider (`ANTHROPIC_HOST`), or a custom provider whose API type is `Anthropic Compatible` | `https://api.qcode.cc/api` |
| GPT and Chinese models | built-in `OpenAI` provider (`OPENAI_HOST` + `OPENAI_BASE_PATH`), or a custom provider whose API type is `OpenAI Compatible` | `https://api.qcode.cc/openai/v1` (the request path is `/openai/v1/chat/completions`) |

**Never call Claude over the OpenAI-compatible endpoint.** QCode serves `claude-*` ids on the Anthropic Messages side only; the OpenAI side refuses them (`model_not_available_on_endpoint`). Keep two providers rather than one, and pick per session with `goose run --provider … --model …`. Details: [Endpoints & API paths](/docs/getting-started/endpoints-and-api-paths).

**The field is named HOST, not base_url.** goose asks for `ANTHROPIC_HOST`, `OPENAI_HOST` and `GOOSE_PROVIDER__HOST`. Enter the host plus the path prefix only — do not write `/v1/messages` into the field. On the OpenAI side the request path is a separate documented field: the official table describes `OPENAI_BASE_PATH` as "Request path appended to the host (defaults to v1/chat/completions)". The official documentation does not spell out how `ANTHROPIC_HOST` is joined with the messages path, so this page only states the QCode value and claims nothing as measured.

## Install

CLI, with Homebrew or the official script:

```bash
brew install block-goose-cli

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

goose update
goose --version
```

Desktop: on macOS use Homebrew or the download buttons; on Linux the official page offers `.deb`, `.rpm` and Flatpak packages:

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

## Configure Claude (Anthropic provider)

The interactive route follows the official prompts:

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

The variables the official environment-variables page groups under custom endpoints do the same job without the wizard:

```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"
```

In `config.yaml` (macOS/Linux: `~/.config/goose/config.yaml`) provider settings live in the `active_provider` and `providers` keys:

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

- The key does not belong in that file: the official docs state "Provider API keys do not go in config.yaml". Keep it in the keyring via `goose configure`, in `secrets.yaml`, or in the provider environment variable.
- Regional nodes: replace the host with `https://asia.qcode.cc/api` or `https://us.qcode.cc/api`. The same key works.
- Claude ids available on QCode: `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`. Billed per token; per-model rates are listed on https://qcode.cc/models

## Configure GPT and Chinese models (OpenAI compatible)

The built-in OpenAI provider "can connect to OpenAI's official API (api.openai.com) or any OpenAI-compatible endpoint", and the official guidance for such a gateway is to "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"
```

The alternative is to keep the documented default path and move the prefix into the host, `export OPENAI_HOST="https://api.qcode.cc/openai"` with `OPENAI_BASE_PATH` left at `v1/chat/completions`. Either way the request goes to the documented endpoint URL `https://api.qcode.cc/openai/v1/chat/completions`.

### As a named custom provider

Run `goose configure`, choose **Custom Providers**, then **Add A Custom Provider** (the menu line reads "Add a new OpenAI/Anthropic/Ollama compatible Provider"):

| Prompt | What to enter |
|---|---|
| API Type | `OpenAI Compatible (most common)` |
| Name | any name you like, e.g. `qcode` |
| API URL | `https://api.qcode.cc/openai/v1/chat/completions` — the official docs describe this prompt as "The base URL of the API endpoint", and the JSON example for the same field carries the full request path |
| Authentication Required | Yes, then a static API key |
| Available Models | comma-separated list of model names, e.g. `gpt-6.1-sol,gpt-5.6-terra,gpt-5.5,deepseek-v4.1-flash,glm-5.3,kimi-k3` |
| Streaming Support | enabled |

The provider reads its key from the environment variable you assigned to it. In the official wording, "Then use the api_key_env to set the key for your session", with the documented example:

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

Use your own provider name and key variable in place of `custom_corp_api` / `CUSTOM_CORP_API_API_KEY`. If you prefer to write the JSON file yourself, it goes in `macOS/Linux: ~/.config/goose/custom_providers/`. Note two things: "Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats." and the official examples only ever show `"engine": "openai"` — the docs publish no value for the Anthropic side, so create Anthropic-compatible custom providers through `goose configure` and let goose write that line.

Chinese model ids on QCode include `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` — see [Chinese models](/docs/usage/cn-models).

## Verify

```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." On `goose run`, `--provider` reads "Specify the provider to use for this session (overrides environment variable)" and `--model` reads "Specify the model to use for this session (overrides environment variable)".

Before you debug goose itself, confirm the endpoint:

```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"}]}'
```

A JSON body containing `content` means the endpoint side answered and the remaining problem is in goose's settings. This page was built from the official documentation; there was no test key, so no request here was measured against QCode.

## Troubleshooting / Known limitations

| Symptom or limit | What the official docs say, and the fix |
|---|---|
| Your model id is not offered in the `goose configure` list | "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." In Desktop the model picker lets you "choose Use custom model to enter a specific model name". |
| 404 on the OpenAI side | "A 404 usually means OPENAI_BASE_PATH is wrong for your proxy." QCode answers at `/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." Re-enter the key with `goose configure`. |
| Keyring errors in containers or headless use | goose "tries to use the system keyring (keychain on macOS) to store secrets by default"; if the keyring is unavailable, "please try setting secret key(s) via environment variables", or run `GOOSE_DISABLE_KEYRING=1 goose configure`. |
| Extra request headers | "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." |
| Model id rejected by QCode | QCode does not offer the Gemini series, and does not offer `gpt-6-luna` / `gpt-5.6-luna`; use other GPT ids (`gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-terra`) or a Claude / Chinese model. Haiku 4.5 must be entered with its full id `claude-haiku-4-5-20251001`. |
| 429 from the provider | Official: "goose may encounter a 429 error (rate limit exceeded) when interacting with LLM providers." Model lists: [Model selection](/docs/usage/model-selection); checks on the service side: [Troubleshooting](/docs/reference/troubleshooting). |

Billing is per token; per-model rates are listed on https://qcode.cc/models

## Related

- [Endpoints & API paths](/docs/getting-started/endpoints-and-api-paths) — protocol × model family
- [Tool compatibility](/docs/ide/tool-compatibility) — which tools take which protocol
- [OpenCode setup](/docs/ide/opencode) — another terminal agent on the same two endpoints
- [Crush setup](/docs/ide/crush) — same provider pair, a JSON config file instead of a wizard
- [Aider integration](/docs/ide/aider) — both endpoints as well, selected per model name
- [Model selection](/docs/usage/model-selection)
- [Chinese models](/docs/usage/cn-models)