# Goose-Provider einrichten

> **Zuletzt geprüft**: 2026-10-13 · 📄 Laut offizieller Dokumentation (goose v1.54.0)

## Auf einen Blick

| Punkt | Details |
|---|---|
| Nutzbare Modelle | Claude ✅ über den `Anthropic`-Provider · GPT ✅ und chinesische Modelle ✅ über die OpenAI-kompatible Seite · Gemini ❌: QCode bietet keine Gemini-Reihe, bitte Claude, GPT oder ein chinesisches Modell verwenden |
| Protokoll & Base URL | Anthropic Messages: `https://api.qcode.cc/api` · OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` |
| Wo eingerichtet wird | `goose configure` im Terminal; goose Desktop → Settings → Models; Umgebungsvariablen (`ANTHROPIC_HOST`, `OPENAI_HOST`, `OPENAI_BASE_PATH`, `GOOSE_PROVIDER__HOST`) |
| Offizielle Dokumentation | [goose-docs.ai — Configure LLM Provider](https://goose-docs.ai/docs/getting-started/providers) |

goose beschreibt sich selbst als "your native open source AI agent — desktop app, CLI, and API". Das Projekt gehört inzwischen zur Agentic AI Foundation: die Doku liegt auf `goose-docs.ai` (die frühere Adresse `block.github.io/goose` leitet nur noch weiter), das Repository ist `aaif-goose/goose`, die Homebrew-Formel heißt dagegen weiterhin `block-goose-cli`. Diese Seite steht im Einklang mit der stabilen Version `v1.54.0`, veröffentlicht am 2026-10-08.

## Welches Protokoll

| Gewünschte Modelle | Provider / API-Typ in goose | Eingetragene Adresse |
|---|---|---|
| Claude | eingebauter `Anthropic`-Provider (`ANTHROPIC_HOST`) oder Custom Provider mit API-Typ `Anthropic Compatible` | `https://api.qcode.cc/api` |
| GPT und chinesische Modelle | eingebauter `OpenAI`-Provider (`OPENAI_HOST` + `OPENAI_BASE_PATH`) oder Custom Provider mit API-Typ `OpenAI Compatible` | `https://api.qcode.cc/openai/v1` (Anfragepfad `/openai/v1/chat/completions`) |

**Rufen Sie Claude niemals über die OpenAI-kompatible Seite auf.** QCode liefert `claude-*` ausschließlich auf der Anthropic-Messages-Seite; die OpenAI-Seite lehnt diese IDs ab (`model_not_available_on_endpoint`). Legen Sie besser zwei Provider an und wählen Sie pro Sitzung mit `goose run --provider … --model …`. Details: [Endpunkte & API-Formate](/docs/getting-started/endpoints-and-api-paths).

**Das Feld heißt HOST, nicht base_url.** goose fragt `ANTHROPIC_HOST`, `OPENAI_HOST` und `GOOSE_PROVIDER__HOST`. Tragen Sie nur Host plus Pfad-Präfix ein — schreiben Sie kein `/v1/messages` in das Feld. Auf der OpenAI-Seite ist der Anfragepfad ein eigenes dokumentiertes Feld: Die Tabelle der Doku beschreibt `OPENAI_BASE_PATH` als "Request path appended to the host (defaults to v1/chat/completions)". Wie `ANTHROPIC_HOST` mit dem Nachrichtenpfad verbunden wird, sagt die offizielle Dokumentation nicht; diese Seite nennt deshalb nur den QCode-Wert und behauptet nichts als gemessen.

## Installation

CLI per Homebrew oder über das offizielle Skript:

```bash
brew install block-goose-cli

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

goose update
goose --version
```

Desktop: für macOS per Homebrew oder die Download-Buttons; für Linux bietet die offizielle Seite .deb-, .rpm- und Flatpak-Pakete:

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

## Claude einrichten (Anthropic-Provider)

Der interaktive Weg folgt den offiziellen Abfragen:

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

Ohne Assistenten gehen die Variablen, die die offizielle Umgebungsvariablen-Seite unter custom endpoints sammelt:

```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 der `config.yaml` (macOS/Linux: `~/.config/goose/config.yaml`) stehen Provider-Einstellungen unter `active_provider` und `providers`:

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

- Der Schlüssel gehört nicht in diese Datei — offiziell: "Provider API keys do not go in config.yaml". Speichern Sie ihn im Keyring (über `goose configure`), in `secrets.yaml` oder in der Provider-Umgebungsvariablen.
- Regionale Knoten: tauschen Sie den Host gegen `https://asia.qcode.cc/api` oder `https://us.qcode.cc/api`. Der gleiche Schlüssel bleibt gültig.
- Bei QCode verfügbare Claude-Modelle: `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`. Abgerechnet wird pro Token; die Preise je Modell stehen unter https://qcode.cc/models

## GPT und chinesische Modelle einrichten (OpenAI-kompatibel)

Die Doku sagt, der eingebaute OpenAI-Provider "can connect to OpenAI's official API (api.openai.com) or any OpenAI-compatible endpoint", und für ein solches Gateway gilt die offizielle Anweisung: "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"
```

Die Alternative: den dokumentierten Standardpfad lassen und das Präfix in den Host schieben — `export OPENAI_HOST="https://api.qcode.cc/openai"`, während `OPENAI_BASE_PATH` auf `v1/chat/completions` bleibt. Beide Formen zielen auf den dokumentierten Endpunkt `/openai/v1/chat/completions`.

### Als benannter Custom Provider

`goose configure` ausführen, **Custom Providers** wählen, dann **Add A Custom Provider** (im Menü steht "Add a new OpenAI/Anthropic/Ollama compatible Provider"):

| Abfrage | Eingabe |
|---|---|
| API Type | `OpenAI Compatible (most common)` |
| Name | Name nach Wahl, zum Beispiel `qcode` |
| API URL | `https://api.qcode.cc/openai/v1/chat/completions` — die Doku beschreibt diesen Schritt als "The base URL of the API endpoint", und im JSON-Beispiel desselben Feldes steht der komplette Anfragepfad |
| Authentication Required | Yes, danach ein statischer API key |
| Available Models | Kommagetrennte Modellnamen, z. B. `gpt-6.1-sol,gpt-5.6-terra,gpt-5.5,deepseek-v4.1-flash,glm-5.3,kimi-k3` |
| Streaming Support | einschalten |

Den Schlüssel liest der Provider aus der Umgebungsvariablen, die Sie ihm zugewiesen haben. Offiziell heißt es "Then use the api_key_env to set the key for your session", das Beispiel lautet:

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

Ersetzen Sie `custom_corp_api` und `CUSTOM_CORP_API_API_KEY` durch Ihre eigenen Namen. Wer die JSON-Datei selbst schreibt, legt sie in `macOS/Linux: ~/.config/goose/custom_providers/` ab. Zwei Hinweise: Offiziell gilt "Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats." — und in den offiziellen Beispielen taucht `engine` nur als `"engine": "openai"` auf. Für die Anthropic-Seite nennt die Doku keinen Wert; legen Sie Anthropic-kompatible Custom Provider daher über `goose configure` an und überlassen Sie goose diese Zeile.

Chinesische Modell-IDs bei QCode: `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` — siehe [Chinesische Modelle](/docs/usage/cn-models).

## Prüfen

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

Zu `goose info` sagt die Doku: "Shows goose information, including the version, configuration file location, session storage, and logs." Die Flags von `goose run` sind als "Specify the provider to use for this session (overrides environment variable)" und "Specify the model to use for this session (overrides environment variable)" beschrieben.

Prüfen Sie erst den Endpunkt, bevor Sie goose selbst untersuchen:

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

Steht in der Antwort ein JSON mit `content`, hat der Endpunkt geantwortet und die Ursache liegt in den Einstellungen von goose. Diese Seite entsteht ausschließlich aus der offiziellen Dokumentation; ohne Test-Key wurde hier keine Anfrage gegen QCode gemessen.

## Bekannte Grenzen

| Symptom oder Grenze | Was die Doku sagt, und was zu tun ist |
|---|---|
| Die Modell-ID fehlt in der Liste von `goose configure` | Offiziell: "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 gilt für die Modellauswahl: "choose Use custom model to enter a specific model name". |
| 404 auf der OpenAI-Seite | Offiziell: "A 404 usually means OPENAI_BASE_PATH is wrong for your proxy." Chat completions von QCode liegen unter `/openai/v1/chat/completions`. |
| `No api key passed in` | Offiziell: "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." Schlüssel mit `goose configure` neu erfassen. |
| Keyring-Fehler in Containern oder ohne Desktop-Umgebung | Offiziell gilt: goose "tries to use the system keyring (keychain on macOS) to store secrets by default"; ist der Keyring nicht verfügbar, gilt "please try setting secret key(s) via environment variables", oder Sie rufen `GOOSE_DISABLE_KEYRING=1 goose configure` auf. |
| Zusätzliche Request-Header | Offiziell: "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 lehnt eine Modell-ID ab | QCode bietet keine Gemini-Reihe und auch gpt-6-luna / gpt-5.6-luna nicht; nehmen Sie andere GPT-Modelle (gpt-6.1-sol / gpt-6-sol / gpt-5.6-terra) oder Claude bzw. ein chinesisches Modell. Haiku 4.5 nur als vollständige ID `claude-haiku-4-5-20251001`. |
| 429 | Offiziell: "goose may encounter a 429 error (rate limit exceeded) when interacting with LLM providers." Die Modelle stehen unter [Modellauswahl](/docs/usage/model-selection), die Prüfreihenfolge auf Serverseite unter [Fehlerbehebung](/docs/reference/troubleshooting). |

Preise in einem Satz: Abgerechnet wird pro Token, die Preise je Modell stehen unter https://qcode.cc/models

## Verwandte Seiten

- [Endpunkte & API-Formate](/docs/getting-started/endpoints-and-api-paths) — Protokoll × Modellfamilie
- [Kompatibilität der Werkzeuge](/docs/ide/tool-compatibility) — welches Werkzeug über welches Protokoll läuft
- [OpenCode einrichten](/docs/ide/opencode) — das gleiche Protokollpaar bei einem anderen Terminal-Agenten
- [Crush einrichten](/docs/ide/crush) — gleiche Provider, aber eine JSON-Datei statt Assistent
- [Aider einrichten](/docs/ide/aider) — beide Seiten, nach Modellname gewählt
- [Modellauswahl](/docs/usage/model-selection)
- [Chinesische Modelle](/docs/usage/cn-models)