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

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

Область ACP	Статус	Примечания
`initialize`, `newSession`, `prompt`, `cancel`	Реализовано	Основной поток моста через stdio к операциям чата, отправки и прерывания Gateway.
`listSessions`, команды с косой чертой	Реализовано	Список сеансов работает с состоянием сеансов Gateway, используя ограниченную курсорную пагинацию и фильтрацию по `cwd`, когда строки сеансов Gateway содержат метаданные рабочего пространства; команды объявляются через `available_commands_update`.
Метаданные происхождения сеанса	Реализовано	Списки сеансов и снимки сведений о сеансах содержат сведения о родительских и дочерних связях OpenClaw в `_meta`, поэтому клиенты ACP могут отображать графы субагентов без закрытых побочных каналов Gateway.
`resumeSession`, `closeSession`	Реализовано	Возобновление повторно привязывает сеанс ACP к существующему сеансу Gateway без воспроизведения истории. Закрытие отменяет активную работу моста, завершает ожидающие запросы со статусом отмены и освобождает состояние сеанса моста.
`loadSession`	Частично	Повторно привязывает сеанс ACP к ключу сеанса Gateway и воспроизводит историю журнала событий ACP для сеансов, созданных мостом. Для старых сеансов или сеансов без журнала используются сохранённые тексты пользователя и ассистента.
Содержимое запроса (`text`, встроенные `resource`, изображения)	Частично	Текст и ресурсы преобразуются в ввод чата; изображения становятся вложениями Gateway.
Режимы сеанса	Частично	`session/set_mode` поддерживается; мост предоставляет средства управления сеансом на базе Gateway для уровня размышлений, подробности вывода инструментов, рассуждений, детализации использования и действий с повышенными привилегиями. Более широкие нативные поверхности режимов и конфигурации ACP пока не входят в область поддержки.
Потоковая передача размышлений	Реализовано	Содержимое размышлений модели передаётся потоком как обновления сеанса `agent_thought_chunk`. Нативные планы сеансов ACP не выдаются.
Обновления сведений о сеансе и использовании	Частично	Мост отправляет уведомления `session_info_update` и, по возможности, `usage_update` из кэшированных снимков сеансов Gateway. Данные об использовании приблизительны и отправляются только тогда, когда суммарные значения токенов Gateway помечены как актуальные.
Потоковая передача данных инструментов	Частично	События `tool_call`/`tool_call_update` содержат необработанные данные ввода-вывода, текстовое содержимое и, по возможности, расположение файлов, если оно присутствует в аргументах или результатах инструментов Gateway. Встроенные терминалы и более содержательный вывод в нативном формате различий не предоставляются.
Подтверждения выполнения	Частично	Запросы Gateway на подтверждение выполнения во время активных циклов запросов ACP передаются клиенту ACP через `session/request_permission`.
Серверы MCP для отдельных сеансов (`mcpServers`)	Не поддерживается	Режим моста отклоняет запросы серверов MCP для отдельных сеансов. Настройте MCP в OpenClaw Gateway или агенте.
Методы файловой системы клиента (`fs/read_text_file`, `fs/write_text_file`)	Не поддерживается	Мост не вызывает методы файловой системы клиента ACP.
Терминальные методы клиента (`terminal/*`)	Не поддерживается	Мост не создаёт терминалы клиента 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

# Удалённый Gateway
openclaw 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

# Направление запущенного моста на удалённый Gateway
openclaw 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.

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

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

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw 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:main
openclaw acp --session agent:design:main
openclaw 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. Типичный порядок действий:

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

Примеры:

# Одноразовый запрос в вашу сессию ACP OpenClaw по умолчанию
acpx openclaw exec "Суммируй состояние активной сессии OpenClaw."

# Постоянная именованная сессия для последующих запросов
acpx openclaw sessions ensure --name codex-bridge
acpx 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 commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

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

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

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

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

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

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

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

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

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

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

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

Параметры

Параметры `acp client`

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

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

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

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

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

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

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

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

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

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

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

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

​Параметры

​Параметры acp client

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

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

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

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

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

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

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

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

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

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

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

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

Параметры

Параметры `acp client`

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