# Goose: настройка ИИ-агента через RouterAI (Claude, GPT-6, DeepSeek)

## Goose

[Goose](https://github.com/aaif-goose/goose) — открытый (Apache-2.0) ИИ-агент, который не только подсказывает код, но и сам выполняет задачи: создаёт и правит файлы, запускает команды, тесты и сборку. Работает как Desktop-приложение и как CLI, а возможности расширяются через MCP-серверы (расширения). Проект перешёл под крыло Agentic AI Foundation (AAIF); на момент написания актуальна версия 1.55.0.

Goose умеет работать с любым OpenAI-совместимым endpoint, поэтому к нему легко подключить RouterAI: одним ключом доступны Claude, GPT, DeepSeek и другие модели из [каталога](/models "каталог моделей RouterAI"), работа из России без VPN, оплата в рублях.

## Требования

- macOS, Linux или Windows (Desktop и CLI доступны на всех трёх платформах)
- API-ключ из [личного кабинета](/settings/keys "личного кабинета") RouterAI
- Модель с поддержкой вызова инструментов (tool calling): Goose строит работу агента на нём. Подходят все модели из раздела «Выбор модели» ниже

## Установка

### Desktop

- **macOS:** скачайте приложение со [страницы установки](https://goose-docs.ai/docs/getting-started/installation "документация Goose: установка") или выполните `brew install --cask block-goose`
- **Linux (Debian/Ubuntu):** скачайте `.deb` со страницы релизов и выполните `sudo dpkg -i goose_*.deb`; для Fedora/RHEL есть `.rpm`, также доступен Flatpak
- **Windows:** скачайте zip-архив, распакуйте и запустите исполняемый файл

### CLI

macOS, Linux и Windows (Git Bash, MSYS2, WSL):

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

Без интерактивной настройки: `CONFIGURE=false bash` вместо `bash`. Через Homebrew: `brew install block-goose-cli`. Обновление — `goose update`.

Если установщик предупредил, что `goose` не в `PATH`, добавьте каталог `~/.local/bin`:

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
goose --version
```

## Подключение к RouterAI

В Goose три способа подключить RouterAI: custom provider в Desktop (удобнее всего), встроенный провайдер OpenAI через переменные окружения и custom provider через CLI или JSON-файл. Для всех способов:

| Параметр | Значение |
| --- | --- |
| Base URL (API URL) | `https://routerai.ru/api/v1` |
| API-ключ | ключ из личного кабинета, `sk-xxxxxxxxxxxxxxxx` |
| Формат API | OpenAI Compatible (Chat Completions) |

### Способ 1: Desktop, Add a custom provider

При первом запуске Goose показывает экран «Welcome to goose». Если провайдер уже был настроен, откройте боковое меню → **Settings** → вкладка **Models** → **Configure providers**.

![Goose Desktop: выбор Connect to a Provider и пункт Add a custom provider](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/931029c93474682e9885e7e4b4479f5c.png)

1. Нажмите **Connect to a Provider**, затем **Add a custom provider**.
2. В окне **Add Custom Provider** выберите **Configure manually** (вариант **Start from a provider template** подставляет настройки известных провайдеров, для RouterAI он не нужен).

В форме оставьте **Provider Type** = `OpenAI Compatible` и заполните поля (номера совпадают с метками на кадре):

1. **Display Name** — `RouterAI`.
2. **API URL** — `https://routerai.ru/api/v1`. Поле **API Base Path** оставьте пустым.

![Goose Desktop: форма Add Custom Provider, поля Display Name и API URL](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/2c2cd42a0326d52b2c8511e477dc13fc.png)

Ниже в той же форме (номера совпадают с метками на втором кадре):

1. Включите флажок **This provider requires an API key** и вставьте ключ в поле **API Key**.
2. В **Available Models** перечислите модели через запятую, например `anthropic/claude-sonnet-5.5, anthropic/claude-haiku-5.5, deepseek/deepseek-v4.1-flash, openai/gpt-6-luna`.
3. Оставьте включённым **Provider supports streaming responses** и нажмите **Create Provider**.

![Goose Desktop: поля API Key, Available Models и кнопка Create Provider](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/3c3693c61dbebd867ef43e5d021f0d9f.png)

После создания Goose покажет «Connected to RouterAI» и кнопку **Get Started**. Ключ Desktop хранит в системной связке ключей (или в `secrets.yaml`, если связка недоступна), а настройки провайдера — в файле `custom_routerai.json` в каталоге `~/.config/goose/custom_providers/`.

### Способ 2: встроенный провайдер OpenAI и переменные окружения

Подходит для CLI и скриптов. Провайдер OpenAI строит адрес запроса из двух частей: `OPENAI_HOST` (корень прокси) и `OPENAI_BASE_PATH` (по умолчанию `v1/chat/completions`). Для RouterAI достаточно указать только хост:

```bash
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
export OPENAI_HOST="https://routerai.ru/api"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="anthropic/claude-sonnet-5.5"
```

Запрос уйдёт на `https://routerai.ru/api/v1/chat/completions`. Равноценный вариант: `OPENAI_HOST="https://routerai.ru/api/v1"` вместе с `OPENAI_BASE_PATH="chat/completions"`. Не смешивайте: `/v1` в хосте и `v1/...` в пути дадут двойной `/v1/v1`.

> ⚠ Ключ для провайдеров Goose берёт из переменных окружения или связки ключей. Ключ, записанный в `config.yaml`, игнорируется.

Чтобы настройки не вводить каждый раз, добавьте `export` в `~/.zshrc` или `~/.bashrc`. Переменные `GOOSE_PROVIDER` и `GOOSE_MODEL` имеют приоритет над `config.yaml` для текущего процесса.

### Способ 3: custom provider через CLI

Удобно, если нужно несколько endpoint'ов или отдельное имя в списке провайдеров. Запустите `goose configure`, выберите **Custom Providers** → **Add A Custom Provider** и ответьте на вопросы: **API Type** (`OpenAI Compatible`), **Name**, **API URL** (`https://routerai.ru/api/v1`), **Authentication Required**, **Available Models**, **Streaming Support**.

Тот же результат даёт JSON-файл `~/.config/goose/custom_providers/routerai.json` (Windows: `%APPDATA%\Block\goose\config\custom_providers\`):

```json
{
  "name": "routerai",
  "engine": "openai",
  "display_name": "RouterAI",
  "description": "RouterAI OpenAI-compatible gateway",
  "api_key_env": "ROUTERAI_API_KEY",
  "base_url": "https://routerai.ru/api/v1",
  "models": [
    { "name": "anthropic/claude-sonnet-5.5", "context_limit": 1000000 },
    { "name": "deepseek/deepseek-v4.1-flash", "context_limit": 1048576 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}
```

Ключ передаётся через переменную из `api_key_env`:

```bash
export ROUTERAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
goose run --provider routerai --model anthropic/claude-sonnet-5.5 -t "Привет!"
```

## Выбор модели

Все четыре модели ниже проверены в связке с Goose: ответ получен, инструменты (создание файла, shell) вызываются. Актуальные идентификаторы и цены — в [каталоге RouterAI](/models "каталог моделей RouterAI").

| Модель | Для чего |
| --- | --- |
| `anthropic/claude-sonnet-5.5` | основная модель для кода и многошаговых задач агента, контекст 1 млн токенов |
| `anthropic/claude-haiku-5.5` | быстрые и недорогие правки, вопросы по коду |
| `openai/gpt-6-luna` | альтернатива из семейства GPT-6 для повседневных задач |
| `deepseek/deepseek-v4.1-flash` | экономичный вариант для больших объёмов работы |

Сменить модель в Desktop: боковое меню → **Settings** → **Models** → **Switch models**, затем выберите провайдера RouterAI и модель из списка (или **Use custom model**, чтобы ввести идентификатор вручную). В CLI модель для одной сессии задаётся флагом `--model`.

![Goose Desktop: Settings, вкладка Models с провайдером RouterAI и кнопками Switch models и Configure providers](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/810fdae15b9003ce697dcfc94703b1f0.png)

## Проверка подключения

Сначала убедитесь, что ключ и endpoint работают:

```bash
curl https://routerai.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-5.5", "max_tokens": 64, "messages": [{"role": "user", "content": "Привет!"}]}'
```

Затем дайте Goose простую задачу, которая требует инструментов. В CLI:

```bash
goose run --no-session -t "Создай файл hello.txt с текстом RouterAI works и прочитай его"
```

![Goose CLI: goose run через провайдер openai с OPENAI_HOST RouterAI, агент создаёт и читает файл](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/a2ce95228b950673c357d8413e50dca4.png)

В Desktop введите тот же запрос в чате. Если подключение настроено верно, агент вызовет инструменты записи файла и shell, а в ответе вернёт содержимое файла.

![Goose Desktop: агент создаёт файл и читает его через RouterAI, модель anthropic/claude-sonnet-5.5](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/e57a34a76a73df7284de3f15b896cdcf.png)

> Счётчики стоимости в интерфейсе Goose не отражают списания в рублях. Фактический расход смотрите в личном кабинете RouterAI.

## MCP-расширения

Расширения Goose построены на Model Context Protocol, поэтому к агенту можно подключить любой MCP-сервер. Встроенные расширения (Developer, Analyze, Summon, Skills и другие) включены по умолчанию и дают агенту работу с файлами и командами.

В Desktop откройте боковое меню → **Extensions** → **Add custom extension**. Укажите **Extension Name**, **Type** (`STDIO` для локального сервера), **Command** (например, `npx -y @modelcontextprotocol/server-filesystem /path`), при необходимости **Timeout** и **Environment Variables**. В CLI то же делает `goose configure` → **Add Extension**. Список готовых серверов — в [каталоге расширений](https://goose-docs.ai/docs/getting-started/using-extensions "документация Goose: расширения").

![Goose Desktop: форма Add custom extension с полями Extension Name, Type, Command, Timeout и Environment Variables](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/e0b98ed70d1edb5cee53cb5d0992e9d2.png)

Выбор модели влияет на работу с расширениями: чем лучше модель вызывает инструменты, тем надёжнее агент использует MCP-серверы. Для сложных цепочек берите `anthropic/claude-sonnet-5.5`.

## Решение проблем

### 404 Not Found

Адрес запроса собран неверно. Текст ошибки содержит итоговый URL: например, `https://routerai.ru/api/v1/v1/chat/completions` значит, что `/v1` указан и в хосте, и в `OPENAI_BASE_PATH`. Используйте пару `OPENAI_HOST=https://routerai.ru/api` без `OPENAI_BASE_PATH` или `https://routerai.ru/api/v1` + `chat/completions`. В custom provider указывайте `https://routerai.ru/api/v1` в **API URL**.

### 401 Unauthorized

Ключ не дошёл до запроса. Проверьте, что `OPENAI_API_KEY` экспортирован в том же терминале, откуда запускается `goose`, и не пуст. Ключ в `config.yaml` Goose игнорирует. В Desktop заново введите ключ в **Settings** → **Models** → **Configure providers** и перезапустите приложение.

### Error missing required key

Для custom provider из JSON-файла не задана переменная из `api_key_env`. Выполните `export ROUTERAI_API_KEY="..."` до запуска `goose` (имя переменной должно совпадать с полем `api_key_env`).

### Model not found (400)

Идентификатор модели написан неверно или такой модели нет. Ошибка перечисляет доступные модели; сверьте точный id с [каталогом](/models "каталог моделей RouterAI"), id всегда вида `провайдер/модель`.

### Агент отвечает, но не выполняет действий

Модель не поддерживает вызов инструментов. Goose использует tool calling, поэтому выбирайте модели из раздела «Выбор модели».

### 402 Payment Required

Недостаточно средств на балансе. Пополните баланс в разделе [Биллинг](/settings/billing "Биллинг").

## Что дальше

- [Каталог моделей](/models "Каталог моделей") — выберите модель под задачу
- [Аутентификация](/docs/guides/overview/authentication "Аутентификация") — управление API-ключами и безопасность
- [Agent Harness](/pages/agent-harness "Agent Harness") — как устроена обвязка ИИ-агента
- [Hermes Agent через RouterAI](/pages/hermes-agent-routerai "Hermes Agent") и [OpenHands через RouterAI](/pages/openhands-routerai "OpenHands") — другие агенты
- [Вайб-кодинг в Claude Code](/pages/vibe-coding-claude-code "Claude Code") — CLI-агент Anthropic через RouterAI
- [Документация Goose](https://goose-docs.ai/docs/getting-started/providers "документация Goose: провайдеры") — провайдеры, расширения, рецепты