OpenClaw

OpenClaw — открытый AI-помощник для личных устройств. Gateway централизованно управляет моделями, сеансами, инструментами и каналами сообщений; доступны терминальный TUI и браузерный Control UI. Добавив AGTCloud как Custom Provider, OpenClaw может вызывать модели текущего ключа API через совместимую точку входа OpenAI Chat Completions.

В этом руководстве рассматриваются только локальная установка, подключение модели, запуск Gateway и базовая проверка. Каналы сообщений, удалённый Gateway, плагины ClawHub, Skills, MCP, задания по расписанию и несколько агентов здесь не рассматриваются.

Сначала проверьте обычный диалог, затем включайте инструменты

OpenClaw может читать файлы, выполнять команды Shell и вызывать другие инструменты. Успешный текстовый ответ не означает совместимость модели со всеми структурами инструментов. При первом тесте используйте изолированный каталог, оставьте ручное подтверждение и проверяйте каждое предлагаемое действие.

Подготовка

Перед началом убедитесь, что вы:

Подготовили устройство macOS, Linux, WSL2 или Windows, поддерживаемое OpenClaw;
Создали ключ API AGTCloud на странице API Keys;
Скопировали из каталога моделей ID модели, доступной текущему ключу и поддерживающей Chat Completions;
Подготовили тестовый каталог без производственных учётных данных и конфиденциального исходного кода.

MODEL_ID — заполнитель для замены. Для проверки вызова инструментов выбирайте модель, доступную текущему ключу API и явно поддерживающую вызов инструментов.

Установка OpenClaw

Официальный установщик OpenClaw при необходимости подготавливает поддерживаемую среду Node.js. Пользователи, самостоятельно управляющие Node.js, также могут установить программу через npm.

Официальный установочный скрипт:

curl -fsSL https://openclaw.ai/install.sh | bash

После установки проверьте версию и среду выполнения:

openclaw --version
openclaw doctor

Если установщик автоматически открыл мастер, можно выйти из этапа настройки модели, сначала настроить Provider AGTCloud ниже, а затем выполнить openclaw onboard --install-daemon. Так мастер сможет сохранить уже проверенную модель по умолчанию.

Безопасное сохранение ключа API

OpenClaw считывает ~/.openclaw/.env как резервный глобальный файл переменных окружения. Сначала создайте его, затем запишите ключ API AGTCloud:

Путь пользовательского файла:

~/.openclaw/.env

Содержимое файла:

AGTCLOUD_API_KEY=your-api-key

Этот файл содержит реальные учётные данные. Не добавляйте его в репозиторий, не загружайте в облачное хранилище и не отправляйте как диагностическое вложение.

Добавление Custom Provider AGTCloud

OpenClaw сохраняет Custom Provider в models.providers. В этом руководстве Provider agtcloud добавляется командами частичного обновления конфигурации без перезаписи существующего openclaw.json.

openclaw config set models.providers.agtcloud \
  '{"baseUrl":"https://api.agtcloud.cn/v1","apiKey":"${AGTCLOUD_API_KEY}","api":"openai-completions","auth":"api-key","authHeader":true,"models":[{"id":"MODEL_ID","name":"MODEL_ID","input":["text"]}]}' \
  --strict-json \
  --merge

Основные поля конфигурации:

Поле	Значение	Назначение
Provider ID	`agtcloud`	Формирует ссылку на модель `agtcloud/MODEL_ID`
`baseUrl`	`https://api.agtcloud.cn/v1`	Адрес OpenAI-совместимого API AGTCloud; должен содержать `/v1`
`apiKey`	`${AGTCLOUD_API_KEY}`	Считывает учётные данные из файла окружения OpenClaw
`api`	`openai-completions`	Использует адаптер запросов Chat Completions
`auth`	`api-key`	Использует аутентификацию ключом API
`authHeader`	`true`	Передаёт учётные данные через Header Authorization
`models`	`MODEL_ID`	Явно регистрирует модель, разрешённую для OpenClaw

Base URL должен содержать /v1

Укажите https://api.agtcloud.cn/v1, а не только API Origin, и не добавляйте полный путь /chat/completions. OpenClaw добавит путь точки входа в соответствии с адаптером openai-completions.

В руководстве модель объявляется только для текстового ввода; неподтверждённые длина контекста, максимальный вывод, цены, рассуждения и работа с изображениями не задаются. После проверки реальных возможностей модели можно дополнить метаданные по официальному описанию полей моделей OpenClaw.

Выбор модели и проверка конфигурации

Назначьте только что зарегистрированную модель моделью по умолчанию:

openclaw models set agtcloud/MODEL_ID

Последовательно проверьте конфигурационный файл, модели Provider и текущую модель по умолчанию:

openclaw config validate
openclaw models list --provider agtcloud
openclaw models status

Если config validate сообщает о недопустимом поле, сначала исправьте конфигурацию, не продолжайте запуск Gateway. Если в списке нет agtcloud/MODEL_ID, проверьте добавление модели в models.providers.agtcloud.models.

Для реальной проверки подключения можно выполнить:

openclaw models status --probe

Проверка подключения отправляет реальные запросы

--probe соединяется с сервисом модели и может расходовать небольшое количество Token. Выполняйте его только после подтверждения правильности Base URL, ключа API и ID модели.

Локальная первоначальная настройка и запуск Gateway

После проверки Provider запустите локальный мастер и установите фоновую службу Gateway:

openclaw onboard --install-daemon

Если мастер спрашивает о модели, выберите сохранение существующей конфигурации. Каналы сообщений, Web Search, Skills и другие расширения пока можно пропустить. При первой настройке рекомендуется оставить Gateway доступным только локально и сохранить аутентификацию доступа.

После завершения перезапустите и проверьте Gateway:

openclaw gateway restart
openclaw gateway status

Если Gateway не запускается, сначала выполните openclaw config validate и openclaw doctor. Не обходите проблему открытием публичного сетевого доступа или отключением аутентификации.

Запуск и проверка подключения

Открытие Control UI или терминального TUI

Браузерный Control UI:

openclaw dashboard

Либо подключитесь к локальному Gateway в терминале:

openclaw tui

Проверка базового текстового ответа

При первой проверке введите:

Ответьте только: подключение к AGTCloud установлено. Не вызывайте никакие инструменты.

Возврат указанного текста подтверждает базовое подключение Gateway, Provider AGTCloud, ключа API и ID модели.

Необязательно: проверка инструментов только для чтения

После стабильной работы обычного диалога в безопасном тестовом проекте введите:

Прочитайте README.md и в трёх пунктах опишите назначение проекта. Не изменяйте никакие файлы и не выполняйте другие команды.

Изучите каждое предлагаемое действие OpenClaw и разрешите только чтение нужного файла. Если обычный диалог работает, а этот шаг нет, целевая модель или текущая совместимая точка входа обычно ещё не полностью поддерживает нужную структуру вызова инструментов.

Добавление или смена модели

Ссылки на модели OpenClaw имеют формат provider/model, поэтому модель AGTCloud записывается так:

agtcloud/MODEL_ID

Custom Provider не гарантирует автоматическое получение всех результатов AGTCloud /v1/models. Чтобы добавить модель, включите новый объект в models.providers.agtcloud.models, затем переключите её следующей командой:

openclaw models set agtcloud/MODEL_ID
openclaw gateway restart

После изменения имени убедитесь, что модель доступна текущему ключу API и поддерживает нужный протокол; иначе возможна ошибка отсутствующей или запрещённой модели.

Частые вопросы

Симптом	Что проверить сначала	Решение
Команда `openclaw` не найдена	Установку, терминал и `PATH`	Откройте терминал заново и выполните `openclaw --version`; при повторной ошибке повторите официальную установку
Конфигурация не проходит проверку	JSON, имена полей и кавычки команд	Выполните `openclaw config validate`, исправьте указанный путь ошибки без перезаписи всего файла
Gateway не запускается	`gateway.mode`, корректность конфигурации и фоновую службу	Повторите локальный onboarding, затем проверьте `openclaw doctor` и `openclaw gateway status`
Ответ `401`	Ключ API и `authHeader`	Используйте действующий ключ API и убедитесь, что `authHeader` равен `true`
Ответ `403`	Права ключа, баланс и доступ к модели	Убедитесь, что ключ может вызывать выбранную модель, и проверьте состояние аккаунта
Ответ `404`	Base URL, протокол и ID модели	Используйте `https://api.agtcloud.cn/v1` без повторного `/v1` или полного Endpoint
Модель не отображается	`models[]` Provider	Добавьте полный `MODEL_ID` в `models.providers.agtcloud.models` и проверьте заново
Модель запрещена	Политику моделей и зарегистрированный каталог	Проверьте ссылку `agtcloud/MODEL_ID` и существующие политики ограничений моделей
Диалог работает, но инструменты не работают	Совместимость вызова инструментов моделью	Отключите задания с инструментами и отдельно проверьте модель с явной поддержкой вызова инструментов
По-прежнему используется старая модель	Gateway и текущий сеанс	Перезапустите Gateway, создайте новый сеанс и проверьте текущую модель

Если причину найти не удаётся, запишите версию OpenClaw, время запроса, API Base URL, Provider, ID модели, HTTP-статус и обезличенную ошибку, затем обратитесь к разделу ошибок и диагностики. Не отправляйте .env, полные резервные копии конфигурации или ключи API.