ACP

Запустите мост Agent Client Protocol (ACP), который взаимодействует с OpenClaw Gateway.

openclaw acp использует ACP через stdio для IDE и пересылает запросы в Gateway через WebSocket, сопоставляя сеансы ACP с ключами сеансов Gateway. Это мост ACP на базе Gateway, а не полноценная среда редактора с нативной поддержкой ACP: он предназначен для маршрутизации сеансов, доставки запросов и потоковой передачи обновлений.

Если вы хотите, чтобы внешний клиент MCP взаимодействовал напрямую с диалогами каналов OpenClaw, а не размещал сеанс среды ACP, используйте openclaw mcp serve.

Чем это не является

openclaw acp означает, что OpenClaw выступает в роли сервера ACP: IDE или клиент ACP подключается к OpenClaw, а OpenClaw перенаправляет работу в сеанс Gateway.

Это отличается от агентов ACP, где OpenClaw запускает внешнюю среду, например Codex или Claude Code, через acpx.

Краткое правило:

• редактор или клиент должен взаимодействовать с OpenClaw по ACP: используйте openclaw acp
• OpenClaw должен запускать Codex, Claude или Gemini как среду ACP: используйте /acp spawn и агентов ACP

Матрица совместимости

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

• loadSession воспроизводит полную историю журнала событий ACP только для сеансов, созданных мостом. Для старых сеансов или сеансов без журнала используется резервная расшифровка, которая не восстанавливает исторические вызовы инструментов и системные уведомления.
• Если несколько клиентов ACP используют один ключ сеанса Gateway, маршрутизация событий и отмен выполняется по возможности, а не строго изолированно для каждого клиента. Если нужны чистые локальные для редактора циклы взаимодействия, предпочитайте изолированные по умолчанию сеансы acp-bridge:<uuid>.
• Состояния остановки Gateway преобразуются в причины остановки ACP, но это сопоставление менее выразительно, чем в полностью нативной среде ACP.
• Средства управления сеансом предоставляют ограниченный набор параметров Gateway: уровень размышлений, подробность вывода инструментов, рассуждения, детализацию использования и действия с повышенными привилегиями. Выбор модели и управление узлом выполнения не предоставляются как параметры конфигурации ACP.
• session_info_update и usage_update формируются на основе снимков сеансов Gateway, а не данных учёта нативной среды ACP в реальном времени. Данные об использовании приблизительны, не содержат сведений о стоимости и выдаются только тогда, когда Gateway помечает общие данные о токенах как актуальные.
• Сопутствующие данные инструментов предоставляются по возможности: мост показывает пути к файлам, обнаруженные в известных аргументах или результатах инструментов, но не выдаёт терминалы ACP или структурированные различия файлов.
• Передача подтверждений выполнения ограничена активным циклом запроса ACP; подтверждения из других сеансов Gateway игнорируются.

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

openclaw acp # Удалённый Gatewayopenclaw acp --url wss://gateway-host:18789 --token <token> # Удалённый Gateway (токен из файла)openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Подключение к существующему ключу сеансаopenclaw acp --session agent:main:main # Подключение по метке (она уже должна существовать)openclaw acp --session-label "support inbox" # Сброс ключа сеанса перед первым запросомopenclaw acp --session agent:main:main --reset-session

Клиент ACP (отладка)

Используйте встроенный клиент ACP для базовой проверки моста без IDE. Он запускает мост ACP и позволяет вводить запросы в интерактивном режиме.

openclaw acp client # Направление запущенного моста на удалённый Gatewayopenclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Переопределение команды сервера (по умолчанию: openclaw)openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

Модель разрешений (режим отладки клиента):

• Автоматическое подтверждение основано на списке разрешённых значений и применяется только к доверенным идентификаторам основных инструментов.
• Автоматическое подтверждение read ограничено текущим рабочим каталогом (--cwd, если он задан).
• ACP автоматически подтверждает только узкие классы операций, доступных только для чтения: ограниченные вызовы read в активном текущем рабочем каталоге, а также инструменты поиска только для чтения (search, web_search, memory_search). Неизвестные и неосновные инструменты, чтение за пределами разрешённой области, инструменты с возможностью выполнения, инструменты плоскости управления, изменяющие инструменты и интерактивные процессы всегда требуют явного подтверждения запроса.
• Предоставленное сервером значение toolCall.kind считается недоверенными метаданными, а не источником авторизации.
• Эта политика моста ACP не связана с разрешениями среды ACPX. Если вы запускаете OpenClaw через бэкенд acpx, параметр plugins.entries.acpx.config.permissionMode=approve-all служит аварийным переключателем «yolo» для этого сеанса среды.

Дымовое тестирование протокола

Для отладки на уровне протокола запустите Gateway с изолированным состоянием и управляйте openclaw acp через stdio с помощью клиента ACP JSON-RPC. Проверьте initialize, session/new, session/list с абсолютным cwd, session/resume, session/close, повторным закрытием и отсутствующим возобновлением.

Доказательство должно включать объявленные возможности жизненного цикла, строку сеанса на базе Gateway, уведомления об обновлениях и журнал Gateway sessions.list:

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

Не используйте openclaw gateway call sessions.list как единственное доказательство работы ACP. Этот путь CLI может запросить повышение области оператора для нового токена; корректность моста ACP подтверждается кадрами ACP через stdio и журналом Gateway sessions.list.

Как это использовать

Используйте ACP, когда IDE или другой клиент поддерживает Agent Client Protocol и должен управлять сеансом OpenClaw Gateway.

1. Убедитесь, что Gateway запущен локально или удалённо.
2. Настройте целевой Gateway с помощью конфигурации или флагов.
3. Настройте IDE для запуска openclaw acp через stdio.

Пример постоянной конфигурации:

openclaw config set gateway.remote.url wss://gateway-host:18789openclaw config set gateway.remote.token <token>

Пример прямого запуска без записи конфигурации:

openclaw acp --url wss://gateway-host:18789 --token <token># предпочтительный вариант для безопасности локального процессаopenclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Выбор агентов

ACP не выбирает агентов напрямую. Маршрутизация выполняется по ключу сессии Gateway. Чтобы обратиться к конкретному агенту, используйте ключи сессий с областью действия агента:

openclaw acp --session agent:main:mainopenclaw acp --session agent:design:mainopenclaw acp --session agent:qa:bug-123

Каждая сессия ACP сопоставляется с одним ключом сессии Gateway. У одного агента может быть много сессий; по умолчанию ACP использует изолированную сессию acp-bridge:<uuid>, если вы не переопределите ключ или метку.

Параметры mcpServers для отдельных сессий не поддерживаются в режиме моста. Если клиент ACP отправляет их во время newSession или loadSession, мост возвращает понятную ошибку, а не молча игнорирует их.

Чтобы в сеансах на базе ACPX были доступны инструменты плагинов OpenClaw или выбранные встроенные инструменты, например cron, включите мосты ACPX MCP на стороне Gateway вместо попытки передать параметры mcpServers для отдельных сессий. См. Агенты ACP и мост MCP для инструментов OpenClaw.

Использование из acpx (Codex, Claude и других клиентов ACP)

Чтобы агент разработки, например Codex или Claude Code, взаимодействовал с вашим ботом OpenClaw по ACP, используйте acpx со встроенной целью openclaw.

Типичный порядок действий:

1. Запустите Gateway и убедитесь, что мост ACP может к нему подключиться.
2. Направьте acpx openclaw на openclaw acp.
3. Укажите ключ сессии OpenClaw, который должен использовать агент разработки.

Примеры:

# Одноразовый запрос в вашу сессию ACP OpenClaw по умолчаниюacpx openclaw exec "Суммируй состояние активной сессии OpenClaw." # Постоянная именованная сессия для последующих запросовacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "Запроси у моего рабочего агента OpenClaw недавний контекст, относящийся к этому репозиторию."

Чтобы acpx openclaw всегда обращался к определённому Gateway и ключу сессии, переопределите команду агента openclaw в ~/.acpx/config.json:

{  "agents": {    "openclaw": {      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"    }  }}

Для локальной копии репозитория OpenClaw используйте прямую точку входа CLI вместо средства запуска для разработки, чтобы поток ACP оставался чистым:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

Это самый простой способ позволить Codex, Claude Code или другому клиенту с поддержкой ACP получать контекстную информацию от агента OpenClaw без извлечения данных из терминала.

Настройка редактора Zed

Добавьте пользовательского агента ACP в ~/.config/zed/settings.json (или используйте интерфейс настроек Zed):

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": ["acp"],      "env": {}    }  }}

Чтобы указать определённый Gateway или агента:

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": [        "acp",        "--url",        "wss://gateway-host:18789",        "--token",        "<token>",        "--session",        "agent:design:main"      ],      "env": {}    }  }}

В Zed откройте панель Agent и выберите "OpenClaw ACP", чтобы начать ветку обсуждения.

Сопоставление сессий

По умолчанию сессии моста ACP получают изолированный ключ сессии Gateway с префиксом acp-bridge:. Эти синтетические одноразовые сессии моста обычной модели подлежат удалению при очистке устаревших записей и не считаются защищёнными каналами общения с пользователями. Чтобы повторно использовать известную сессию, передайте ключ или метку сессии:

• --session <key>: использовать определённый ключ сессии Gateway.
• --session-label <label>: найти существующую сессию по метке.
• --reset-session: создать новый идентификатор сессии для этого ключа (тот же ключ, новая расшифровка).

Если ваш клиент ACP поддерживает метаданные, параметры можно переопределить для каждой сессии:

{  "_meta": {    "sessionKey": "agent:main:main",    "sessionLabel": "support inbox",    "resetSession": true  }}

Подробнее о ключах сессий см. в разделе /concepts/session.

Параметры

• --url <url>: URL WebSocket для Gateway (если настроено, по умолчанию используется gateway.remote.url).
• --token <token>: токен аутентификации Gateway.
• --token-file <path>: прочитать токен аутентификации Gateway из файла.
• --password <password>: пароль аутентификации Gateway.
• --password-file <path>: прочитать пароль аутентификации Gateway из файла.
• --session <key>: ключ сессии по умолчанию.
• --session-label <label>: метка сессии по умолчанию для поиска.
• --require-existing: завершить работу с ошибкой, если ключ или метка сессии не существуют.
• --reset-session: сбросить ключ сессии перед первым использованием.
• --no-prefix-cwd: не добавлять рабочий каталог в начало запросов.
• --provenance <off|meta|meta+receipt>: включать метаданные происхождения ACP или подтверждения.
• --verbose, -v: подробное журналирование в stderr.

Примечание по безопасности:

• --token и --password в некоторых системах могут быть видны в локальных списках процессов. Предпочтительнее использовать --token-file/--password-file или переменные среды (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• Определение данных аутентификации Gateway следует общему контракту, используемому другими клиентами Gateway:
  • локальный режим: переменная среды (OPENCLAW_GATEWAY_*), затем gateway.auth.*; переход к gateway.remote.* выполняется только тогда, когда gateway.auth.* не задан (если локальный SecretRef настроен, но не разрешается, операция завершается с ошибкой без небезопасного молчаливого перехода)
  • удалённый режим: gateway.remote.* с резервным использованием переменных среды или конфигурации согласно правилам приоритета для удалённого режима
  • --url безопасен при переопределении и не использует неявные учётные данные из конфигурации или переменных среды; передайте явные --token/--password (либо варианты с файлами)

Параметры acp client

• --cwd <dir>: рабочий каталог сессии ACP.
• --server <command>: команда сервера ACP (по умолчанию: openclaw).
• --server-args <args...>: дополнительные аргументы, передаваемые серверу ACP.
• --server-verbose: включить подробное журналирование на сервере ACP.
• --verbose, -v: подробное журналирование клиента.
• openclaw acp client задаёт OPENCLAW_SHELL=acp-client для порождённого процесса моста, что можно использовать для зависящих от контекста правил оболочки или профиля.

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

• Справочник CLI
• Агенты ACP