Goose Provider Setup

Point goose's Anthropic and OpenAI-compatible providers at QCode: which HOST field takes which URL, and what goose configure cannot do

Need an API key? Sign up →·Endpoints & base URLs →

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

At a glance¶

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¶

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.

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:

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:

brew install --cask block-goose

Configure Claude (Anthropic provider)¶

The interactive route follows the official prompts:

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:

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:

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)":

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"):

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:

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.

Verify¶

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:

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¶

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

Related¶

• Endpoints & API paths — protocol × model family
• Tool compatibility — which tools take which protocol
• OpenCode setup — another terminal agent on the same two endpoints
• Crush setup — same provider pair, a JSON config file instead of a wizard
• Aider integration — both endpoints as well, selected per model name
• Model selection
• Chinese models

Enterprise →