openclaw gateway ....
Обнаружение Bonjour
Настройка локального mDNS и глобального DNS-SD.
Обзор обнаружения
Как OpenClaw объявляет шлюзы и находит их.
Конфигурация
Ключи конфигурации Gateway верхнего уровня.
Запуск Gateway
Поведение при запуске
Поведение при запуске
- Не запускается, если
gateway.mode=localне задан в~/.openclaw/openclaw.json. Для разовых запусков и разработки используйте--allow-unconfigured; этот параметр обходит проверку, не записывая и не исправляя конфигурацию. openclaw onboard --mode localиopenclaw setupзаписываютgateway.mode=local. Если файл конфигурации существует, ноgateway.modeотсутствует, конфигурация считается повреждённой или перезаписанной, и Gateway не пытается самостоятельно определитьlocal— повторно выполните первоначальную настройку, задайте ключ вручную или передайте--allow-unconfigured.- Привязка не только к loopback-интерфейсу без аутентификации блокируется.
- Значения
--bindlan,tailnetиcustomсейчас разрешаются только через IPv4; при самостоятельной настройке хоста только с IPv6 перед Gateway требуется дополнительный компонент или прокси с IPv4. SIGUSR1при наличии разрешения запускает перезапуск внутри процесса.commands.restart(по умолчанию включён) управляет отправленным извнеSIGUSR1; задайте значениеfalse, чтобы блокировать ручные перезапуски с помощью сигналов ОС, сохранив возможность перезапуска через командуgateway restart, инструмент Gateway, а также применение или обновление конфигурации.SIGINT/SIGTERMостанавливают процесс, но не восстанавливают пользовательское состояние терминала. Если CLI обёрнут в TUI или используется ввод в необработанном режиме, восстановите терминал самостоятельно перед завершением работы.
Параметры
number
Порт WebSocket (по умолчанию берётся из конфигурации или переменной среды; обычно
18789).string
Режим привязки:
loopback (по умолчанию), lan, tailnet, auto, custom.string
Общий токен для
connect.params.auth.token. По умолчанию используется OPENCLAW_GATEWAY_TOKEN, если он задан.string
Режим аутентификации:
none, token, password, trusted-proxy.string
Пароль для
--auth password.string
Читать пароль Gateway из файла.
string
Предоставление доступа через Tailscale:
off, serve, funnel.boolean
Сбросить конфигурацию Tailscale serve/funnel при завершении работы.
boolean
Запустить без обязательной проверки
gateway.mode=local. Только для разовой начальной настройки и разработки; конфигурация не сохраняется и не исправляется.boolean
Создать конфигурацию и рабочую область для разработки, если они отсутствуют (без
BOOTSTRAP.md).boolean
Сбросить конфигурацию для разработки, учётные данные, сеансы и рабочую область. Требуется
--dev.boolean
Перед запуском завершить любой существующий процесс, прослушивающий целевой порт.
boolean
Подробное журналирование в stdout/stderr.
boolean
Показывать в консоли только журналы серверной части CLI (также включает stdout/stderr).
string
по умолчанию:"auto"
Стиль журнала WebSocket:
auto, full, compact.boolean
Псевдоним для
--ws-log compact.boolean
Записывать необработанные события потока модели в JSONL.
string
Путь к JSONL необработанного потока.
--claude-cli-logs — устаревший псевдоним для --cli-backend-logs.
Для --bind custom задайте в gateway.customBindHost адрес IPv4. Любой адрес, кроме 127.0.0.1 или 0.0.0.0, также требует 127.0.0.1 на том же порту для клиентов на этом же хосте; запуск завершается ошибкой, если хотя бы один из слушателей не может выполнить привязку. Подстановочный адрес 0.0.0.0 не добавляет отдельный обязательный псевдоним. При самостоятельной настройке хоста только с IPv6 перед Gateway требуется дополнительный компонент или прокси с IPv4.
Перезапуск Gateway
--safe запрашивает у работающего Gateway предварительную проверку активных задач и планирует один объединённый перезапуск после их завершения. Ожидание ограничено параметром gateway.reload.deferralTimeoutMs (по умолчанию 5 минут / 300000); после исчерпания лимита перезапуск выполняется принудительно. Задайте deferralTimeoutMs: 0, чтобы вместо принудительного перезапуска ждать неограниченно долго, периодически выводя предупреждения о незавершённых задачах. --safe нельзя использовать вместе с --force или --wait.
--skip-deferral обходит проверку отложенного перезапуска из-за активных задач при безопасном перезапуске, поэтому Gateway перезапускается немедленно даже при наличии заявленных блокирующих факторов. Для него требуется --safe — используйте этот параметр, если откладывание зависло из-за неконтролируемой задачи.
--wait <duration> переопределяет лимит ожидания завершения задач для обычного, небезопасного перезапуска. Принимает значение в миллисекундах без суффикса или с суффиксами единиц ms, s, m, h, d (например, 30s, 5m, 1h30m); --wait 0 задаёт неограниченное ожидание. Несовместим с --force и --safe.
--force пропускает ожидание завершения активных задач и выполняет немедленный перезапуск. Обычная команда restart без флагов сохраняет существующее поведение перезапуска через диспетчер служб.
Профилирование Gateway
OPENCLAW_GATEWAY_STARTUP_TRACE=1записывает длительность этапов запуска, включая задержкуeventLoopMaxдля каждого этапа и длительность построения таблиц поиска плагинов (индекс установленных компонентов, реестр манифестов, планирование запуска, построение карты владельцев).OPENCLAW_GATEWAY_RESTART_TRACE=1записывает относящиеся к перезапуску строкиrestart trace:: обработку сигналов, ожидание завершения активных задач, этапы остановки, следующий запуск, время готовности и показатели памяти.OPENCLAW_DIAGNOSTICS=timelineвместе сOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>записывает в режиме максимальных усилий хронологию диагностики запуска в формате JSONL для внешних стендов контроля качества (эквивалент конфигурацииdiagnostics.flags: ["timeline"]; путь по-прежнему задаётся только через переменную среды). ДобавьтеOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1, чтобы включить выборки цикла событий.pnpm build, а затемpnpm test:startup:gateway -- --runs 5 --warmup 1измеряют производительность запуска Gateway через собранную точку входа CLI: первый вывод процесса,/healthz,/readyz, длительность этапов трассировки запуска, задержку цикла событий и время построения таблиц поиска плагинов.pnpm build, а затемpnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5измеряют производительность внутрипроцессного перезапуска в macOS или Linux (в Windows не поддерживается; для перезапуска требуетсяSIGUSR1). ИспользуетсяSIGUSR1; в дочернем процессе включаются обе трассировки и записываются следующие/healthz, следующие/readyz, время недоступности, время готовности, CPU, RSS и показатели трассировки перезапуска./healthzпроверяет работоспособность процесса;/readyzпроверяет готовность к использованию. Рассматривайте строки трассировки и результаты измерений как сигнал для определения ответственного компонента, а не как полный вывод о производительности на основе одного интервала или замера.
Запрос к работающему Gateway
Все команды запросов используют RPC через WebSocket.- Режимы вывода
- Общие параметры
- По умолчанию: удобочитаемый вывод (с цветами в TTY).
--json: машиночитаемый JSON (без оформления и индикатора выполнения).--no-color(илиNO_COLOR=1): отключить ANSI, сохранив удобочитаемую компоновку.
Если задан
--url, CLI не использует резервные учётные данные из конфигурации или переменных среды. Передайте --token или --password явно. Отсутствие явно заданных учётных данных является ошибкой.gateway health
/healthz — проверка работоспособности процесса: она завершается, как только сервер способен ответить по HTTP. /readyz строже и продолжает сообщать о неготовности, пока запускаемые вспомогательные процессы плагинов, каналы или настроенные хуки ещё переходят в рабочее состояние. Подробные локальные или аутентифицированные ответы /readyz содержат диагностический блок eventLoop (задержка, загрузка, отношение к числу ядер CPU, флаг degraded).
number
Обращаться к локальному Gateway на loopback-интерфейсе через этот порт. Для данного вызова переопределяет
OPENCLAW_GATEWAY_URL и OPENCLAW_GATEWAY_PORT.gateway usage-cost
Получить сводки расходов на использование из журналов сеансов.
number
по умолчанию:"30"
Количество учитываемых дней.
string
Ограничить сводку одним идентификатором настроенного агента.
boolean
Объединить данные всех настроенных агентов. Нельзя использовать вместе с
--agent.gateway stability
Получить последние данные диагностического регистратора стабильности из работающего Gateway.
number
по умолчанию:"25"
Максимальное количество включаемых последних событий (не более
1000).string
Фильтровать по типу диагностического события, например
payload.large или diagnostic.memory.pressure.number
Включать только события после указанного номера диагностической последовательности.
string
Читать сохранённый пакет данных о стабильности вместо обращения к работающему Gateway.
--bundle latest (или отдельный --bundle) выбирает новейший пакет в каталоге состояния; также можно напрямую передать путь к JSON-файлу пакета.boolean
Записать ZIP-архив с диагностическими данными для передачи службе поддержки вместо вывода сведений о стабильности.
string
Путь вывода для
--export.Конфиденциальность и поведение пакета
Конфиденциальность и поведение пакета
- Записи сохраняют операционные метаданные: названия событий, количества, размеры в байтах, показатели памяти, состояние очереди и сеанса, идентификаторы одобрений, названия каналов и плагинов, а также отредактированные сводки сеансов. Они не содержат текст чата, тела Webhook, результаты инструментов, необработанные тела запросов и ответов, токены, файлы cookie, секретные значения, имена хостов и необработанные идентификаторы сеансов. Установите
diagnostics.enabled: false, чтобы полностью отключить средство записи. - При фатальном завершении Gateway, тайм-ауте остановки или сбое запуска после перезапуска тот же диагностический снимок записывается в
~/.openclaw/logs/stability/openclaw-stability-*.json, если средство записи содержит события. Просмотрите новейший пакет с помощьюopenclaw gateway stability --bundle latest;--limit,--typeи--since-seqтакже применяются к выводу пакета.
gateway diagnostics export
Создаёт локальный ZIP-архив диагностики, предназначенный для отчётов об ошибках. Модель конфиденциальности и содержимое пакета описаны в разделе Экспорт диагностики.
string
Путь к выходному ZIP-архиву. По умолчанию создаётся экспорт для службы поддержки в каталоге состояния.
number
по умолчанию:"5000"
Максимальное количество включаемых очищенных строк журнала.
number
по умолчанию:"1000000"
Максимальный объём журнала в байтах для проверки.
string
URL WebSocket Gateway для снимка работоспособности.
string
Токен Gateway для снимка работоспособности.
string
Пароль Gateway для снимка работоспособности.
number
по умолчанию:"3000"
Тайм-аут снимка состояния и работоспособности.
boolean
Пропустить поиск сохранённого пакета стабильности.
boolean
Вывести записанный путь, размер и манифест в формате JSON.
manifest.json (перечень файлов), summary.md (сводка Markdown), diagnostics.json (сводка верхнего уровня по конфигурации, журналам, обнаружению, стабильности, состоянию и работоспособности), config/sanitized.json, status/gateway-status.json, health/gateway-health.json, logs/openclaw-sanitized.jsonl и stability/latest.json, если пакет существует.
Экспорт предназначен для передачи другим лицам. Он сохраняет операционные сведения, полезные для отладки: безопасные поля журналов, названия подсистем, коды состояния, длительности, настроенные режимы, порты, идентификаторы плагинов и провайдеров, несекретные параметры функций и отредактированные операционные сообщения журналов. При этом он исключает или редактирует текст чата, тела Webhook, результаты инструментов, учётные данные, файлы cookie, идентификаторы учётных записей и сообщений, текст запросов и инструкций, имена хостов и секретные значения. Если сообщение журнала похоже на текст полезной нагрузки пользователя, чата или инструмента (например, «пользователь сказал», «текст чата», «результат инструмента», «тело Webhook»), экспорт сохраняет только факт пропуска сообщения и количество его байтов.
gateway status
Показывает службу Gateway (launchd/systemd/schtasks), а также необязательную проверку подключения и аутентификации.
string
Добавить явную цель проверки. Настроенная удалённая цель и localhost по-прежнему проверяются.
string
Аутентификация по токену для проверки.
string
Аутентификация по паролю для проверки.
number
по умолчанию:"10000"
Тайм-аут проверки.
boolean
Пропустить проверку подключения (показать только службу).
boolean
Также сканировать службы системного уровня.
boolean
Расширить проверку подключения до проверки чтения и завершить работу с ненулевым кодом при её сбое. Нельзя использовать вместе с
--no-probe.Семантика состояния
Семантика состояния
- Остаётся доступной для диагностики, даже если локальная конфигурация CLI отсутствует или недействительна.
- Вывод по умолчанию подтверждает состояние службы, подключение WebSocket и возможность аутентификации, видимую во время рукопожатия, но не операции чтения, записи или администрирования.
- Проверки не вносят изменений при первой аутентификации устройства: они повторно используют существующий кэшированный токен устройства, если он есть, но никогда не создают новую идентичность устройства CLI или запись сопряжения только для чтения исключительно для проверки состояния.
- По возможности разрешает настроенные SecretRef аутентификации для проверки. Если обязательный SecretRef не разрешён,
--jsonсообщаетrpc.authWarningпри сбое подключения или аутентификации проверки; явно передайте--token/--passwordлибо исправьте источник секрета. После успешного завершения проверки предупреждения о неразрешённой аутентификации подавляются. - Вывод JSON содержит
gateway.version, если его сообщает работающий Gateway;--require-rpcможет использовать данные RPCstatus.runtimeVersion, если проверка рукопожатия не может предоставить метаданные версии. - Используйте
--require-rpcв скриптах и автоматизации, когда работающей прослушивающей службы недостаточно и также требуется работоспособность RPC с областью чтения. --deepсканирует дополнительные установки launchd/systemd/schtasks; если найдено несколько служб, похожих на Gateway, человекочитаемый вывод показывает рекомендации по очистке (обычно следует запускать один Gateway на каждом компьютере) и, когда применимо, сообщает о недавней передаче перезапуска диспетчером.--deepтакже выполняет проверку конфигурации с учётом плагинов (pluginValidation: "full") и показывает предупреждения манифеста плагина (например, об отсутствии метаданных конфигурации канала). Значениеgateway statusпо умолчанию сохраняет быстрый путь только для чтения, пропускающий проверку плагинов.- Человекочитаемый вывод содержит разрешённый путь к файлу журнала, а также пути и сведения о действительности конфигурации CLI и службы, чтобы упростить диагностику расхождений профиля или каталога состояния.
Проверки расхождения аутентификации Linux systemd
Проверки расхождения аутентификации Linux systemd
- Проверки расхождения аутентификации службы считывают из юнита как
Environment=, так иEnvironmentFile=(включая%h, пути в кавычках, несколько файлов и необязательные файлы-). - Разрешает SecretRef
gateway.auth.tokenс помощью объединённого окружения среды выполнения (сначала окружение команды службы, затем резервное окружение процесса). - Проверки расхождения токенов пропускают разрешение токена конфигурации, если аутентификация по токену фактически не активна (
gateway.auth.modeявно имеет значениеpassword/none/trusted-proxyлибо режим не задан, пароль может иметь приоритет и ни один кандидат на токен не может получить приоритет).
gateway probe
Команда «отладить всё». Она всегда проверяет:
- настроенный удалённый Gateway (если задан) и
- localhost (интерфейс обратной связи), даже если настроен удалённый Gateway.
--url добавляет эту явную цель перед обеими остальными. В человекочитаемом выводе цели обозначаются как URL (explicit), Remote (configured) / Remote (configured, inactive) и Local loopback.
Если доступно несколько целей проверки, выводятся все. SSH-туннель, URL TLS/прокси и настроенный удалённый URL могут указывать на один и тот же Gateway даже при разных транспортных портах;
multiple_gateways предназначен для доступных шлюзов, которые различаются или чья идентичность неоднозначна. Запуск нескольких шлюзов поддерживается для изолированных профилей (например, резервного бота), но в большинстве установок работает один Gateway.number
Использовать этот порт для локальной цели проверки через интерфейс обратной связи и удалённого порта SSH-туннеля. Без
--url выбирается только локальная цель через интерфейс обратной связи вместо URL среды настроенного Gateway, порта окружения или удалённых целей.Интерпретация
Интерпретация
Reachable: yesозначает, что хотя бы одна цель приняла подключение WebSocket.Capability: read-only|write-capable|admin-capable|pairing-pending|connect-onlyсообщает, что проверке удалось подтвердить об аутентификации, отдельно от доступности.Read probe: okозначает, что подробные вызовы RPC с областью чтения (health/status/system-presence/config.get) также завершились успешно.Read probe: limited - missing scope: operator.readозначает, что подключение выполнено успешно, но RPC с областью чтения ограничен. Это отображается как ухудшенная доступность, а не полный сбой.Read probe: failedпослеConnect: okозначает, что WebSocket подключился, но последующая диагностика чтения завершилась по тайм-ауту или со сбоем — это также ухудшенное состояние, а не недоступность.- Как и
gateway status, проверка повторно использует существующие кэшированные данные аутентификации устройства, но не создаёт идентичность устройства или состояние сопряжения при первом использовании. - Код завершения ненулевой только в том случае, если ни одна проверенная цель недоступна.
Вывод JSON
Вывод JSON
Верхний уровень:
ok: хотя бы одна цель доступна.degraded: хотя бы одна цель приняла подключение, но не завершила полную подробную диагностику RPC.capability: лучшая возможность среди доступных целей (read_only,write_capable,admin_capable,pairing_pending,connected_no_operator_scopeилиunknown).primaryTargetId: лучшая цель, которую следует считать активной, в следующем порядке: явный URL, SSH-туннель, настроенная удалённая цель, локальный интерфейс обратной связи.warnings[]: записи предупреждений по мере возможности сcode,messageи необязательнымtargetIds.network: подсказки URL для локального интерфейса обратной связи и tailnet, полученные из текущей конфигурации и сетевых параметров хоста.discovery.timeoutMs/discovery.count: фактический бюджет обнаружения и количество результатов, использованные в этом проходе проверки.
targets[].connect): ok (доступность и классификация ухудшенного состояния), rpcOk (успешность полного подробного RPC), scopeLimited (сбой подробного RPC из-за отсутствия области оператора).Для каждой цели (targets[].auth): role и scopes, указанные в hello-ok, если доступны, а также отображаемая классификация capability.Распространённые коды предупреждений
Распространённые коды предупреждений
ssh_tunnel_failed: не удалось настроить SSH-туннель; команда перешла к прямым проверкам.multiple_gateways: были доступны разные идентичности Gateway либо OpenClaw не смог подтвердить, что доступные цели являются одним и тем же Gateway. SSH-туннель, URL прокси или настроенный удалённый URL к одному и тому же Gateway не вызывают это предупреждение.auth_secretref_unresolved: настроенный SecretRef аутентификации не удалось разрешить для цели, проверка которой завершилась сбоем.probe_scope_limited: подключение WebSocket выполнено успешно, но проверка чтения была ограничена из-за отсутствияoperator.read.local_tls_runtime_unavailable: локальный TLS Gateway включён, но OpenClaw не удалось загрузить отпечаток локального сертификата.
Удалённое подключение по SSH (аналог режима приложения Mac)
Режим приложения macOS “Remote over SSH” использует локальное перенаправление порта, чтобы удалённый Gateway, доступный только через интерфейс обратной связи, стал доступен по адресуws://127.0.0.1:<port>.
Эквивалент для CLI:
string
user@host или user@host:port (порт по умолчанию — 22).string
Файл идентификации.
boolean
Выбрать первый обнаруженный хост Gateway в качестве цели SSH из разрешённой конечной точки обнаружения (
local. и настроенный глобальный домен, если он задан). Подсказки только из TXT игнорируются.gateway.remote.sshTarget, gateway.remote.sshIdentity.
gateway call <method>
Низкоуровневая вспомогательная функция RPC.
string
по умолчанию:"{}"
Строка с объектом JSON для параметров.
string
URL WebSocket для Gateway.
string
Токен Gateway.
string
Пароль Gateway.
number
по умолчанию:"10000"
Лимит времени ожидания.
boolean
В основном предназначено для RPC в стиле агентов, которые передают промежуточные события перед окончательными данными.
boolean
Машиночитаемый вывод JSON.
--params должен быть допустимым JSON, а каждый метод проверяет собственную структуру параметров (лишние поля и поля с неверными именами отклоняются).Управление службой Gateway
Установка с обёрткой
Используйте--wrapper, когда управляемая служба должна запускаться через другой исполняемый файл, например через промежуточный модуль диспетчера секретов или вспомогательную программу запуска от имени другого пользователя. Обёртка получает обычные аргументы Gateway и отвечает за последующий вызов через exec файла openclaw или Node с этими аргументами.
gateway install проверяет, что путь указывает на исполняемый файл, записывает обёртку в ProgramArguments службы и сохраняет OPENCLAW_WRAPPER в окружении службы для последующих принудительных переустановок, обновлений и исправлений с помощью doctor.
OPENCLAW_WRAPPER при переустановке:
Параметры команд
Параметры команд
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node>(по умолчанию:node),--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway stop:--disable,--json
Поведение жизненного цикла
Поведение жизненного цикла
- Используйте
gateway restartдля перезапуска управляемой службы. Не объединяйтеgateway stopиgateway startв цепочку вместо перезапуска. - В macOS команда
gateway stopпо умолчанию используетlaunchctl bootout, что удаляет LaunchAgent из текущего сеанса загрузки без сохранения состояния отключения: автоматическое восстановление KeepAlive остаётся активным при будущих сбоях, аgateway startповторно включает службу без ручного выполненияlaunchctl enable. Передайте--disable, чтобы надолго отключить KeepAlive и RunAtLoad и не допустить повторного запуска Gateway до следующего явного выполненияgateway start; используйте этот вариант, если остановка вручную должна сохраняться после перезагрузок. - Команды жизненного цикла принимают
--jsonдля использования в сценариях.
Аутентификация и SecretRef при установке
Аутентификация и SecretRef при установке
- Когда для аутентификации по токену требуется токен, а
gateway.auth.tokenуправляется через SecretRef,gateway installпроверяет возможность разрешения SecretRef, но не сохраняет разрешённый токен в метаданных окружения службы. - Если для аутентификации по токену требуется токен, а настроенный SecretRef токена не разрешается, установка завершается с отказом вместо сохранения резервного токена в виде обычного текста.
- Для аутентификации по паролю в
gateway runпредпочитайтеOPENCLAW_GATEWAY_PASSWORD,--password-fileилиgateway.auth.passwordна основе SecretRef, а не встроенное значение--password. - В режиме автоматического определения аутентификации доступный только в оболочке
OPENCLAW_GATEWAY_PASSWORDне отменяет требования к токену при установке; при установке управляемой службы используйте постоянную конфигурацию (gateway.auth.passwordили параметр конфигурацииenv). - Если настроены и
gateway.auth.token, иgateway.auth.password, аgateway.auth.modeне задан, установка блокируется до явного выбора режима.
Обнаружение шлюзов (Bonjour)
gateway discover выполняет поиск маяков Gateway (_openclaw-gw._tcp).
- Многоадресный DNS-SD:
local. - Одноадресный DNS-SD (глобальный Bonjour): выберите домен (например,
openclaw.internal.) и настройте раздельный DNS и DNS-сервер; см. раздел Bonjour.
role (подсказка о роли шлюза), transport (подсказка о транспорте, например gateway), gatewayPort (порт WebSocket, обычно 18789), tailnetDns (имя хоста MagicDNS, если доступно), gatewayTls / gatewayTlsSha256 (включение TLS и отпечаток сертификата). sshPort и cliPath публикуются только в режиме полного обнаружения (discovery.mdns.mode: "full"; по умолчанию используется "minimal", при котором они не публикуются — в этом случае клиенты по умолчанию используют порт 22 для целевых узлов SSH).
gateway discover
number
по умолчанию:"2000"
Время ожидания для каждой команды (обзор/разрешение).
boolean
Машиночитаемый вывод (также отключает оформление и индикатор выполнения).
- Сканирует
local., а также настроенный глобальный домен, если он включён. wsUrlв выводе JSON формируется из разрешённой конечной точки службы, а не только из подсказок TXT, таких какlanHostилиtailnetDns.discovery.mdns.modeуправляет публикациейsshPort/cliPathкак в mDNSlocal., так и в глобальном DNS-SD (см. выше).