# Настройка Goose

> **Последняя проверка**: 2026-10-13 · 📄 По официальной документации (goose v1.54.0)

## Кратко

| Параметр | Значение |
|---|---|
| Доступные модели | Claude ✅ (provider `Anthropic`) · 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`; formula в Homebrew при этом по-прежнему называется `block-goose-cli`. Страница сверена со стабильной версией `v1.54.0`, опубликованной 2026-10-08.

## Какой протокол

| Нужные модели | Provider / тип API в goose | Что вводить |
|---|---|---|
| Claude | встроенный provider `Anthropic` (`ANTHROPIC_HOST`) или custom provider с типом API `Anthropic Compatible` | `https://api.qcode.cc/api` |
| GPT и китайские модели | встроенный provider `OpenAI` (`OPENAI_HOST` + `OPENAI_BASE_PATH`) или custom provider с типом API `OpenAI Compatible` | `https://api.qcode.cc/openai/v1` (путь запроса `/openai/v1/chat/completions`) |

**Никогда не вызывайте Claude через OpenAI-совместимую сторону.** QCode отдаёт `claude-*` только на стороне Anthropic Messages; OpenAI-сторона отклоняет такие ID (`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
```

Desktop: для macOS — Homebrew или кнопки загрузки, а для Linux официальная страница предлагает пакеты .deb / .rpm / Flatpak:

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

## Настройка Claude (provider Anthropic)

Интерактивный путь повторяет официальные запросы:

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

Вместо мастера можно взять переменные, которые официальная страница про переменные окружения относит к custom endpoints:

```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'а.
- Региональные узлы: замените хост на `https://asia.qcode.cc/api` или `https://us.qcode.cc/api`; ключ остаётся тот же.
- Модели Claude, доступные в 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`. Оплата за токены; цены по моделям указаны на 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"
```

Второй вариант — оставить официальный путь по умолчанию и перенести префикс в хост: `export OPENAI_HOST="https://api.qcode.cc/openai"`, а `OPENAI_BASE_PATH` оставить равным `v1/chat/completions`. Оба варианта ведут к задокументированному эндпоинту `/openai/v1/chat/completions`.

### Как именованный custom 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 в документации нет, поэтому custom provider типа Anthropic создавайте через `goose configure`, чтобы goose сам записал эту строку.

ID китайских моделей 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` — см. [Китайские модели](/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` описаны как "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.

## Известные ограничения

| Симптом или ограничение | Что говорит документация и что делать |
|---|---|
| Нужного ID модели нет в списке `goose configure` | Официально: "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". |
| 404 на OpenAI-стороне | Официально: "A 404 usually means OPENAI_BASE_PATH is wrong for your proxy." Chat completions QCode находятся на `/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`. |
| Ошибки keyring в контейнере или без графического окружения | Официально goose "tries to use the system keyring (keychain on macOS) to store secrets by default"; если keyring недоступен — "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 нужно полное имя `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). |

Один абзац про оплату: начисление за токены, цены по моделям указаны на https://qcode.cc/models

## Похожие материалы

- [Эндпоинты и форматы API](/docs/getting-started/endpoints-and-api-paths) — протокол × семейство моделей
- [Совместимость инструментов](/docs/ide/tool-compatibility) — какой инструмент по какому протоколу работает
- [Настройка OpenCode](/docs/ide/opencode) — тот же набор из двух протоколов у другого терминального агента
- [Настройка Crush](/docs/ide/crush) — те же два provider, но через JSON-файл
- [Интеграция Aider](/docs/ide/aider) — обе стороны выбираются по имени модели
- [Выбор модели](/docs/usage/model-selection)
- [Китайские модели](/docs/usage/cn-models)