Skip to main content
Краткие ответы и более глубокое устранение неполадок для реальных конфигураций (локальная разработка, VPS, несколько агентов, OAuth/API-ключи, переключение моделей при сбое). Диагностику среды выполнения см. в разделе Устранение неполадок. Полный справочник по конфигурации см. в разделе Конфигурация.

​
Первые 60 секунд, если что-то не работает

1

Быстрая проверка состояния

Краткая локальная сводка: ОС и обновление, доступность Gateway/службы, агенты/сеансы, конфигурация провайдера и проблемы среды выполнения (если Gateway доступен).
2

Отчёт для отправки (им можно безопасно делиться)

Диагностика только для чтения с последними строками журнала (токены скрыты).
3

Состояние демона и порта

Показывает состояние среды выполнения супервизора и доступность RPC, целевой URL проверки и конфигурацию, которую, вероятно, использовала служба.
4

Углублённые проверки

Проверка работоспособности Gateway в реальном времени, включая проверки каналов, если они поддерживаются (требуется доступный Gateway). См. раздел Работоспособность.
5

Просмотр последних записей журнала

Если RPC недоступен, используйте:
Файловые журналы отделены от журналов службы; см. разделы Ведение журналов и Устранение неполадок.
6

Запуск doctor (исправление)

Исправляет/переносит конфигурацию и состояние, затем выполняет проверки работоспособности. См. раздел Doctor.
7

Снимок Gateway (только WS)

Запрашивает полный снимок у работающего Gateway. См. раздел Работоспособность.

​
Быстрый старт и первоначальная настройка

Вопросы и ответы о первом запуске — установка, первоначальная настройка, маршруты аутентификации, подписки, первоначальные сбои — находятся в разделе Частые вопросы о первом запуске.

​
Что такое OpenClaw?

OpenClaw — персональный ИИ-ассистент, работающий на ваших устройствах. Он отвечает в уже используемых вами системах обмена сообщениями (Discord, Google Chat, iMessage, Mattermost, Signal, Slack, Telegram, WebChat, WhatsApp и комплектных плагинах каналов, таких как QQ Bot), а на поддерживаемых платформах также предоставляет голосовые функции и интерактивный Canvas. Gateway — постоянно работающий уровень управления; сам ассистент и есть продукт.
OpenClaw — не «просто оболочка для Claude». Это локальный уровень управления, запускающий функционального ассистента на вашем собственном оборудовании и предоставляющий к нему доступ из уже используемых вами приложений для общения, с сохраняющими состояние сеансами, памятью и инструментами — без передачи ваших рабочих процессов облачному SaaS.
  • Ваши устройства, ваши данные: запускайте Gateway где угодно (Mac, Linux, VPS), сохраняя рабочее пространство и историю сеансов локально.
  • Настоящие каналы, а не веб-песочница: Discord/iMessage/Signal/Slack/Telegram/WhatsApp и другие, а также голосовые функции на мобильных устройствах и Canvas на поддерживаемых платформах.
  • Независимость от моделей: используйте Anthropic, MiniMax, OpenAI, OpenRouter и другие сервисы с маршрутизацией и переключением при сбое для каждого агента.
  • Полностью локальный вариант: запускайте локальные модели, чтобы все данные оставались на вашем устройстве.
  • Маршрутизация нескольких агентов: отдельные агенты для каждого канала, аккаунта или задачи, каждый со своим рабочим пространством и настройками по умолчанию.
  • Открытый исходный код и широкие возможности настройки: изучайте, расширяйте и размещайте самостоятельно без привязки к поставщику.
Документация: Gateway, Каналы, Несколько агентов, Память.
Хорошие первые проекты: создать веб-сайт (WordPress, Shopify или статический сайт); разработать прототип мобильного приложения (структура, экраны, план API); упорядочить файлы и папки; подключить Gmail и автоматизировать создание сводок или последующие действия.OpenClaw может выполнять крупные задачи, но лучше всего разбивать их на этапы и использовать субагентов для параллельной работы.
  • Персональные сводки: сводки по входящим сообщениям, календарю и интересующим вас новостям.
  • Исследование и подготовка текстов: быстрый поиск информации, сводки и первые варианты писем или документов.
  • Напоминания и последующие действия: подсказки и контрольные списки, запускаемые через Cron или Heartbeat.
  • Автоматизация браузера: заполнение форм, сбор данных, выполнение повторяющихся веб-задач.
  • Координация между устройствами: отправьте задачу с телефона, позвольте Gateway выполнить её на сервере и получите результат обратно в чате.
Да, в части исследования, квалификации и подготовки текстов: сканирования сайтов, составления коротких списков, обобщения информации о потенциальных клиентах, подготовки черновиков рассылок или рекламных текстов.При проведении рассылок или рекламных кампаний сохраняйте участие человека. Избегайте спама, соблюдайте местное законодательство и правила платформ, проверяйте всё до отправки. Пусть OpenClaw готовит черновики, а вы их утверждаете.Документация: Безопасность.
OpenClaw — это персональный ассистент и уровень координации, а не замена IDE. Используйте Claude Code или Codex для максимально быстрого непосредственного написания кода внутри репозитория. Используйте OpenClaw для долговременной памяти, доступа с разных устройств и оркестрации инструментов.
  • Постоянная память и рабочее пространство между сеансами.
  • Доступ с разных платформ (Telegram, WhatsApp, TUI, WebChat).
  • Оркестрация инструментов (браузер, файлы, планирование, хуки).
  • Постоянно работающий Gateway (запускайте на VPS и взаимодействуйте откуда угодно).
  • Узлы для локального браузера, экрана, камеры и выполнения команд.
Примеры: https://openclaw.ai/showcase.

​
Skills и автоматизация

Используйте управляемые переопределения вместо редактирования копии в репозитории. Поместите изменения в ~/.openclaw/skills/<name>/SKILL.md (или добавьте папку через skills.load.extraDirs в ~/.openclaw/openclaw.json). Приоритет: <workspace>/skills -> <workspace>/.agents/skills -> ~/.agents/skills -> ~/.openclaw/skills -> комплектные -> skills.load.extraDirs, поэтому управляемые переопределения имеют приоритет над комплектными навыками без изменения git. Чтобы установить глобально, но ограничить видимость некоторыми агентами, храните общую копию в ~/.openclaw/skills и управляйте видимостью с помощью agents.defaults.skills / agents.list[].skills. В виде PR для копии в репозитории следует отправлять только изменения, достойные включения в основной проект.
Да: добавьте каталоги через skills.load.extraDirs в ~/.openclaw/openclaw.json (самый низкий приоритет в приведённом выше порядке). clawhub по умолчанию устанавливает в ./skills, который OpenClaw при следующем сеансе рассматривает как <workspace>/skills. Чтобы ограничить видимость определёнными агентами, используйте это вместе с agents.defaults.skills или agents.list[].skills.
Поддерживаемые варианты:
  • Задания Cron: изолированные задания могут задавать переопределение model для каждого задания.
  • Агенты: направляйте задачи отдельным агентам с разными моделями по умолчанию, уровнями рассуждения и параметрами потоковой передачи.
  • Переключение по запросу: /model в любое время переключает модель текущего сеанса.
Пример — одна и та же модель с разными настройками для каждого агента:
Поместите общие настройки по умолчанию для каждой модели в agents.defaults.models["provider/model"].params, а переопределения для отдельных агентов — в плоскую структуру agents.list[].params. Не дублируйте одну и ту же модель во вложенной структуре agents.list[].models["provider/model"].params; этот путь предназначен для каталога моделей и переопределений среды выполнения конкретного агента.См. разделы Задания Cron, Маршрутизация нескольких агентов, Конфигурация, Команды с косой чертой.
Используйте субагентов для длительных или параллельных задач: они работают в собственных сеансах, возвращают сводку и не блокируют основной чат. Попросите бота «создать субагента для этой задачи» или используйте /subagents. Используйте /status, чтобы проверить, занят ли сейчас Gateway.И длительные задачи, и субагенты расходуют токены; если важна стоимость, задайте для субагентов более дешёвую модель через agents.defaults.subagents.model.Документация: Субагенты, Фоновые задачи.
Привяжите ветку обсуждения Discord к субагенту или целевому сеансу, чтобы последующие сообщения в ней оставались в этом привязанном сеансе.
  • Создайте через sessions_spawn, используя thread: true (при необходимости — mode: "session" для постоянной последующей работы).
  • Либо выполните привязку вручную с помощью /focus <target>.
  • /agents проверяет состояние привязки.
  • /session idle <duration|off> и /session max-age <duration|off> управляют автоматическим снятием фокуса.
  • /unfocus отвязывает ветку обсуждения.
Конфигурация: session.threadBindings.enabled (глобальный переключатель), session.threadBindings.idleHours (по умолчанию 24, 0 отключает), session.threadBindings.maxAgeHours (по умолчанию 0 = без жёсткого ограничения) и переопределения для отдельных каналов channels.discord.threadBindings.{enabled,idleHours,maxAgeHours}. channels.discord.threadBindings.spawnSessions управляет автоматической привязкой при создании (по умолчанию true).Документация: Субагенты, Discord, Справочник по конфигурации, Команды с косой чертой.
Проверьте определённый маршрут инициатора запроса:
  • При доставке результата субагента в режиме завершения предпочтение отдаётся привязанной ветке обсуждения или маршруту беседы, если они существуют.
  • Если источник завершения содержит только канал, OpenClaw использует сохранённый маршрут сеанса инициатора запроса (lastChannel / lastTo / lastAccountId), чтобы прямая доставка всё ещё могла выполниться.
  • Если нет ни привязанного, ни пригодного сохранённого маршрута, прямая доставка может завершиться сбоем, и вместо немедленной публикации результат будет поставлен в очередь доставки сеанса.
  • Недействительные или устаревшие целевые объекты также могут привести к резервной доставке через очередь или окончательному сбою доставки.
  • Если последний видимый ответ дочернего ассистента в точности равен NO_REPLY / no_reply или ANNOUNCE_SKIP, OpenClaw намеренно подавляет уведомление, а не публикует устаревший предыдущий прогресс.
Отладка: openclaw tasks show <lookup>, где <lookup> — идентификатор задачи, идентификатор запуска или ключ сеанса.Документация: Субагенты, Фоновые задачи, Инструменты сеанса.
Cron выполняется внутри процесса Gateway; он не срабатывает, если Gateway не работает непрерывно.
  • Убедитесь, что Cron включён (cron.enabled), а OPENCLAW_SKIP_CRON не задан.
  • Убедитесь, что Gateway работает круглосуточно (без перехода в спящий режим и перезапусков).
  • Проверьте часовой пояс задания (--tz и часовой пояс хоста).
Отладка:
Документация: Задания Cron, Автоматизация.
Проверьте режим доставки:
  • --no-deliver / delivery.mode: "none": резервная отправка исполнителем не предполагается.
  • Отсутствует или недействительна цель объявления (channel / to): исполнитель пропустил исходящую доставку.
  • Ошибки аутентификации канала (unauthorized, Forbidden): исполнитель попытался выполнить доставку, но учётные данные не позволили это сделать.
  • Безмолвный изолированный результат (только NO_REPLY / no_reply) считается намеренно не предназначенным для доставки, поэтому резервная доставка из очереди также подавляется.
Для изолированных заданий Cron агент всё равно может отправлять сообщения напрямую с помощью инструмента message, если доступен маршрут чата. --announce управляет только резервной доставкой исполнителем итогового текста, который агент ещё не отправил самостоятельно.Отладка:
Документация: Задания Cron, Фоновые задачи.
Это рабочий механизм переключения модели, а не повторное планирование. Изолированный Cron сохраняет передачу управления другой модели во время выполнения и повторяет попытку, когда активный запуск выдаёт LiveSessionModelSwitchError, сохраняя переключённые провайдера и модель (а также переопределение профиля аутентификации, если оно было переключено) перед повторной попыткой.Приоритет выбора модели: сначала переопределение модели обработчиком Gmail (hooks.gmail.model), затем model для отдельного задания, после него сохранённое переопределение модели сеанса Cron и, наконец, обычный выбор модели агента или модели по умолчанию.Цикл повторных попыток ограничен первоначальной попыткой и 2 повторными попытками с переключением; после этого Cron прерывает выполнение, а не повторяет его бесконечно.Отладка:
Документация: Задания Cron, CLI Cron.
Используйте встроенные команды openclaw skills или поместите Skills в рабочее пространство; интерфейс Skills для macOS недоступен в Linux. Найти Skills можно на сайте https://clawhub.ai.
По умолчанию встроенная команда openclaw skills install записывает данные в каталог skills/ активного рабочего пространства. Добавьте --global, чтобы установить их в общий управляемый каталог Skills для всех локальных агентов. Устанавливайте отдельный CLI clawhub только для публикации или синхронизации собственных Skills. Используйте agents.defaults.skills или agents.list[].skills, чтобы ограничить круг агентов, которым доступны общие Skills.
Да, с помощью планировщика Gateway:
  • Задания Cron для запланированных или повторяющихся задач (сохраняются после перезапусков).
  • Heartbeat для периодических проверок основного сеанса.
  • Изолированные задания для автономных агентов, которые публикуют сводки или доставляют сообщения в чаты.
Документация: Задания Cron, Автоматизация, Heartbeat.
Не напрямую. Доступность Skills для macOS ограничивается metadata.openclaw.os и наличием необходимых исполняемых файлов; они загружаются только при соответствии требованиям на хосте Gateway. В Linux Skills, предназначенные только для darwin (apple-notes, apple-reminders, things-mac), не загрузятся, если не переопределить это ограничение.Поддерживаются три варианта:Вариант A — запуск Gateway на Mac (самый простой). Запустите Gateway там, где доступны исполняемые файлы macOS, а затем подключитесь из Linux в удалённом режиме или через Tailscale. Skills загрузятся обычным образом, поскольку хост Gateway работает под управлением macOS.Вариант B — использование узла macOS (без SSH). Запустите Gateway в Linux, подключите узел macOS (приложение в строке меню) и задайте для параметра Команды запуска узла на Mac значение «Всегда спрашивать» или «Всегда разрешать». OpenClaw считает предназначенные только для macOS Skills соответствующими требованиям, если необходимые исполняемые файлы доступны на узле; агент запускает их с помощью инструмента nodes. При выборе «Всегда спрашивать» подтверждение «Всегда разрешать» в запросе добавляет эту команду в список разрешённых.Вариант C — проксирование исполняемых файлов macOS через SSH (для опытных пользователей). Оставьте Gateway в Linux, но настройте необходимые исполняемые файлы CLI так, чтобы они разрешались в обёртки SSH, выполняющие команды на Mac, а затем переопределите Skill, разрешив Linux, чтобы он продолжал соответствовать требованиям.
  1. Создайте обёртку SSH для исполняемого файла (пример: memo для Apple Notes):
  2. Поместите обёртку в PATH на хосте Linux (например, ~/bin/memo).
  3. Переопределите метаданные Skill (в рабочем пространстве или ~/.openclaw/skills), разрешив Linux:
  4. Запустите новый сеанс, чтобы обновился снимок Skills.
Сейчас встроенной интеграции нет. Возможные варианты:
  • Пользовательский Skill или плагин: оптимальный вариант для надёжного доступа к API (API есть у обоих сервисов).
  • Автоматизация браузера: работает без написания кода, но медленнее и менее надёжна.
Для работы агентства с отдельным контекстом каждого клиента создайте по одной странице Notion на клиента (контекст, предпочтения и текущая работа) и попросите агента получать эту страницу в начале сеанса.Для нативной интеграции создайте запрос функции или разработайте Skill на основе этих API.
При нативной установке файлы помещаются в каталог skills/ активного рабочего пространства; используйте --global для всех локальных агентов или настройте agents.defaults.skills / agents.list[].skills, чтобы ограничить видимость. Некоторым Skills требуются исполняемые файлы, установленные через Homebrew; в Linux для этого используется Linuxbrew.См. Skills, Конфигурация Skills, ClawHub.
Используйте встроенный профиль браузера user, который подключается через Chrome DevTools MCP:
Чтобы использовать собственное имя, создайте явный профиль MCP:
Можно использовать браузер локального хоста или подключённый браузерный узел. Если Gateway работает на другом компьютере, запустите хост узла на компьютере с браузером или используйте удалённый CDP.Текущие ограничения профилей existing-session / user по сравнению с управляемым профилем openclaw:
  • click, type, hover, scrollIntoView, drag и select требуют ссылок на снимки, а не селекторов CSS.
  • Обработчикам загрузки требуются ref или inputRef, по одному файлу за раз, без CSS element.
  • responsebody, экспорт PDF, перехват загрузок и пакетные действия по-прежнему требуют использования управляемого браузера.
Полное сравнение см. в разделе Браузер.

​
Изоляция и память

Да: Изоляция. Настройка для Docker (полный Gateway в Docker или образы изолированной среды) описана в разделе Docker.
Образ по умолчанию ориентирован прежде всего на безопасность и работает от имени пользователя node, поэтому в нём отсутствуют системные пакеты, Homebrew и встроенные браузеры. Для более полной настройки:
  • Обеспечьте сохранение /home/node с помощью OPENCLAW_HOME_VOLUME, чтобы кэши не терялись.
  • Включите системные зависимости в образ с помощью OPENCLAW_IMAGE_APT_PACKAGES.
  • Установите браузеры Playwright с помощью встроенного CLI: node /app/node_modules/playwright-core/cli.js install chromium.
  • Задайте PLAYWRIGHT_BROWSERS_PATH и обеспечьте сохранение этого пути.
Документация: Docker, Браузер.
Да, если приватный трафик — это личные сообщения, а общедоступный — группы. Задайте agents.defaults.sandbox.mode: "non-main", чтобы сеансы групп и каналов (с неосновными ключами) выполнялись в настроенной изолированной среде, а основной сеанс личных сообщений оставался на хосте. После включения изоляции по умолчанию используется среда Docker. Ограничьте инструменты, доступные в изолированных сеансах, с помощью tools.sandbox.tools.Пошаговая настройка: Группы: личные сообщения для личного общения и общедоступные группы. Справочник по ключам: Конфигурация Gateway.
Задайте для agents.defaults.sandbox.docker.binds значение ["host:container:mode"] (например, "/home/user/src:/src:ro"). Глобальные привязки и привязки отдельных агентов объединяются; привязки отдельных агентов игнорируются, когда scope: "shared". Для конфиденциальных данных используйте :ro; привязки обходят ограничения файловой системы изолированной среды.OpenClaw проверяет источники привязок как по нормализованному пути, так и по каноническому пути, разрешённому через самый глубокий существующий родительский каталог, поэтому попытки выхода через родительский каталог с символической ссылкой блокируются даже тогда, когда последний сегмент пути ещё не существует.См. Изоляция и Изоляция, политика инструментов и повышенные права.
Память OpenClaw представляет собой файлы Markdown в рабочем пространстве агента: ежедневные заметки хранятся в memory/YYYY-MM-DD.md, а отобранные долгосрочные заметки — в MEMORY.md (только для основных и приватных сеансов).OpenClaw также выполняет без уведомления сброс памяти перед Compaction, прежде чем Compaction создаст сводку разговора, напоминая модели сначала записать долговечные заметки. Он выполняется только тогда, когда рабочее пространство доступно для записи (в изолированных средах только для чтения он пропускается); отключить его можно с помощью agents.defaults.compaction.memoryFlush.enabled: false. См. Память.
Попросите бота записать факт в память: долгосрочные заметки помещаются в MEMORY.md, а краткосрочный контекст — в memory/YYYY-MM-DD.md. Обычно достаточно напомнить модели сохранять воспоминания. Если она продолжает забывать, убедитесь, что Gateway при каждом запуске использует одно и то же рабочее пространство.Документация: Память, Рабочее пространство агента.
Файлы памяти хранятся на диске и сохраняются до удаления; ограничением служит объём хранилища, а не модель. Контекст сеанса по-прежнему ограничен окном контекста модели, поэтому длинные разговоры могут подвергаться сжатию или усечению — именно поэтому существует поиск по памяти, который возвращает в контекст только релевантные фрагменты.Документация: Память, Контекст.
Только если вы используете эмбеддинги OpenAI, которые являются провайдером по умолчанию. Codex OAuth обеспечивает доступ к чату и генерации завершений, но не предоставляет доступ к эмбеддингам, поэтому вход через Codex (с помощью OAuth или входа через Codex CLI) не включает семантический поиск по памяти. Для эмбеддингов OpenAI всё равно требуется настоящий ключ API (OPENAI_API_KEY или models.providers.openai.apiKey).Чтобы всё выполнялось локально, задайте agents.defaults.memorySearch.provider: "local" (GGUF/llama.cpp). Другие поддерживаемые провайдеры: Bedrock, DeepInfra, Gemini (GEMINI_API_KEY или memorySearch.remote.apiKey), GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI-compatible и Voyage. Подробности настройки см. в разделах Память и Поиск по памяти.

​
Где данные хранятся на диске

Нет: собственное состояние OpenClaw хранится локально, но внешние сервисы всё равно видят отправляемые им данные.
  • Локально по умолчанию: сеансы, файлы памяти, конфигурация и рабочее пространство находятся на хосте Gateway (~/.openclaw и каталог вашего рабочего пространства).
  • Удалённо по необходимости: сообщения, отправляемые провайдерам моделей (Anthropic/OpenAI и т. д.), поступают в их API, а платформы обмена сообщениями (Slack/Telegram/WhatsApp и т. д.) хранят данные сообщений на своих серверах.
  • Вы контролируете объём передаваемых данных: локальные модели сохраняют запросы на вашем компьютере, но трафик каналов всё равно проходит через серверы соответствующих каналов.
См. также: Рабочее пространство агента, Память.
Всё находится в $OPENCLAW_STATE_DIR (по умолчанию: ~/.openclaw):Устаревший путь для одного агента ~/.openclaw/agent/* мигрируется командой openclaw doctor.Ваше рабочее пространство (AGENTS.md, файлы памяти, Skills и т. д.) хранится отдельно и настраивается с помощью agents.defaults.workspace (по умолчанию: ~/.openclaw/workspace).
Эти файлы находятся в рабочем пространстве агента, а не в ~/.openclaw.
  • Рабочее пространство (для каждого агента): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, необязательный HEARTBEAT.md. Корневой файл memory.md с именем в нижнем регистре используется только как входные данные для исправления устаревшей конфигурации; openclaw doctor --fix может объединить его с MEMORY.md, если существуют оба файла.
  • Каталог состояния (~/.openclaw): конфигурация, состояние каналов и провайдеров, профили аутентификации, сеансы, журналы, общие Skills (~/.openclaw/skills).
Рабочее пространство по умолчанию — ~/.openclaw/workspace; его можно настроить:
Если бот «забывает» информацию после перезапуска, убедитесь, что Gateway при каждом запуске использует одно и то же рабочее пространство (в удалённом режиме используется рабочее пространство хоста Gateway, а не вашего локального ноутбука).Совет: чтобы поведение или предпочтение сохранялось надолго, попросите бота записать его в AGENTS.md или MEMORY.md, а не полагаться на историю чата.См. Рабочее пространство агента и Память.
Да. SOUL.md — один из файлов начальной загрузки рабочего пространства, внедряемых в контекст агента. Ограничение внедрения по умолчанию для каждого файла составляет 20000 символов; общий бюджет начальной загрузки для всех файлов составляет 60000 символов.Измените общие значения по умолчанию:
Или переопределите настройки одного агента в agents.list[].bootstrapMaxChars / bootstrapTotalMaxChars.Используйте /context, чтобы проверить исходные и внедрённые размеры, а также выяснить, произошло ли усечение. Сосредоточьте SOUL.md на манере речи, позиции и личности; рабочие правила поместите в AGENTS.md, а долговременные факты — в память.См. Контекст и Конфигурация агента.
Поместите рабочее пространство агента в приватный репозиторий git и создавайте его резервные копии в приватном хранилище (например, в приватном репозитории GitHub). Это сохранит память вместе с файлами AGENTS/SOUL/USER и позволит позднее восстановить «разум» помощника.Не добавляйте в коммиты ничего из ~/.openclaw (учётные данные, сеансы, токены, зашифрованные полезные нагрузки секретов). Для полного восстановления создавайте отдельные резервные копии рабочего пространства и каталога состояния.Документация: Рабочее пространство агента.
Да. Рабочее пространство — это рабочий каталог по умолчанию и основа памяти, а не строгая песочница. Относительные пути разрешаются внутри рабочего пространства; абсолютные пути могут обращаться к другим расположениям на хосте, если не включена песочница. Для изоляции используйте agents.defaults.sandbox или настройки песочницы для отдельных агентов. Чтобы репозиторий стал рабочим каталогом по умолчанию, укажите корень репозитория в workspace этого агента — сам репозиторий OpenClaw содержит только исходный код, поэтому храните рабочее пространство отдельно, если только вы намеренно не хотите, чтобы агент работал внутри него.
Состоянием сеансов управляет хост Gateway. В удалённом режиме нужное вам хранилище сеансов находится на удалённом компьютере, а не на вашем локальном ноутбуке. См. Управление сеансами.

​
Основы конфигурации

OpenClaw считывает необязательную конфигурацию в формате JSON5 из $OPENCLAW_CONFIG_PATH (по умолчанию: ~/.openclaw/openclaw.json). Если файл отсутствует, используются относительно безопасные значения по умолчанию, включая рабочее пространство по умолчанию ~/.openclaw/workspace.
Привязки не к loopback-интерфейсу требуют корректного способа аутентификации Gateway: аутентификации с общим секретом (токеном или паролем) либо gateway.auth.mode: "trusted-proxy" за правильно настроенным обратным прокси-сервером с учётом идентификации.
  • gateway.remote.token / .password сами по себе не включают локальную аутентификацию Gateway; локальные пути вызова могут использовать gateway.remote.* как резервный вариант, только если gateway.auth.* не задан.
  • Для аутентификации по паролю задайте gateway.auth.mode: "password" вместе с gateway.auth.password (или OPENCLAW_GATEWAY_PASSWORD).
  • Если gateway.auth.token / .password явно настроен через SecretRef, но не разрешается, разрешение завершается отказом без небезопасного продолжения (удалённый резервный вариант не маскирует ошибку).
  • Конфигурации Control UI с общим секретом проходят аутентификацию через connect.params.auth.token или connect.params.auth.password (хранятся в настройках приложения/интерфейса). Режимы с передачей идентификационных данных, такие как Tailscale Serve или trusted-proxy, вместо этого используют заголовки запросов — не помещайте общие секреты в URL-адреса.
  • При использовании gateway.auth.mode: "trusted-proxy" обратным прокси-серверам loopback на том же хосте требуются явно заданный gateway.auth.trustedProxy.allowLoopback = true и запись loopback в gateway.trustedProxies.
OpenClaw по умолчанию требует аутентификацию Gateway, в том числе для loopback. Если явный способ аутентификации не настроен, при запуске выбирается режим токена и создаётся токен только для этого запуска, поэтому локальные клиенты WS должны проходить аутентификацию. Это не позволяет другим локальным процессам обращаться к Gateway.Явно настройте gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN или OPENCLAW_GATEWAY_PASSWORD, если клиентам нужен постоянный секрет между перезапусками. Также можно выбрать режим пароля или trusted-proxy для обратных прокси-серверов с учётом идентификации. Чтобы открыть доступ через loopback, явно задайте gateway.auth.mode: "none". openclaw doctor --generate-gateway-token создаёт токен в любое время.
Gateway отслеживает конфигурацию и поддерживает горячую перезагрузку: gateway.reload.mode: "hybrid" (по умолчанию) применяет безопасные изменения без перезапуска и перезапускает систему при критических изменениях. Также поддерживаются hot, restart и off. Большинство изменений tools.*, политики agents.*, session.* и messages.* применяются немедленно без каких-либо действий по перезагрузке; изменения привязки/порта gateway.* требуют перезапуска.
Задайте cli.banner.taglineMode:
  • off: скрывает текст слогана, но сохраняет строку заголовка/версии баннера.
  • default: всегда использует All your chats, one OpenClaw..
  • random: чередующиеся забавные/сезонные слоганы (поведение по умолчанию).
  • Чтобы полностью отключить баннер, задайте переменную окружения OPENCLAW_HIDE_BANNER=1.
web_fetch работает без ключа API. web_search зависит от выбранного провайдера:Grok также может повторно использовать OAuth xAI из аутентификации модели (openclaw onboard --auth-choice xai-oauth).Рекомендуется: openclaw configure --section web и выберите провайдера.
Конфигурация веб-поиска для конкретного провайдера находится в plugins.entries.<plugin>.config.webSearch.*. Устаревшие пути провайдеров tools.web.search.* по-прежнему загружаются для совместимости, но не должны использоваться в новых конфигурациях. Конфигурация резервного веб-получения Firecrawl находится в plugins.entries.firecrawl.config.webFetch.*.
  • Списки разрешений: добавьте web_search/web_fetch/x_search или group:web для всех трёх.
  • web_fetch включён по умолчанию.
  • Если tools.web.fetch.provider не указан, OpenClaw автоматически определяет первого готового резервного провайдера получения данных по доступным учётным данным; официальный плагин Firecrawl предоставляет этот резервный вариант.
  • Демоны считывают переменные окружения из ~/.openclaw/.env (или из окружения службы).
Документация: Веб-инструменты.
config.apply заменяет всю конфигурацию; частичный объект удаляет всё остальное.Текущая версия OpenClaw предотвращает большинство случайных перезаписей:
  • Операции записи конфигурации, выполняемые OpenClaw, перед записью проверяют полную конфигурацию после изменения.
  • Недопустимые или разрушительные операции записи, выполняемые OpenClaw, отклоняются и сохраняются как openclaw.json.rejected.*.
  • Если прямое редактирование нарушает запуск или горячую перезагрузку, Gateway безопасно завершает работу или пропускает перезагрузку; он не перезаписывает openclaw.json.
  • openclaw doctor --fix отвечает за восстановление, может восстановить последнюю заведомо исправную версию и сохраняет отклонённый файл как openclaw.json.clobbered.*.
Восстановление:
  • Проверьте openclaw logs --follow на наличие Invalid config at, Config write rejected: или config reload skipped (invalid config).
  • Проверьте новейший openclaw.json.clobbered.* или openclaw.json.rejected.* рядом с активной конфигурацией.
  • Выполните openclaw config validate и openclaw doctor --fix.
  • Скопируйте обратно только нужные ключи с помощью openclaw config set или config.patch.
  • Если нет последней заведомо исправной версии или отклонённых данных, восстановите конфигурацию из резервной копии либо повторно выполните openclaw doctor и настройте каналы и модели заново.
  • При неожиданной потере данных сообщите об ошибке, приложив последнюю известную конфигурацию или резервную копию. Локальный агент программирования часто может восстановить рабочую конфигурацию по журналам или истории.
Как избежать проблемы: используйте openclaw config set для небольших изменений, openclaw configure для интерактивного редактирования, config.schema.lookup для проверки незнакомого пути (возвращает поверхностный узел схемы и сводки его непосредственных дочерних элементов), а config.patch — для частичного редактирования через RPC; применяйте config.apply только для полной замены конфигурации. Инструмент среды выполнения gateway, доступный агенту, отказывается перезаписывать tools.exec.ask / tools.exec.security даже через устаревшие псевдонимы tools.bash.*.Документация: Конфигурация, Настройка, Устранение неполадок Gateway, Doctor.
Распространённая схема: один Gateway (например, Raspberry Pi), а также узлы и агенты.
  • Gateway (центральный): управляет каналами (Signal/WhatsApp), маршрутизацией и сеансами.
  • Узлы (устройства): компьютеры Mac и устройства iOS/Android подключаются как периферийные устройства и предоставляют локальные инструменты (system.run, canvas, camera).
  • Агенты (рабочие процессы): отдельные среды рассуждений и рабочие пространства для специальных ролей (например, эксплуатационных задач и личных данных).
  • Субагенты: запускают фоновую работу из основного агента для параллельного выполнения.
  • TUI: подключается к Gateway и позволяет переключать агентов и сеансы.
Документация: Узлы, Удалённый доступ, Маршрутизация между несколькими агентами, Субагенты, TUI.
Да:
Значение по умолчанию — false (с графическим интерфейсом). Режим без графического интерфейса чаще вызывает срабатывание защиты от ботов на некоторых сайтах (X/Twitter часто блокирует такие сеансы). Он использует тот же движок Chromium и подходит для большинства задач автоматизации; основное отличие — отсутствие видимого окна браузера (для визуального контроля используйте снимки экрана). См. Браузер.
Укажите путь к исполняемому файлу Brave (или любого браузера на основе Chromium) в browser.executablePath и перезапустите Gateway. См. Браузер.

​
Удалённые Gateway и узлы

Сообщения Telegram обрабатываются Gateway, который запускает агента и только затем обращается к узлам через WebSocket Gateway, когда требуется инструмент узла:Telegram -> Gateway -> Агент -> node.* -> Узел -> Gateway -> TelegramУзлы не видят входящий трафик провайдера; они получают только вызовы RPC узлов.
Подключите компьютер как узел. Gateway работает в другом месте, но может вызывать инструменты node.* (экран, камера, система) на вашем локальном компьютере через WebSocket Gateway.
  1. Запустите Gateway на постоянно работающем хосте (VPS или домашнем сервере).
  2. Подключите хост Gateway и свой компьютер к одной сети tailnet.
  3. Убедитесь, что WebSocket Gateway доступен (привязка к tailnet или туннель SSH).
  4. Откройте локальное приложение macOS и подключитесь в режиме Remote over SSH (или напрямую через tailnet), чтобы оно зарегистрировалось как узел.
  5. Подтвердите узел:
Отдельный мост TCP не требуется; узлы подключаются через WebSocket Gateway.Напоминание о безопасности: сопряжение узла macOS разрешает system.run на этом компьютере. Подключайте только доверенные устройства; ознакомьтесь с разделом Безопасность.Документация: Узлы, Протокол Gateway, Удалённый режим macOS, Безопасность.
Сначала проверьте основное:
Затем проверьте аутентификацию и маршрутизацию: если вы используете Tailscale Serve, убедитесь, что gateway.auth.allowTailscale задан правильно; если вы подключаетесь через туннель SSH, убедитесь, что туннель работает и направлен на правильный порт; также убедитесь, что списки разрешений для личных сообщений и групп включают вашу учётную запись.Документация: Tailscale, Удалённый доступ, Каналы.
Да, хотя встроенного моста между ботами нет.Самый простой способ: используйте обычный канал чата, доступный обоим ботам (Slack/Telegram/WhatsApp). Пусть бот A отправит сообщение боту B, после чего бот B ответит обычным образом.Мост CLI (универсальный): запустите сценарий, который вызывает другой Gateway через openclaw agent --message ... --deliver, указав чат, прослушиваемый другим ботом. Если один из ботов находится на удалённом VPS, направьте CLI на этот удалённый Gateway через SSH/Tailscale (см. Удалённый доступ):
Добавьте защитное ограничение, чтобы два бота не образовали бесконечный цикл (ответы только на упоминания, списки разрешённых каналов или правило «не отвечать на сообщения ботов»).Документация: Удалённый доступ, CLI агента, Отправка сообщений агентом.
Нет. Один Gateway размещает несколько агентов, каждый со своим рабочим пространством, настройками моделей по умолчанию и маршрутизацией. Это стандартная схема, которая намного дешевле и проще, чем отдельный VPS для каждого агента. Используйте отдельные VPS только для строгой изоляции (границ безопасности) или существенно различающихся конфигураций, которые не должны быть общими.
Да: узлы — основной способ получить доступ к ноутбуку из удалённого Gateway, предоставляющий больше возможностей, чем доступ к оболочке. Gateway работает на macOS/Linux (в Windows — через WSL2) и потребляет мало ресурсов (достаточно небольшого VPS или устройства класса Raspberry Pi; 4 ГБ ОЗУ вполне хватает), поэтому распространённая схема включает постоянно работающий хост и ноутбук в качестве узла.
  • Входящий SSH не требуется — узлы сами подключаются к WebSocket Gateway через сопряжение устройств.
  • Более безопасное управление выполнением — system.run ограничивается списками разрешений и подтверждениями узла на этом ноутбуке.
  • Больше инструментов устройства — помимо system.run, узлы предоставляют canvas, camera и screen.
  • Локальная автоматизация браузера — оставьте Gateway на VPS, а Chrome запускайте локально через хост узла либо подключитесь к локальному Chrome через Chrome MCP.
SSH подходит для эпизодического доступа к оболочке; узлы удобнее для постоянных рабочих процессов агентов и автоматизации устройств.Документация: Узлы, CLI узлов, Браузер.
Нет. На одном хосте должен работать только один Gateway, если вы намеренно не используете изолированные профили (см. Несколько Gateway). Узлы — это периферийные устройства, подключающиеся к Gateway (узлы iOS/Android или «режим узла» macOS в приложении строки меню). Сведения о хостах узлов без графического интерфейса и управлении через CLI см. в разделе CLI хоста узла.Полный перезапуск требуется для изменений gateway, discovery и предоставляемых размещёнными плагинами поверхностей.
Да:
  • config.schema.lookup: проверить одно поддерево конфигурации вместе с его неглубоким узлом схемы, соответствующей подсказкой интерфейса и сводками непосредственных дочерних элементов перед записью.
  • config.get: получить текущий снимок и хеш.
  • config.patch: безопасное частичное обновление (предпочтительно для большинства изменений через RPC); выполняет горячую перезагрузку, когда это возможно, и перезапуск, когда это необходимо.
  • config.apply: проверить и полностью заменить конфигурацию; выполняет горячую перезагрузку, когда это возможно, и перезапуск, когда это необходимо.
  • Доступный агенту инструмент среды выполнения gateway по-прежнему отказывается перезаписывать tools.exec.ask / tools.exec.security; устаревшие псевдонимы tools.bash.* нормализуются в те же защищённые пути.
Задаёт рабочее пространство и ограничивает круг пользователей, которые могут активировать бота.
  1. Установите и выполните вход на VPS:
  2. Установите приложение Tailscale на Mac и выполните вход, используя ту же сеть tailnet.
  3. Включите MagicDNS в консоли администрирования Tailscale, чтобы у VPS было постоянное имя.
  4. Используйте имя хоста в tailnet: SSH ssh user@your-vps.tailnet-xxxx.ts.net; WebSocket Gateway ws://your-vps.tailnet-xxxx.ts.net:18789.
Чтобы использовать интерфейс управления без SSH, включите Tailscale Serve на VPS:
Gateway останется привязанным к loopback-интерфейсу, а HTTPS будет доступен через Tailscale. См. Tailscale.
Serve предоставляет доступ к интерфейсу управления и WebSocket Gateway; узлы подключаются через ту же конечную точку WebSocket Gateway.
  1. Убедитесь, что VPS и Mac находятся в одной сети tailnet.
  2. Используйте приложение macOS в удалённом режиме (в качестве цели SSH можно указать имя хоста в tailnet) — оно создаёт туннель к порту Gateway и подключается как узел.
  3. Подтвердите узел:
Документация: Протокол Gateway, Обнаружение, удалённый режим macOS.
Если на втором ноутбуке нужны только локальные инструменты (экран, камера, выполнение команд), добавьте его как узел — один Gateway без дублирования конфигурации. Локальные инструменты узла сейчас доступны только в macOS. Устанавливайте второй Gateway только для строгой изоляции или двух полностью независимых ботов.Документация: Узлы, CLI узлов, Несколько экземпляров Gateway.

​
Переменные окружения и загрузка .env

OpenClaw считывает переменные окружения из родительского процесса (оболочки, launchd/systemd, CI и т. д.), а также загружает:
  • .env из текущего рабочего каталога.
  • глобальный резервный файл .env из ~/.openclaw/.env ($OPENCLAW_STATE_DIR/.env).
Ни один из файлов .env не переопределяет существующие переменные окружения. Исключение составляют ключи учётных данных провайдера в файле .env рабочего пространства: такие ключи, как GEMINI_API_KEY, XAI_API_KEY или MISTRAL_API_KEY (а также другие переменные окружения аутентификации встроенных провайдеров), игнорируются в файле .env рабочего пространства и должны находиться в окружении процесса, ~/.openclaw/.env или конфигурации env.Переменные окружения, заданные непосредственно в конфигурации, применяются только при их отсутствии в окружении процесса:
Полный порядок приоритетов и список источников см. в разделе /environment.
Есть два способа исправить это:
  1. Поместите отсутствующие ключи в ~/.openclaw/.env, чтобы они загружались, даже если служба не наследует окружение оболочки.
  2. Включите импорт из оболочки (необязательная функция для удобства):
    При этом запускается ваша оболочка входа и импортируются только отсутствующие ожидаемые ключи без переопределения существующих. Эквивалентные переменные окружения: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.
openclaw models status сообщает, включён ли импорт окружения оболочки. «Shell env: off» не означает, что ваши переменные окружения отсутствуют, — это означает лишь, что OpenClaw не будет автоматически загружать вашу оболочку входа.Если Gateway работает как служба (launchd/systemd), он не наследует окружение оболочки. Чтобы исправить это, поместите токен в ~/.openclaw/.env, включите env.shellEnv.enabled: true или добавьте его в конфигурацию env (применяется только при отсутствии значения), затем перезапустите Gateway и снова проверьте состояние:
Токены Copilot разрешаются в следующем порядке: OPENCLAW_GITHUB_TOKEN, затем COPILOT_GITHUB_TOKEN, затем GH_TOKEN, затем GITHUB_TOKEN.См. /concepts/model-providers и /environment.

​
Сеансы и несколько чатов

Отправьте /new или /reset отдельным сообщением. См. Управление сеансами.
Да. По умолчанию используется ежедневная политика сброса: сеанс сменяется в настроенный локальный час на хосте Gateway (session.reset.atHour, значение по умолчанию — 4, 0-23) с учётом времени начала текущего сеанса. Чтобы вместо этого использовать сброс по бездействию, задайте mode: "idle" и session.reset.idleMinutes: сеанс завершится после периода бездействия, отсчитываемого от последнего реального взаимодействия, а не от системных событий Heartbeat/Cron/выполнения команд.
resetByType поддерживает direct (устаревший псевдоним dm), group и thread. Устаревший параметр верхнего уровня session.idleMinutes по-прежнему работает как псевдоним для совместимости, задающий сброс по умолчанию в режиме бездействия, если блок session.reset/resetByType не задан. Сеансы с активным CLI-сеансом, принадлежащим провайдеру, не прерываются неявным ежедневным сбросом по умолчанию. Полное описание жизненного цикла см. в разделе Управление сеансами.
Да, с помощью маршрутизации между несколькими агентами и субагентов: один агент-координатор и несколько рабочих агентов с собственными рабочими пространствами и моделями.Это лучше воспринимать как интересный эксперимент: он требует много токенов и зачастую менее эффективен, чем один бот с отдельными сеансами. Типичная схема — один бот, с которым вы общаетесь, разные сеансы для параллельной работы и запуск субагентов по мере необходимости.Документация: Маршрутизация между несколькими агентами, Субагенты, CLI агентов.
Контекст сеанса ограничен размером контекстного окна модели. Длинные чаты, большой объём вывода инструментов или множество файлов могут привести к Compaction или обрезке.
  • Попросите бота обобщить текущее состояние и записать его в файл.
  • Используйте /compact перед длительными задачами и /new при смене темы.
  • Храните важный контекст в рабочем пространстве и просите бота повторно читать его.
  • Используйте субагентов для длительной или параллельной работы, чтобы основной чат оставался компактным.
  • Если это происходит часто, выберите модель с более широким контекстным окном.
Полный сброс без интерактивного взаимодействия:
Затем снова запустите настройку:
Если мастер первоначальной настройки обнаружит существующую конфигурацию, он также предложит сброс; см. Первоначальная настройка (CLI). Если вы использовали профили (--profile / OPENCLAW_PROFILE), сбросьте каждый каталог состояния (по умолчанию ~/.openclaw-<profile>). Сброс только для разработки: openclaw gateway --dev --reset удаляет конфигурацию разработки, учётные данные, сеансы и рабочее пространство.
  • Compaction (сохраняет разговор, обобщая старые реплики): /compact или /compact <instructions>, чтобы задать указания для сводки.
  • Сброс (новый идентификатор сеанса для того же ключа чата): /new или /reset.
Если проблема повторяется, настройте очистку сеанса (agents.defaults.contextPruning), чтобы удалять старый вывод инструментов, или используйте модель с более широким контекстным окном.Документация: Compaction, Очистка сеанса, Управление сеансами.
Ошибка проверки на стороне провайдера: модель создала блок tool_use без обязательного поля input. Обычно это означает, что история сеанса устарела или повреждена, что часто происходит после длинных веток обсуждения или изменения инструмента либо схемы.Решение: начните новый сеанс, отправив /new отдельным сообщением.
По умолчанию Heartbeat запускается каждые 30m или каждые 1h, если разрешённый режим аутентификации — OAuth/аутентификация по токену Anthropic, включая повторное использование Claude CLI, а heartbeat.every не задан. Настройка или отключение:
Если HEARTBEAT.md существует, но фактически пуст (содержит только пустые строки, комментарии Markdown/HTML, заголовки ATX, маркеры ограждений или пустые заготовки элементов списка), OpenClaw пропускает запуск Heartbeat для экономии вызовов API. Если файл отсутствует, Heartbeat всё равно запускается, а модель решает, что делать.Переопределения для отдельных агентов задаются через agents.list[].heartbeat. Документация: Heartbeat.
Нет. OpenClaw работает с вашей собственной учётной записью: если вы состоите в группе, OpenClaw может её видеть. По умолчанию ответы в группах заблокированы, пока вы не разрешите отправителей (groupPolicy: "allowlist").Чтобы разрешить ответы в группе только вам:
Самый быстрый способ — отслеживать журналы и отправить тестовое сообщение в группу.
Найдите chatId (или from), оканчивающийся на @g.us, например 1234567890-1234567890@g.us.Если группа уже настроена или добавлена в список разрешённых, выведите список групп из конфигурации:
Документация: WhatsApp, Каталог, Журналы.
Две распространённые причины: по умолчанию включено требование упоминания (необходимо упомянуть бота через @ или обеспечить соответствие mentionPatterns) либо вы настроили channels.whatsapp.groups без "*", а группа не включена в список разрешённых.См. Группы и Групповые сообщения.
По умолчанию личные чаты объединяются в основной сеанс. У групп и каналов есть собственные ключи сеансов, а темы Telegram и ветки Discord являются отдельными сеансами. См. Группы и Групповые сообщения.
Жёстких ограничений нет — можно создать десятки и даже сотни, но учитывайте следующее:
  • Рост объёма данных на диске: активные сеансы и расшифровки хранятся в базе данных SQLite каждого агента; устаревшие и архивные артефакты по-прежнему могут накапливаться в ~/.openclaw/agents/<agentId>/sessions/.
  • Расход токенов: большее число агентов означает больше одновременных обращений к моделям.
  • Операционные затраты: профили аутентификации, рабочие пространства и маршрутизация каналов для каждого агента.
Оставляйте одно активное рабочее пространство на агента (agents.defaults.workspace), удаляйте старые сеансы с помощью openclaw sessions cleanup, если объём данных на диске растёт (не изменяйте активное состояние SQLite вручную), и используйте openclaw doctor для обнаружения лишних рабочих пространств и несоответствий профилей.
Да, с помощью маршрутизации между несколькими агентами: запустите несколько изолированных агентов и маршрутизируйте входящие сообщения по каналу, учётной записи или собеседнику. Slack поддерживается в качестве канала и может быть привязан к определённым агентам.Доступ к браузеру предоставляет широкие возможности, но не позволяет «делать всё, что может человек»: защита от ботов, CAPTCHA и MFA всё ещё могут блокировать автоматизацию. Для наиболее надёжного управления используйте локальный Chrome MCP на хосте или CDP на компьютере, где фактически запущен браузер.Рекомендуемая конфигурация: постоянно работающий хост Gateway (VPS/Mac mini), по одному агенту на каждую роль (с привязками), каналы Slack, привязанные к этим агентам, и локальный браузер через Chrome MCP или Node при необходимости.Документация: Маршрутизация между несколькими агентами, Slack, Браузер, Узлы.

​
Модели, переключение при сбое и профили аутентификации

Вопросы и ответы о моделях — значения по умолчанию, выбор, псевдонимы, переключение, переключение при сбое и профили аутентификации — находятся в разделе Часто задаваемые вопросы о моделях.

​
Gateway: порты, сообщение «уже запущен» и удалённый режим

gateway.port управляет единым мультиплексированным портом для WebSocket и HTTP (Control UI, обработчики и т. д.). Приоритет:
«Running» — это представление диспетчера процессов (launchd/systemd/schtasks), а проверка подключения означает, что CLI фактически подключается к WebSocket Gateway. Ориентируйтесь на следующие строки из openclaw gateway status: Probe target: (URL, использованный проверкой), Listening: (что фактически привязано к порту), Last gateway error: (распространённая первопричина, когда процесс работает, но порт не прослушивается).
Вы редактируете один файл конфигурации, а служба использует другой (часто из-за несоответствия --profile / OPENCLAW_STATE_DIR).Чтобы исправить это, выполните следующую команду из той же среды --profile, которую должна использовать служба:
OpenClaw применяет блокировку среды выполнения, сразу привязывая прослушиватель WebSocket при запуске (по умолчанию ws://127.0.0.1:18789). Если привязка завершается ошибкой EADDRINUSE, возникает исключение GatewayLockError («другой экземпляр Gateway уже прослушивает порт»).Решение: остановите другой экземпляр, освободите порт или запустите с openclaw gateway --port <port>.
Задайте gateway.mode: "remote" и укажите удалённый URL WebSocket, при необходимости добавив удалённые учётные данные с общим секретом:
  • openclaw gateway запускается, только если gateway.mode имеет значение local (или если передан переопределяющий флаг).
  • Приложение macOS отслеживает файл конфигурации и переключает режимы без перезапуска при изменении этих значений.
  • gateway.remote.token / .password являются только клиентскими учётными данными для удалённого подключения; сами по себе они не включают аутентификацию локального Gateway.
Способ аутентификации Gateway не соответствует способу аутентификации пользовательского интерфейса.Факты (из кода):
  • Control UI хранит токен в sessionStorage с областью действия, ограниченной текущей вкладкой браузера и выбранным URL Gateway, поэтому обновление страницы в той же вкладке продолжает работать без долговременного хранения токена в localStorage.
  • При AUTH_TOKEN_MISMATCH доверенные клиенты могут выполнить одну ограниченную повторную попытку с кешированным токеном устройства, если Gateway возвращает указания для повторной попытки (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
  • При этой повторной попытке с кешированным токеном повторно используются кешированные утверждённые области доступа, сохранённые вместе с токеном устройства; вызывающие стороны с явным deviceToken / явным scopes сохраняют запрошенный набор областей доступа, а не наследуют кешированные области.
  • Вне этого пути повторной попытки приоритет аутентификации подключения следующий: сначала явно заданный общий токен или пароль, затем явно заданный deviceToken, после этого сохранённый токен устройства и затем загрузочный токен.
  • Встроенная начальная настройка с помощью кода настройки возвращает токен устройства Node с scopes: [], а также ограниченный токен передачи оператору для доверенной настройки с мобильного устройства. Передача оператору позволяет читать нативную конфигурацию этапа настройки, но не предоставляет областей доступа для изменения сопряжения или operator.admin.
Решение:
  • Самый быстрый способ: openclaw dashboard (выводит и копирует URL панели управления, пытается открыть её; в среде без графического интерфейса показывает подсказку по SSH).
  • Если токена ещё нет: openclaw doctor --generate-gateway-token.
  • При удалённом подключении сначала создайте туннель с помощью ssh -N -L 18789:127.0.0.1:18789 user@host, затем откройте http://127.0.0.1:18789/.
  • В режиме общего секрета задайте gateway.auth.token / OPENCLAW_GATEWAY_TOKEN или gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, затем вставьте соответствующий секрет в настройках Control UI.
  • В режиме Tailscale Serve убедитесь, что gateway.auth.allowTailscale включён и вы открываете URL Serve, а не прямой URL loopback или tailnet, который обходит заголовки идентификации Tailscale.
  • В режиме доверенного прокси убедитесь, что подключение проходит через настроенный прокси с поддержкой идентификации. Для loopback-прокси на том же хосте также требуется gateway.auth.trustedProxy.allowLoopback = true.
  • Если после одной повторной попытки несоответствие сохраняется, замените или повторно утвердите токен сопряжённого устройства:
  • Если замена отклонена: сеансы сопряжённых устройств могут заменять токен только собственного устройства, если у них также нет operator.admin, а явно заданные значения --scope не могут превышать текущие операторские области доступа вызывающей стороны.
  • Если проблема сохраняется: openclaw status --all и Устранение неполадок. Подробности об аутентификации см. в разделе Панель управления.
При привязке tailnet выбирается IP-адрес Tailscale из сетевых интерфейсов (100.64.0.0/10). Если компьютер не подключён к Tailscale или интерфейс отключён, Gateway переключается на loopback вместо предоставления доступа через другой сетевой интерфейс.Решение: запустите Tailscale на этом хосте и перезапустите Gateway либо явно переключитесь на gateway.bind: "loopback" / "lan".tailnet задаётся явно; auto предпочитает loopback. Используйте gateway.bind: "tailnet", чтобы ограничить доступ не через loopback сетью Tailnet, сохранив обязательный прослушиватель 127.0.0.1 на том же хосте.
Обычно нет: один Gateway может обслуживать несколько каналов обмена сообщениями и агентов. Используйте несколько экземпляров Gateway только для резервирования (например, для аварийного бота) или строгой изоляции и изолируйте каждый из них с помощью собственных OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, agents.defaults.workspace и уникального gateway.port.Рекомендуется: openclaw --profile <name> ... для каждого экземпляра (автоматически создаёт ~/.openclaw-<name>), уникальный gateway.port для конфигурации каждого профиля (или --port при ручном запуске) и отдельная служба для каждого профиля с openclaw --profile <name> gateway install.Профили также добавляют суффиксы к именам служб: launchd ai.openclaw.<profile>, systemd openclaw-gateway-<profile>.service, Windows OpenClaw Gateway (<profile>). Модуль systemd без уточнения openclaw-gateway существует только для профиля по умолчанию; устаревшее имя модуля systemd до переименования clawdbot-gateway переносится автоматически.Полное руководство: Несколько экземпляров Gateway.
Gateway — это сервер WebSocket, который ожидает, что первым сообщением будет кадр connect. Любое другое сообщение приводит к закрытию подключения с кодом 1008 (нарушение политики).Распространённые причины: вы открыли URL HTTP в браузере вместо использования клиента WS, указали неправильный порт или путь либо прокси или туннель удалил заголовки аутентификации или отправил запрос, не предназначенный для Gateway.Решение: используйте URL WS (ws://<host>:18789 или wss://... поверх HTTPS), не открывайте порт WS в обычной вкладке браузера и передавайте токен или пароль в кадре connect, когда аутентификация включена. Пример для CLI/TUI:
Подробности протокола: Протокол Gateway.

​
Ведение журналов и отладка

Файловые журналы (структурированные): /tmp/openclaw/openclaw-YYYY-MM-DD.log. Задайте постоянный путь с помощью logging.file, уровень файлового журнала — с помощью logging.level, а детализацию вывода в консоль — с помощью --verbose и logging.consoleLevel.Самый быстрый способ отслеживания:
Журналы службы или диспетчера процессов (когда Gateway запускается через launchd/systemd):
  • Стандартный вывод launchd в macOS: ~/Library/Logs/openclaw/gateway.log (профили используют gateway-<profile>.log; стандартный поток ошибок отключён).
  • Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager.
  • Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST.
Дополнительные сведения см. в разделе Устранение неполадок.
Если вы запускаете Gateway вручную, openclaw gateway --force может освободить порт. См. Gateway.
Три режима установки в Windows:1) Локальная настройка Windows Hub: нативное приложение управляет локальным Gateway в WSL, принадлежащим приложению. Откройте OpenClaw Companion из меню «Пуск» или области уведомлений, затем используйте Gateway Setup или вкладку Connections.2) Настроенный вручную Gateway в WSL2: Gateway работает внутри Linux.
Если вы не устанавливали службу, запустите её на переднем плане: openclaw gateway run.3) Нативные Windows CLI/Gateway: работают непосредственно в Windows.
Если вы запускаете его вручную (без службы): openclaw gateway run.Документация: Windows, Руководство по эксплуатации службы Gateway.
Быстрая проверка состояния:
Распространённые причины: данные аутентификации модели не загружены на хосте Gateway (проверьте models status), сопряжение канала или список разрешённых блокирует ответы (проверьте конфигурацию и журналы канала) либо WebChat/Dashboard открыт без правильного токена. При удалённом подключении убедитесь, что туннель или соединение Tailscale установлено и WebSocket Gateway доступен.Документация: Каналы, Устранение неполадок, Удалённый доступ.
Обычно это означает, что UI потерял соединение WebSocket. Проверьте: запущен ли Gateway (openclaw gateway status)? Исправно ли он работает (openclaw status)? Есть ли у UI правильный токен (openclaw dashboard)? При удалённом подключении работает ли туннель или соединение Tailscale?Затем просматривайте журналы в реальном времени:
Документация: Dashboard, Удалённый доступ, Устранение неполадок.
Затем сопоставьте сообщение об ошибке:
  • BOT_COMMANDS_TOO_MUCH: в меню Telegram слишком много пунктов. OpenClaw уже сокращает его до ограничения Telegram и повторяет попытку с меньшим количеством команд, но некоторые пункты меню всё равно могут быть отброшены. Сократите количество команд плагинов, навыков или пользовательских команд либо отключите channels.telegram.commands.native, если меню вам не нужно.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed! или аналогичные сетевые ошибки: на VPS или при работе через прокси убедитесь, что исходящие HTTPS-соединения разрешены и DNS работает для api.telegram.org.
Если Gateway находится на удалённом хосте, проверьте журналы на хосте Gateway.Документация: Telegram, Устранение неполадок каналов.
В TUI используйте /status, чтобы увидеть текущее состояние. Если вы ожидаете ответы в канале чата, убедитесь, что доставка включена (/deliver on).Документация: TUI, Команды с косой чертой.
Если вы установили службу (launchd в macOS, systemd в Linux):
При запуске на переднем плане остановите её с помощью Ctrl-C, затем выполните openclaw gateway run.Документация: Руководство по эксплуатации службы Gateway.
openclaw gateway restart перезапускает фоновую службу (launchd/systemd). openclaw gateway запускает Gateway на переднем плане для текущего сеанса терминала. Используйте подкоманды Gateway, если вы установили службу; для однократного запуска используйте обычный запуск на переднем плане.
Запустите Gateway с параметром --verbose, чтобы получить более подробный вывод в консоли, затем изучите файл журнала на предмет ошибок аутентификации каналов, маршрутизации моделей и RPC.

​
Медиафайлы и вложения

Исходящие вложения от агента должны использовать структурированные поля медиафайлов, например media, mediaUrl, path или filePath. См. Настройка ассистента OpenClaw и Отправка агентом.
Также проверьте следующее: целевой канал поддерживает исходящие медиафайлы и не заблокирован списками разрешённых; размер файла не превышает ограничений провайдера (изображения масштабируются так, чтобы максимальная сторона составляла 2048px); tools.fs.workspaceOnly=true ограничивает отправку по локальным путям файлами из рабочей области, временного каталога или хранилища медиафайлов, а также файлами, проверенными песочницей; tools.fs.workspaceOnly=false (по умолчанию) позволяет при структурированной отправке локальных медиафайлов использовать локальные файлы хоста, которые агент уже может читать, для медиафайлов и безопасных типов документов (изображения, аудио, видео, PDF, документы Office и проверенные текстовые документы, например Markdown/MD, TXT, JSON, YAML/YML). Это не сканер секретов: доступный агенту файл secret.txt или config.json можно прикрепить, если расширение и проверка содержимого соответствуют требованиям. Храните конфиденциальные файлы вне доступных агенту путей или используйте tools.fs.workspaceOnly=true для более строгой отправки по локальным путям.См. Изображения.

​
Безопасность и управление доступом

Считайте входящие личные сообщения недоверенными данными. Настройки по умолчанию снижают риск:
  • По умолчанию в каналах с поддержкой личных сообщений используется сопряжение: неизвестные отправители получают код сопряжения, а их сообщение не обрабатывается. Подтвердите доступ с помощью openclaw pairing approve --channel <channel> [--account <id>] <code>. Количество ожидающих запросов ограничено 3 на канал; если код не пришёл, проверьте openclaw pairing list --channel <channel> [--account <id>].
  • Для публичного открытия личных сообщений требуется явное согласие (dmPolicy: "open" и список разрешённых "*").
Выполните openclaw doctor, чтобы выявить рискованные политики личных сообщений.
Нет. Внедрение подсказок связано с недоверенным содержимым, а не только с тем, кто может отправлять боту личные сообщения. Если ваш ассистент читает внешнее содержимое (результаты веб-поиска или загрузки, страницы браузера, электронные письма, документы, вложения, вставленные журналы), оно может содержать инструкции, пытающиеся перехватить управление моделью, даже если отправитель только вы.Наибольший риск возникает при включённых инструментах: модель могут обманом заставить вывести контекст или вызвать инструменты от вашего имени. Сократите потенциальный ущерб:
  • используйте агента-«читателя» только для чтения или без инструментов, чтобы суммировать недоверенное содержимое
  • не включайте web_search / web_fetch / browser для агентов с доступом к инструментам
  • также считайте декодированный текст файлов и документов недоверенным: OpenResponses input_file и извлечение текста из медиа-вложений помещают извлечённый текст в явные маркеры границ внешнего содержимого, а не передают необработанный текст файла
  • используйте песочницу и строгие списки разрешённых инструментов
Подробнее: Безопасность.
Язык и среда выполнения имеют значение, но для персонального агента это не основной риск. Практические риски связаны с доступностью Gateway, кругом лиц, которые могут отправлять сообщения боту, внедрением подсказок, областью действия инструментов, обращением с учётными данными, доступом к браузеру, доступом к выполнению команд и доверием к сторонним навыкам и плагинам.Rust и WASM могут обеспечить более строгую изоляцию для некоторых классов кода, но не решают проблемы внедрения подсказок, некорректных списков разрешённых, публичной доступности Gateway, чрезмерно широких полномочий инструментов или уже выполненного входа в конфиденциальные учётные записи в профиле браузера. Считайте основными следующие меры: обеспечьте приватность или аутентификацию Gateway, используйте сопряжение и списки разрешённых для личных сообщений и групп, запрещайте рискованные инструменты или запускайте их в песочнице при работе с недоверенными данными, устанавливайте только доверенные плагины и навыки и выполняйте openclaw security audit --deep после изменений конфигурации.Подробнее: Безопасность, Песочница.
Более безопасная базовая конфигурация: Gateway привязан к loopback или доступен только через аутентифицированный приватный доступ (tailnet, туннель SSH, аутентификация по токену или паролю либо правильно настроенный доверенный прокси); личные сообщения работают в режиме pairing или allowlist; группы внесены в список разрешённых, а обработка сообщений требует упоминания, если только все участники не являются доверенными; инструменты высокого риска (exec, browser, gateway, cron) запрещены или строго ограничены для агентов, читающих недоверенное содержимое; песочница включена там, где при выполнении инструментов необходимо сократить потенциальный ущерб.В первую очередь исправьте публичную привязку без аутентификации, открытые личные сообщения или группы с доступом к инструментам и открытый доступ к управлению браузером. Подробнее: openclaw security audit.
Относитесь к сторонним навыкам и плагинам как к коду, которому вы решили доверять. Страницы навыков ClawHub показывают состояние проверки перед установкой, но проверки не являются исчерпывающей границей безопасности. OpenClaw не выполняет встроенную локальную блокировку опасного кода при установке или обновлении плагинов и навыков; используйте управляемый оператором security.installPolicy для локальных решений о разрешении или блокировке.Более безопасный подход: отдавайте предпочтение доверенным авторам и закреплённым версиям, изучайте навык или плагин перед включением, используйте узкие списки разрешённых плагинов и навыков, запускайте процессы с недоверенными входными данными в песочнице с минимальным набором инструментов и не предоставляйте стороннему коду широкий доступ к файловой системе, выполнению команд, браузеру или секретам.Подробнее: Skills, Плагины, Безопасность.
Да, для большинства конфигураций. Изоляция бота с помощью отдельных учётных записей и номеров телефона сокращает потенциальный ущерб в случае сбоя и упрощает смену учётных данных или отзыв доступа без воздействия на ваши личные учётные записи.Начните с малого: предоставьте доступ только к действительно необходимым инструментам и учётным записям, а при необходимости расширьте его позже.Документация: Безопасность, Сопряжение.
Мы не рекомендуем предоставлять полную автономию при работе с личными сообщениями. Самый безопасный подход: оставьте личные сообщения в режиме сопряжения или используйте строгий список разрешённых, выделите отдельный номер или учётную запись, если бот должен отправлять сообщения от вашего имени, и позвольте ему подготавливать черновики, которые вы будете подтверждать перед отправкой.Для экспериментов используйте отдельную изолированную учётную запись. См. Безопасность.
Да, если агент работает только в чате, а входные данные являются доверенными. Модели меньшего уровня более уязвимы для перехвата инструкций, поэтому не используйте их для агентов с доступом к инструментам или при чтении недоверенного содержимого. Если вам необходимо использовать модель меньшего размера, строго ограничьте инструменты и запускайте её в песочнице. См. Безопасность.
Коды сопряжения отправляются только, когда неизвестный отправитель пишет боту и включён параметр dmPolicy: "pairing"; сам по себе /start код не создаёт.Проверьте ожидающие запросы:
Для немедленного доступа добавьте идентификатор отправителя в список разрешённых или задайте dmPolicy: "open" для этой учётной записи.
Нет. По умолчанию для личных сообщений WhatsApp используется политика сопряжения. Неизвестные отправители получают только код сопряжения; их сообщение не обрабатывается. OpenClaw отвечает только в чатах, из которых получает сообщения, или при явной отправке, инициированной вами.
Запрос номера телефона в мастере задаёт ваш список разрешённых/владельца, чтобы разрешить ваши собственные личные сообщения, — он не используется для автоматической отправки. При использовании личного номера WhatsApp укажите этот номер и включите channels.whatsapp.selfChatMode.

​
Команды чата, прерывание задач и «оно не останавливается»

Большинство внутренних сообщений и сообщений инструментов отображаются, только если для этого сеанса включён режим подробного вывода, трассировки или рассуждений.Исправьте это в том чате, где они отображаются:
Если лишние сообщения по-прежнему отображаются, проверьте настройки сеанса в интерфейсе управления и задайте для подробного вывода значение наследовать; убедитесь, что вы не используете профиль бота с verboseDefault: "on" в конфигурации.Документация: Рассуждения и подробный вывод, Безопасность.
Отправьте любое из следующих значений отдельным сообщением (без косой черты), чтобы инициировать прерывание: stop, stop action, stop current action, stop run, stop current run, stop agent, stop the agent, stop openclaw, openclaw stop, stop don't do anything, stop do not do anything, stop doing anything, do not do that, please stop, stop please, abort, esc, exit, interrupt, halt. Также работают распространённые команды прерывания на других языках (французском, немецком, испанском, китайском, японском, хинди, арабском и русском).Для фоновых процессов, запущенных инструментом exec, попросите агента выполнить:
Большинство команд с косой чертой необходимо отправлять отдельным сообщением, начинающимся с /, но некоторые сокращённые команды (например, /status) также можно использовать внутри сообщения отправителям из списка разрешённых. См. Команды с косой чертой.
По умолчанию OpenClaw блокирует обмен сообщениями между провайдерами. Если вызов инструмента привязан к Telegram, он не сможет отправить сообщение в Discord, пока вы явно не разрешите это. Изменение вступает в силу немедленно, перезапуск Gateway не требуется:
По умолчанию запросы, поступающие во время выполнения, направляются в активный запуск. Используйте /queue, чтобы выбрать поведение активного запуска:
  • steer (по умолчанию) — направить активный запуск на следующей границе модели.
  • followup — поставить сообщения в очередь и выполнять их по одному после завершения текущего запуска.
  • collect — поставить совместимые сообщения в очередь и ответить один раз после завершения текущего запуска.
  • interrupt — прервать текущий запуск и начать заново.
Для режимов очереди можно добавить параметры, например debounce:0.5s cap:25 drop:summarize. См. Очередь команд и Очередь управления.

​
Прочее

Учётные данные и выбор модели не связаны между собой. Задание ANTHROPIC_API_KEY (или сохранение ключа API Anthropic в профилях аутентификации) включает аутентификацию, но фактической моделью по умолчанию будет та, которую вы укажете в agents.defaults.model.primary (например, anthropic/claude-sonnet-4-6 или anthropic/claude-opus-4-6). No credentials found for profile "anthropic:default" означает, что Gateway не удалось найти учётные данные Anthropic в ожидаемом auth-profiles.json для запущенного агента.
Всё ещё не получается? Спросите в Discord или откройте обсуждение на GitHub.

​
Связанные материалы