> ## Documentation Index > Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt > Use this file to discover all available pages before exploring further. # ACP 代理 — 设置 关于概览、操作手册和概念，请参见 [ACP 代理](/tools/acp-agents)。 本页涵盖 acpx harness 配置、用于 MCP 桥接的插件设置，以及权限配置。 只有在设置 ACP/acpx 路径时才使用本页。对于原生 Codex app-server 运行时配置，请使用 [Codex harness](/plugins/codex-harness)。对于 OpenAI API 密钥或 Codex OAuth 模型提供方配置，请使用 [OpenAI](/providers/openai)。 Codex 有两条 OpenClaw 路径： | Route | Config/command | Setup page | | ------------------- | ------------------------------------------------------ | --------------------------------------- | | 原生 Codex app-server | `/codex ...`, `openai/gpt-*` 代理引用 | [Codex harness](/plugins/codex-harness) | | 显式 Codex ACP 适配器 | `/acp spawn codex`, `runtime: "acp", agentId: "codex"` | 本页 | 除非你明确需要 ACP/acpx 行为，否则优先使用原生路径。 ## acpx 运行时支持（当前） 内置的 acpx harness 别名（来自固定版本的 `acpx` 依赖）： | Alias | Wraps | | ------------ | ------------------------------------------------------------------------------------------------------ | | `claude` | [Claude Code](https://claude.ai/code) | | `codex` | [Codex CLI](https://developers.openai.com/codex/cli) | | `copilot` | [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli) | | `cursor` | [Cursor CLI](https://cursor.com/docs/cli/acp) (`cursor-agent acp`) | | `droid` | [Factory Droid](https://www.factory.ai) | | `fast-agent` | [fast-agent](https://fast-agent.ai) | | `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | | `iflow` | [iFlow CLI](https://github.com/iflow-ai/iflow-cli) | | `kilocode` | [Kilocode](https://kilocode.ai) | | `kimi` | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | | `kiro` | [Kiro CLI](https://kiro.dev) | | `mux` | [Mux](https://mux.coder.com) | | `opencode` | [OpenCode](https://opencode.ai) | | `openclaw` | OpenClaw ACP 桥接（原生 `openclaw acp`） | | `pi` | [Pi Coding Agent](https://github.com/earendil-works/pi) | | `qoder` | [Qoder CLI](https://docs.qoder.com/cli/acp) | | `qwen` | [Qwen Code](https://github.com/QwenLM/qwen-code) | | `trae` | [Trae CLI](https://docs.trae.cn/cli) | `factory-droid` 和 `factorydroid` 也会解析为内置的 `droid` 适配器。 当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义代理别名，否则会优先将这些值用于 `agentId`。 如果你的本地 Cursor 安装仍然将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 代理命令，而不是更改内置默认值。 直接使用 acpx CLI 时，也可以通过 `--agent ` 目标任意适配器，但这个原始逃生口是 acpx CLI 的特性（不是正常的 OpenClaw `agentId` 路径）。 模型控制取决于适配器能力。Codex ACP 模型引用会在启动前由 OpenClaw 规范化。其他运行时需要 ACP `models` 以及 `session/set_model` 支持；如果某个运行时既不暴露该 ACP 能力， 也不提供自身的启动模型标志，OpenClaw/acpx 就无法强制选择模型。 ## 必需配置 ACP 核心基线： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { acp: { enabled: true, // 可选。默认值为 true；设为 false 可在保留 /acp 控制的同时暂停 ACP 派发。 dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", allowedAgents: [ "claude", "codex", "copilot", "cursor", "droid", "gemini", "iflow", "kilocode", "kimi", "kiro", "openclaw", "opencode", "qwen", ], stream: { deliveryMode: "live", }, }, } ``` 线程绑定配置在所有受支持的通道适配器之间共享： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { session: { threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, spawnSessions: true, }, }, } ``` 如果线程绑定的 ACP spawn 不起作用，请先验证适配器功能开关： * Discord: `session.threadBindings.spawnSessions=true` 当前对话绑定不需要创建子线程。它们需要一个活动的对话上下文，以及一个暴露 ACP 对话绑定的通道适配器。 参见 [配置参考](/gateway/configuration-reference)。 ## acpx 后端的插件设置 打包安装会为 ACP 使用官方的 `@openclaw/acpx` 运行时插件。 在使用 ACP harness 会话之前，请先安装并启用它： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/acpx openclaw config set plugins.entries.acpx.enabled true ``` 源代码检出也可以在 `pnpm install` 后使用本地工作区插件。 先运行： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /acp doctor ``` 如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想 切换回打包插件，请使用显式包路径： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/acpx openclaw config set plugins.entries.acpx.enabled true ``` 开发期间的本地工作区安装： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./path/to/local/acpx-plugin ``` 然后验证后端健康状态： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /acp doctor ``` ### acpx 运行时启动探测 `acpx` 插件直接嵌入 ACP 运行时（无需单独配置 `acpx` 二进制文件或 版本）。默认情况下，它会在 Gateway 启动期间注册嵌入式后端，并在网关 `ready` 信号之前等待启动探测。仅当脚本或环境有意保持启动探测禁用时， 才设置 `OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0` 或 `OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1`。运行 `/acp doctor` 可执行显式的 按需探测。 当路径或标志值应保持为一个 argv token 时，可使用结构化参数覆盖单个 ACP 代理命令： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "plugins": { "entries": { "acpx": { "enabled": true, "config": { "agents": { "claude": { "command": "node", "args": ["/path/to/custom adapter.mjs", "--verbose"] } } } } } } } ``` * `agents..command` 是该 ACP 代理的可执行文件或现有命令字符串。 * `agents..args` 为可选项。OpenClaw 通过当前 acpx 命令字符串注册表传递之前，会先对数组中的每一项进行 shell 引号转义。 参见 [插件](/tools/plugin)。 ### 自动下载适配器 `acpx` 会在首次使用时通过 `npx` 自动下载 ACP 适配器（例如 Claude 和 Codex ACP 桥接）。你无需手动安装适配器包，OpenClaw 本身也没有单独的 postinstall 步骤。如果适配器下载或启动失败，`/acp doctor` 会报告该失败。 ### Plugin tools MCP 桥接 默认情况下，ACPX 会话**不会**将 OpenClaw 插件注册的工具暴露给 ACP 运行时。 如果你希望 Codex 或 Claude Code 之类的 ACP 代理调用已安装的 OpenClaw 插件工具，例如 memory recall/store，请启用专用桥接： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true ``` 这会做什么： * 将一个内置的、名为 `openclaw-plugin-tools` 的 MCP 服务器注入到 ACPX 会话 启动流程中。 * 暴露由已安装且已启用的 OpenClaw 插件注册的插件工具。 * 将当前激活的 ACP 会话身份传递给插件工具工厂，从而让 代理作用域的工具保留在该代理的命名空间中。 * 保持该功能显式开启且默认关闭。 安全与信任说明： * 这会扩展 ACP 运行时工具面。 * ACP 代理只能访问网关中已激活的插件工具。 * 应将其视为与允许这些插件在 OpenClaw 本身中执行具有相同的信任边界。 * 在启用前请审查已安装的插件。 自定义 `mcpServers` 仍然像以前一样工作。内置的 plugin-tools 桥接是一项额外的可选便利功能，而不是通用 MCP 服务器配置的替代品。 ### OpenClaw tools MCP 桥接 默认情况下，ACPX 会话同样**不会**通过 MCP 暴露内置 OpenClaw 工具。只有当 ACP 代理需要某些选定的内置工具（如 `cron`）时，才启用单独的 core-tools 桥接： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true ``` 这会做什么： * 将一个名为 `openclaw-tools` 的内置 MCP 服务器注入 ACPX 会话 启动流程。 * 暴露选定的内置 OpenClaw 工具。初始服务器暴露 `cron`。 * 保持核心工具暴露显式启用且默认关闭。 ### 运行时操作超时配置 默认情况下，`acpx` 插件会为内嵌运行时启动和控制操作提供 120 秒。这为 Gemini CLI 之类较慢的 harness 留出足够时间完成 ACP 启动和初始化。如果你的主机需要不同的操作限制，请覆盖它： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 ``` 运行时将使用 OpenClaw 的 agent/run 超时设置，包括 `/acp timeout`。 `sessions_spawn` 不接受按调用覆盖的超时；操作员路径为 `agents.defaults.subagents.runTimeoutSeconds`。更改 `timeoutSeconds` 后请重启网关。 ### 健康探测代理配置 当 `/acp doctor` 或启动探测检查后端时，随附的 `acpx` 插件会探测一个 harness 代理。如果设置了 `acp.allowedAgents`，则默认使用 第一个允许的代理；否则默认使用 `codex`。如果你的部署需要用于健康检查的不同 ACP 代理，请显式设置探测代理： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set plugins.entries.acpx.config.probeAgent claude ``` 更改该值后重启网关。 ## 权限配置 ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供两个配置键来控制权限处理方式： 这些 ACPX 运行时权限与 OpenClaw exec 审批以及 CLI 后端厂商绕过标志（例如 Claude CLI `--permission-mode bypassPermissions`）是分开的。ACPX `approve-all` 是 ACP 会话的运行时紧急开关。 有关 OpenClaw `tools.exec.mode`、Codex Guardian 审批以及 ACPX harness 权限之间更广泛的比较，请参见 [权限模式](/tools/permission-modes)。 ### `permissionMode` 控制运行时代理在不提示的情况下可执行哪些操作。 | Value | Behavior | | --------------- | --------------------- | | `approve-all` | 自动批准所有文件写入和 shell 命令。 | | `approve-reads` | 仅自动批准读取；写入和执行需要提示。 | | `deny-all` | 拒绝所有权限提示。 | ### `nonInteractivePermissions` 控制当本应显示权限提示但没有交互式 TTY 可用时会发生什么（ACP 会话始终如此）。 | Value | Behavior | | ------ | -------------------------------------------------- | | `fail` | 以 `PermissionPromptUnavailableError` 中止会话。**（默认）** | | `deny` | 静默拒绝该权限并继续（优雅降级）。 | ### 配置 通过插件配置设置： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail ``` 更改这些值后重启网关。 OpenClaw 默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行操作都可能失败，并报错 `PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode`。 如果你需要限制权限，请将 `nonInteractivePermissions` 设为 `deny`，这样会话会优雅降级而不是崩溃。 ## 相关内容 * [ACP 代理](/tools/acp-agents) — 概览、运维手册、概念 * [子代理](/tools/subagents) * [多代理路由](/concepts/multi-agent)