AI модели и настройка аутентификации

Чему вы научитесь

Настроить нескольких провайдеров AI моделей (Anthropic, OpenAI, OpenRouter и др.)
Использовать три метода аутентификации (API Key, OAuth, Token)
Управлять аутентификацией нескольких аккаунтов и ротацией аутентификации
Настроить выбор моделей и резервные модели
Устранять распространенные проблемы аутентификации

Трудности, с которыми вы сталкиваетесь

Clawdbot поддерживает десятки провайдеров моделей, но настройка может вызвать путаницу:

Следует использовать API Key или OAuth?
В чем разница между методами аутентификации разных провайдеров?
Как настроить несколько аккаунтов?
Как автоматически обновлять OAuth токен?

Когда использовать этот метод

После первой установки необходимо настроить AI модель
Добавление нового провайдера моделей или резервного аккаунта
При возникновении ошибок аутентификации или ограничений квоты
Необходимо настроить переключение моделей и механизм резервирования

🎒 Подготовка перед началом

Предварительная проверка

В этом руководстве предполагается, что вы завершили Быстрый запуск, установили и запустили Gateway.

Убедитесь, что установлен Node ≥22
Демон Gateway работает
Подготовьте учетные данные хотя бы одного провайдера AI моделей (API Key или подписной аккаунт)

Основная идея

Настройка моделей и аутентификация разделены

В Clawdbot выбор модели и учетные данные аутентификации — это два независимых понятия:

Настройка модели: указывает Clawdbot, какую модель использовать (например, anthropic/claude-opus-4-5), хранится в ~/.clawdbot/models.json
Настройка аутентификации: предоставляет учетные данные для доступа к модели (например, API Key или OAuth токен), хранится в ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

Почему разделены?

Эта конструкция позволяет гибко переключаться между несколькими провайдерами и аккаунтами без повторной настройки параметров модели.

Три метода аутентификации

Clawdbot поддерживает три метода аутентификации для разных сценариев:

Метод аутентификации	Формат хранения	Типичный сценарий	Поддерживаемые провайдеры
API Key	`{ type: "api_key", key: "sk-..." }`	Быстрый старт, тестирование	Anthropic, OpenAI, OpenRouter, DeepSeek и др.
OAuth	`{ type: "oauth", access: "...", refresh: "..." }`	Длительная работа, автоматическое обновление	Anthropic (Claude Code CLI), OpenAI (Codex), Qwen Portal
Token	`{ type: "token", token: "..." }`	Статический Bearer токен	GitHub Copilot, некоторые настраиваемые прокси

Поддерживаемые провайдеры моделей

Clawdbot имеет встроенную поддержку следующих провайдеров моделей:

Список встроенных провайдеров

Провайдер	Метод аутентификации	Рекомендуемая модель	Примечание
Anthropic	API Key / OAuth (Claude Code CLI)	`anthropic/claude-opus-4-5`	Рекомендуется Claude Pro/Max + Opus 4.5
OpenAI	API Key / OAuth (Codex)	`openai/gpt-5.2`	Поддерживает стандартную версию OpenAI и версию Codex
OpenRouter	API Key	`openrouter/anthropic/claude-sonnet-4-5`	Агрегирует сотни моделей
Ollama	HTTP Endpoint	`ollama/<model>`	Локальные модели, не требуется API Key
DeepSeek	API Key	`deepseek/deepseek-r1`	Удобно для Китая
Qwen Portal	OAuth	`qwen-portal/<model>`	OAuth Qwen Portal
Venice	API Key	`venice/<model>`	Приоритет конфиденциальности
Bedrock	AWS SDK	`amazon-bedrock/<model>`	Модели, размещенные в AWS
Antigravity	API Key	`google-antigravity/<model>`	Сервис прокси моделей

Рекомендуемая комбинация

Для большинства пользователей рекомендуется настроить Anthropic Opus 4.5 в качестве основной модели, OpenAI GPT-5.2 — в качестве резервной. Opus лучше работает в обработке длинного контекста и безопасности.

Следуйте моим шагам

Шаг 1: Настройка Anthropic (рекомендуется)

Зачем Anthropic Claude — это рекомендуемая модель для Clawdbot, особенно Opus 4.5, она отлично работает в обработке длинного контекста и безопасности.

Вариант A: Использовать API Key Anthropic (самый быстрый)

bash

clawdbot onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Что вы должны увидеть:

Gateway перезагружает конфигурацию
Модель по умолчанию установлена на anthropic/claude-opus-4-5
Файл аутентификации ~/.clawdbot/agents/default/agent/auth-profiles.json создан

Вариант B: Использовать OAuth (рекомендуется для длительной работы)

OAuth подходит для длительно работающего Gateway, токен будет автоматически обновляться.

Сгенерируйте setup-token (необходимо запустить Claude Code CLI на любой машине):

bash

claude setup-token

Скопируйте выведенный токен
Запустите на хосте Gateway:

bash

clawdbot models auth paste-token --provider anthropic
# вставьте токен

Что вы должны увидеть:

Подсказка "Auth profile added: anthropic:claude-cli"
Тип аутентификации — oauth (не api_key)

Преимущества OAuth

OAuth токен автоматически обновляется, ручное обновление не требуется. Подходит для постоянно работающего демона Gateway.

Шаг 2: Настройка OpenAI в качестве резервной модели

Зачем Настройка резервной модели позволяет автоматически переключаться, когда основная модель (например, Anthropic) сталкивается с ограничением квоты или ошибкой.

bash

clawdbot onboard --openai-api-key "$OPENAI_API_KEY"

Или использовать OpenAI Codex OAuth:

bash

clawdbot onboard --openai-codex

Что вы должны увидеть:

В ~/.clawdbot/clawdbot.json добавлена конфигурация провайдера OpenAI
В файле аутентификации добавлена конфигурация openai:default или openai-codex:codex-cli

Шаг 3: Настройка выбора модели и резервных моделей

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

Отредактируйте ~/.clawdbot/clawdbot.json:

yaml

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-5"
      fallbacks:
        - "openai/gpt-5.2"
        - "openai/gpt-5-mini"
    models:
      "anthropic/claude-opus-4-5":
        alias: "opus"
      "anthropic/claude-sonnet-4-5":
        alias: "sonnet"
      "openai/gpt-5.2":
        alias: "gpt"
      "openai/gpt-5-mini":
        alias: "gpt-mini"

Описание полей:

primary: модель, используемая по умолчанию
fallbacks: резервные модели,尝试 по очереди (автоматическое переключение при сбое)
alias: псевдоним модели (например, /model opus эквивалентно /model anthropic/claude-opus-4-5)

Что вы должны увидеть:

После перезапуска Gateway основная модель становится Opus 4.5
Настройка резервных моделей вступает в силу

Шаг 4: Добавление OpenRouter (опционально)

Зачем OpenRouter агрегирует сотни моделей, подходит для доступа к специальным или бесплатным моделям.

bash

clawdbot onboard --auth-choice openrouter-api-key --token "$OPENROUTER_API_KEY"

Затем настройте модель:

yaml

agents:
  defaults:
    model:
      primary: "openrouter/anthropic/claude-sonnet-4-5"

Что вы должны увидеть:

Формат ссылки на модель: openrouter/<provider>/<model>
Можно использовать clawdbot models scan для просмотра доступных моделей

Шаг 5: Настройка Ollama (локальные модели)

Зачем Ollama позволяет запускать модели локально, без API Key, подходит для сценариев, чувствительных к конфиденциальности.

Отредактируйте ~/.clawdbot/clawdbot.json:

yaml

models:
  providers:
    ollama:
      baseUrl: "http://localhost:11434"
      api: "openai-completions"
      models:
        - id: "ollama/llama3.2"
          name: "Llama 3.2"
          api: "openai-completions"
          reasoning: false
          input: ["text"]
          cost:
            input: 0
            output: 0
            cacheRead: 0
            cacheWrite: 0
          contextWindow: 128000
          maxTokens: 4096

agents:
  defaults:
    model:
      primary: "ollama/llama3.2"

Что вы должны увидеть:

Для моделей Ollama не требуется API Key
Убедитесь, что служба Ollama работает на http://localhost:11434

Шаг 6: Проверка конфигурации

Зачем Убедитесь, что аутентификация и настройка модели правильны, Gateway может нормально вызывать AI.

bash

clawdbot doctor

Что вы должны увидеть:

Нет ошибок аутентификации
Список моделей включает настроенные провайдеры
Состояние показывает "OK"

Или отправьте тестовое сообщение:

bash

clawdbot message send --to +1234567890 --message "Hello from Clawdbot"

Что вы должны увидеть:

AI отвечает нормально
Нет ошибки "No credentials found"

Контрольная точка ✅

[ ] Настроен хотя бы один провайдер моделей (Anthropic или OpenAI)
[ ] Файл аутентификации auth-profiles.json создан
[ ] Файл конфигурации моделей models.json создан
[ ] Можно переключать модели через /model <alias>
[ ] В журнале Gateway нет ошибок аутентификации
[ ] Тестовое сообщение успешно получает ответ AI

Предупреждения о ловушках

Несоответствие режима аутентификации

Проблема: Конфигурация OAuth не соответствует режиму аутентификации

yaml

# ❌ Ошибка: учетные данные OAuth, но режим — token
anthropic:claude-cli:
  provider: "anthropic"
  mode: "token"  # должно быть "oauth"

Исправление:

yaml

# ✅ Правильно
anthropic:claude-cli:
  provider: "anthropic"
  mode: "oauth"

TIP

Clawdbot автоматически установит режим mode: "oauth" для конфигурации, импортированной из Claude Code CLI, ручное изменение не требуется.

Ошибка обновления OAuth токена

Проблема: Ошибка "OAuth token refresh failed for anthropic"

Причины:

Учетные данные Claude Code CLI недействительны на другой машине
OAuth токен истек

Исправление:

bash

# Сгенерируйте setup-token заново
claude setup-token

# Повторно вставьте
clawdbot models auth paste-token --provider anthropic

token vs oauth

type: "token" — это статический Bearer токен, не обновляется автоматически. type: "oauth" поддерживает автоматическое обновление.

Ограничение квоты и отказоустойчивость

Проблема: Основная модель сталкивается с ограничением квоты (ошибка 429)

Симптом:

HTTP 429: rate_limit_error

Автоматическая обработка:

Clawdbot автоматически попробует следующую модель в fallbacks
Если все модели не работают, возвращается ошибка

Настройка периода охлаждения (опционально):

yaml

auth:
  cooldowns:
    billingBackoffHours: 24  # Отключить провайдера на 24 часа после ошибки квоты
    failureWindowHours: 1      # Сбои в течение 1 часа учитываются при охлаждении

Перекрытие переменных окружения

Проблема: В файле конфигурации используются переменные окружения, но они не установлены

yaml

models:
  providers:
    openai:
      apiKey: "${OPENAI_KEY}"  # Если не установлено, будет ошибка

Исправление:

bash

# Установите переменную окружения
export OPENAI_KEY="sk-..."

# Или добавьте в .zshrc/.bashrc
echo 'export OPENAI_KEY="sk-..."' >> ~/.zshrc

Расширенная конфигурация

Несколько аккаунтов и ротация аутентификации

Зачем Настройте несколько аккаунтов для одного провайдера, чтобы реализовать балансировку нагрузки и управление квотой.

Настройка файла аутентификации (~/.clawdbot/agents/default/agent/auth-profiles.json):

json

{
  "version": 1,
  "profiles": {
    "anthropic:me@example.com": {
      "type": "oauth",
      "provider": "anthropic",
      "email": "me@example.com"
    },
    "anthropic:work": {
      "type": "api_key",
      "provider": "anthropic",
      "key": "sk-ant-work..."
    },
    "openai:personal": {
      "type": "api_key",
      "provider": "openai",
      "key": "sk-openai-1..."
    },
    "openai:work": {
      "type": "api_key",
      "provider": "openai",
      "key": "sk-openai-2..."
    }
  },
  "order": {
    "anthropic": ["anthropic:me@example.com", "anthropic:work"],
    "openai": ["openai:personal", "openai:work"]
  }
}

Поле order:

Определяет порядок ротации аутентификации
Clawdbot будет пробовать каждый аккаунт по порядку
Неудачные аккаунты будут автоматически пропущены

Команды CLI для управления порядком:

bash

# Просмотр текущего порядка
clawdbot models auth order get --provider anthropic

# Установка порядка
clawdbot models auth order set --provider anthropic anthropic:me@example.com anthropic:work

# Очистка порядка (использовать ротацию по умолчанию)
clawdbot models auth order clear --provider anthropic

Аутентификация для определенной сессии

Зачем Заблокируйте конфигурацию аутентификации для определенной сессии или под-Agent.

Используйте синтаксис /model <alias>@<profileId>:

bash

# Заблокировать использование определенного аккаунта для текущей сессии
/model opus@anthropic:work

# Указать аутентификацию при создании под-Agent
clawdbot sessions spawn --model "opus@anthropic:work" --workspace "~/clawd-work"

Блокировка в файле конфигурации (~/.clawdbot/clawdbot.json):

yaml

auth:
  order:
    # Заблокировать порядок anthropic для main Agent
    main: ["anthropic:me@example.com", "anthropic:work"]

Автоматическое обновление OAuth токена

Clawdbot поддерживает автоматическое обновление для следующих провайдеров OAuth:

Провайдер	Процесс OAuth	Механизм обновления
Anthropic (Claude Code CLI)	Стандартный код авторизации	Обновление через pi-mono RPC
OpenAI (Codex)	Стандартный код авторизации	Обновление через pi-mono RPC
Qwen Portal	Настраиваемый OAuth	`refreshQwenPortalCredentials`
Chutes	Настраиваемый OAuth	`refreshChutesTokens`

Логика автоматического обновления:

Проверка срока истечения токена (поле expires)
Если не истек, использовать напрямую
Если истек, использовать токен refresh для запроса нового токена access
Обновить сохраненные учетные данные

Синхронизация Claude Code CLI

Если используется OAuth Anthropic (anthropic:claude-cli), Clawdbot синхронизирует обратно с хранилищем Claude Code CLI при обновлении токена, обеспечивая согласованность обеих сторон.

Псевдонимы моделей и ярлыки

Зачем Псевдонимы моделей позволяют быстро переключать модели, не запоминая полный ID.

Предопределенные псевдонимы (рекомуемая конфигурация):

yaml

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-5":
        alias: "opus"
      "anthropic/claude-sonnet-4-5":
        alias: "sonnet"
      "anthropic/claude-haiku-4-5":
        alias: "haiku"
      "openai/gpt-5.2":
        alias: "gpt"
      "openai/gpt-5-mini":
        alias: "gpt-mini"

Использование:

bash

# Быстро переключиться на Opus
/model opus

# Эквивалентно
/model anthropic/claude-opus-4-5

# Использовать определенную аутентификацию
/model opus@anthropic:work

Псевдонимы отделены от аутентификации

Псевдонимы — это просто ярлыки для ID моделей, они не влияют на выбор аутентификации. Чтобы указать аутентификацию, используйте синтаксис @<profileId>.

Настройка неявных провайдеров

Некоторые провайдеры не требуют явной настройки, Clawdbot автоматически обнаруживает:

Провайдер	Способ обнаружения	Файл конфигурации
GitHub Copilot	`~/.copilot/credentials.json`	Не требуется настройка
AWS Bedrock	Переменные окружения или учетные данные AWS SDK	`~/.aws/credentials`
Codex CLI	`~/.codex/auth.json`	Не требуется настройка

Приоритет неявной конфигурации

Неявная конфигурация автоматически объединяется в models.json, но явная конфигурация может переопределить их.

Часто задаваемые вопросы

OAuth vs API Key: в чем разница?

OAuth:

Подходит для длительно работающего Gateway
Токен автоматически обновляется
Требуется подписной аккаунт (Claude Pro/Max, OpenAI Codex)

API Key:

Подходит для быстрого старта и тестирования
Не обновляется автоматически
Может использоваться для аккаунтов бесплатного уровня

Рекомендуемый выбор

Длительная работа → используйте OAuth (Anthropic, OpenAI)
Быстрое тестирование → используйте API Key
Чувствительность к конфиденциальности → используйте локальные модели (Ollama)

Как просмотреть текущую конфигурацию аутентификации?

bash

# Просмотреть файл аутентификации
cat ~/.clawdbot/agents/default/agent/auth-profiles.json

# Просмотреть конфигурацию моделей
cat ~/.clawdbot/models.json

# Просмотреть основной файл конфигурации
cat ~/.clawdbot/clawdbot.json

Или используйте CLI:

bash

# Список моделей
clawdbot models list

# Просмотреть порядок аутентификации
clawdbot models auth order get --provider anthropic

Как удалить определенную аутентификацию?

bash

# Отредактируйте файл аутентификации, удалите соответствующий профиль
nano ~/.clawdbot/agents/default/agent/auth-profiles.json

# Или используйте CLI (ручная операция)
clawdbot doctor  # Просмотр проблемных конфигураций

Подтверждение перед удалением

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

Как восстановиться после ограничения квоты?

Автоматическое восстановление:

Clawdbot автоматически повторит попытку после периода охлаждения
Просмотрите журналы, чтобы узнать время повторной попытки

Ручное восстановление:

bash

# Очистить состояние охлаждения
clawdbot models auth clear-cooldown --provider anthropic --profile-id anthropic:me@example.com

# Или перезапустить Gateway
clawdbot gateway restart

Итог урока

Clawdbot поддерживает три метода аутентификации: API Key, OAuth, Token
Настройка моделей и аутентификации разделены, хранятся в разных файлах
Рекомендуется настроить Anthropic Opus 4.5 в качестве основной модели, OpenAI GPT-5.2 — в качестве резервной
OAuth поддерживает автоматическое обновление, подходит для длительной работы
Можно настроить несколько аккаунтов и ротацию аутентификации, чтобы реализовать балансировку нагрузки
Используйте псевдонимы моделей для быстрого переключения моделей

Предварительный просмотр следующего урока

На следующем уроке мы изучим Управление сессиями и несколько Agent.
Вы узнаете:
Модели сессий и изоляция сессий
Сотрудничество под-Agent
Сжатие контекста
Настройка маршрутизации нескольких Agent

Приложение: справочник по исходному коду

Нажмите, чтобы развернуть расположение исходного кода

Дата обновления: 2026-01-27

Функция	Путь к файлу	Номер строки
Определение типов учетных данных аутентификации	`src/agents/auth-profiles/types.ts`	1-74
Разбор и обновление OAuth токена	`src/agents/auth-profiles/oauth.ts`	1-220
Управление файлом конфигурации аутентификации	`src/agents/auth-profiles/profiles.ts`	1-85
Тип конфигурации моделей	`src/config/types.models.ts`	1-60
Генерация конфигурации моделей	`src/agents/models-config.ts`	1-139
Конфигурация Zod Schema	`src/config/zod-schema.core.ts`	1-300+

Ключевые типы:

AuthProfileCredential: объединенный тип учетных данных аутентификации (ApiKeyCredential | TokenCredential | OAuthCredential)
ModelProviderConfig: структура конфигурации провайдера моделей
ModelDefinitionConfig: структура определения модели

Ключевые функции:

resolveApiKeyForProfile(): разбор учетных данных аутентификации и возврат API Key
refreshOAuthTokenWithLock(): обновление OAuth токена с блокировкой
ensureClawdbotModelsJson(): генерация и объединение конфигурации моделей

Расположение файлов конфигурации:

~/.clawdbot/clawdbot.json: основной файл конфигурации
~/.clawdbot/agents/<agentId>/agent/auth-profiles.json: учетные данные аутентификации
~/.clawdbot/models.json: сгенерированная конфигурация моделей

AI модели и настройка аутентификации ​

Чему вы научитесь ​

Трудности, с которыми вы сталкиваетесь ​

Когда использовать этот метод ​

🎒 Подготовка перед началом ​

Основная идея ​

Настройка моделей и аутентификация разделены ​

Три метода аутентификации ​

Поддерживаемые провайдеры моделей ​

Следуйте моим шагам ​

Шаг 1: Настройка Anthropic (рекомендуется) ​

Шаг 2: Настройка OpenAI в качестве резервной модели ​

Шаг 3: Настройка выбора модели и резервных моделей ​

Шаг 4: Добавление OpenRouter (опционально) ​

Шаг 5: Настройка Ollama (локальные модели) ​

Шаг 6: Проверка конфигурации ​

Контрольная точка ✅ ​

Предупреждения о ловушках ​

Несоответствие режима аутентификации ​

Ошибка обновления OAuth токена ​

Ограничение квоты и отказоустойчивость ​

Перекрытие переменных окружения ​

Расширенная конфигурация ​

Несколько аккаунтов и ротация аутентификации ​

Аутентификация для определенной сессии ​

Автоматическое обновление OAuth токена ​

Псевдонимы моделей и ярлыки ​

Настройка неявных провайдеров ​

Часто задаваемые вопросы ​

OAuth vs API Key: в чем разница? ​

Как просмотреть текущую конфигурацию аутентификации? ​

Как удалить определенную аутентификацию? ​

Как восстановиться после ограничения квоты? ​

Итог урока ​

Предварительный просмотр следующего урока ​

Приложение: справочник по исходному коду ​

AI модели и настройка аутентификации

Чему вы научитесь

Трудности, с которыми вы сталкиваетесь

Когда использовать этот метод

🎒 Подготовка перед началом

Основная идея

Настройка моделей и аутентификация разделены

Три метода аутентификации

Поддерживаемые провайдеры моделей

Следуйте моим шагам

Шаг 1: Настройка Anthropic (рекомендуется)

Шаг 2: Настройка OpenAI в качестве резервной модели

Шаг 3: Настройка выбора модели и резервных моделей

Шаг 4: Добавление OpenRouter (опционально)

Шаг 5: Настройка Ollama (локальные модели)

Шаг 6: Проверка конфигурации

Контрольная точка ✅

Предупреждения о ловушках

Несоответствие режима аутентификации

Ошибка обновления OAuth токена

Ограничение квоты и отказоустойчивость

Перекрытие переменных окружения

Расширенная конфигурация

Несколько аккаунтов и ротация аутентификации

Аутентификация для определенной сессии

Автоматическое обновление OAuth токена

Псевдонимы моделей и ярлыки

Настройка неявных провайдеров

Часто задаваемые вопросы

OAuth vs API Key: в чем разница?

Как просмотреть текущую конфигурацию аутентификации?

Как удалить определенную аутентификацию?

Как восстановиться после ограничения квоты?

Итог урока

Предварительный просмотр следующего урока

Приложение: справочник по исходному коду