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

> **Последняя проверка**: 2026-09-18 · 📄 По официальной документации (OpenClaw v2026.9.4, выпуск 2026-09-11)

## Кратко

| Параметр | Описание |
|---|---|
| Доступные модели | Claude ✅ (протокол Anthropic) · GPT ✅ · китайские модели ✅ · Gemini ⚠️ (адаптер `google-generative-ai` в апстриме есть, в этом обзоре не проверен) |
| Протокол и Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Где настраивается | `~/.openclaw/openclaw.json` (JSON5, горячая перезагрузка) или мастер `openclaw onboard` |
| Официальная документация | [Custom Providers](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) · [docs.openclaw.ai](https://docs.openclaw.ai) |

OpenClaw — это **открытый AI-ассистент, который работает на вашем собственном устройстве**: self-hosted процесс Gateway подключается к Discord, Telegram, Slack, iMessage и другим каналам, есть нативные приложения для macOS / Windows / Linux. **Это не редактор кода** — страница здесь потому, что его часто используют как «личный шлюз к нескольким моделям», и потому что он официально поддерживает любые OpenAI / Anthropic-совместимые эндпоинты.

## Предварительные требования

- Установленный OpenClaw (официальный установщик `curl -fsSL https://openclaw.ai/install.sh | bash`; при установке из npm нужен Node 24.16+, официально рекомендован 26+, см. [README](https://github.com/openclaw/openclaw#readme)).
- Ключ QCode.cc с префиксом `cr_` (создаётся в [консоли](https://qcode.cc/dashboard)). Аккаунты у внешних вендоров **не нужны**.
- Аккаунт самого OpenClaw тоже не нужен: все модели берутся из настроенных провайдеров.

## Настройка

### Маршрут A: править файл конфигурации (рекомендуется)

Добавьте блок `models.providers` в `~/.openclaw/openclaw.json`. Файл в формате JSON5 (комментарии и висячие запятые разрешены), Gateway перечитывает его автоматически, без перезапуска:

```json5
{
  models: {
    mode: "merge", // keep built-in providers, append QCode
    providers: {
      qcode: {
        baseUrl: "https://api.qcode.cc/api",
        apiKey: "${QCODE_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text", "image"] },
        ],
      },
      qcode_openai: {
        baseUrl: "https://api.qcode.cc/openai/v1",
        apiKey: "${QCODE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.6", name: "GPT-5.6" },
          { id: "glm-5.3", name: "GLM-5.3" },
        ],
      },
    },
  },
}
```

Три замечания (по официальной документации [custom-providers](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md)):

- `apiKey` поддерживает подстановку `${ENV_VAR}`; апстрим рекомендует ссылки на секреты и переменные окружения вместо литерального ключа.
- `api` — адаптер запросов: для ветки Anthropic это `anthropic-messages`, для OpenAI — `openai-completions`. Если указать только `baseUrl` без `api`, применяется `openai-completions`.
- Модель принимает изображения (vision) только при явном `input: ["text", "image"]`, иначе картинки передаются как текстовые ссылки.

### Маршрут B: Custom Provider в мастере onboard

```bash
openclaw onboard --install-daemon
```

В списке провайдеров выберите **Custom Provider** (если его нет в начале — в разделе **More…**) и введите base URL, API-ключ, совместимость и ID модели. Мастер перед сохранением выполняет реальный запрос (официальная формулировка: *verifies a real reply before saving*) — опечатка в URL всплывёт сразу.

Неинтерактивный эквивалент (в скрипте), на примере модели Claude:

```bash
openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.qcode.cc/api" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "$QCODE_API_KEY" \
  --custom-compatibility anthropic
```

🔴 Два написания различаются: у флага мастера значение `anthropic` (`--custom-compatibility anthropic`), а в конфиге у поля `api` — `anthropic-messages` (см. [документацию onboard](https://github.com/openclaw/openclaw/blob/main/docs/cli/onboard.md)).

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

1. На маршруте B мастер уже проверил всё сам (реальный запрос перед сохранением).
2. После маршрута A отправьте ассистенту что-нибудь простое вроде `ping`. Если не работает — сначала проверьте синтаксис JSON5 в `~/.openclaw/openclaw.json` (комментарии и лишние запятые ломают его).
3. Проверить отдельно путь и доставку ключа:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $QCODE_API_KEY"
# → 401 = ключ недействителен; любой код не-JSON-ошибки = путь достижим
```

4. Каждый запрос (в том числе от OpenClaw) попадает в [probe.qcode.cc](https://probe.qcode.cc) — введите ключ, чтобы увидеть модель и код ответа. Не помогает? Пройдите чек-лист в [устранении неполадок](/docs/reference/troubleshooting).

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

- **О форме Base URL**: в обоих официальных примерах `anthropic-messages` (Synthetic, MiniMax) `baseUrl` указывается **без `/v1`** (например `https://api.minimax.io/anthropic`), поэтому на этой странице — `https://api.qcode.cc/api`. Какой именно путь дописывает OpenClaw, документация дословно не описывает, и вживую мы это не проверяли. Если запросы дают 404, укажите полный путь `https://api.qcode.cc/api/v1/messages`.
- Для адаптера `openai-responses` официальное условие — поддержка `/v1/responses` на бэкенде. У QCode эта ветка обслуживает только семейство GPT; китайские модели направляйте через `openai-completions` (матрица протоколов: [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths)).
- На не-прямых эндпоинтах `anthropic-messages` OpenClaw подавляет beta-заголовки Anthropic (описанное поведение) — это полезно для сторонних шлюзов. Если в другом инструменте вы видите 400 из-за `anthropic-beta`, это не проблема OpenClaw.
- Ветка Gemini (`google-generative-ai`) есть в официальном перечне, но форма baseUrl для эндпоинта QCode `/gemini` в этом обзоре не проверялась — примера нет.
- Официальная документация живёт в ветке `main` на GitHub; docs.openclaw.ai может чуть отставать.

## Связанные документы

- [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths) — четыре протокольные ветки и написание Base URL
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility) — протоколы во всех инструментах
- [CC Switch: настройка](/docs/ide/cc-switch) — переключение провайдеров Claude Code / Codex в GUI
- [Китайские модели](/docs/usage/cn-models) — актуальные id GLM / Kimi / DeepSeek / QCode в продаже
- [Устранение неполадок](/docs/reference/troubleshooting)