古法编程

Appearance

配置 ACP 智能体网关时，需要先完成 acpx harness 基础配置，再安装并启用 @openclaw/acpx 插件。通过 acp 配置块控制默认智能体、允许列表和并发会话数；通过插件配置的 permissionMode 与 nonInteractivePermissions 控管文件写入和命令执行权限。若需让 ACP 智能体调用已有插件工具或内置工具（如 cron），可分别开启 pluginToolsMcpBridge 和 openClawToolsMcpBridge。运行 /acp doctor 可验证后端健康。

OpenClaw ACP 智能体配置与接入设置 ​

概述、运营手册与概念请参考 ACP 智能体。

以下内容涵盖 acpx harness 配置、面向 MCP 桥接的插件设置以及权限配置。仅当你在设置 ACP/acpx 路线时使用本页。
原生 Codex app-server 运行时配置请走 Codex 适配层。OpenAI API 密钥或 Codex OAuth 模型提供商配置请走 OpenAI 提供商。

Codex 有两条 OpenClaw 路线：

路线配置/命令设置页面
原生 Codex app-server/codex ...、openai/gpt-* 智能体引用Codex 适配层
显式 Codex ACP 适配器/acp spawn codex、runtime: "acp", agentId: "codex"本页

除非明确需要 ACP/acpx 行为，否则优先走原生路线。

当前内置 acpx 适配层别名 ​

当前 acpx 内置的适配层别名如下：

  • claude
  • codex
  • copilot
  • cursor（Cursor CLI：cursor-agent acp）
  • droid
  • gemini
  • iflow
  • kilocode
  • kimi
  • kiro
  • openclaw
  • opencode
  • pi
  • qwen

当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则推荐使用这些值作为 agentId。
如果本地 Cursor 安装仍将 ACP 暴露为 agent acp，请在 acpx 配置中覆盖 cursor 智能体命令，而不是更改内置默认值。

直接使用 acpx CLI 也可以通过 --agent <command> 指定任意适配器，但该逃生口是 acpx CLI 的功能（不是正常的 OpenClaw agentId 路径）。

模型控制取决于适配器能力。Codex ACP 模型引用在启动前由 OpenClaw 归一化。其他适配层需要 ACP models 配合 session/set_model 支持；如果某个适配层既没有暴露该 ACP 能力，也没有自己的启动模型标志，则 OpenClaw/acpx 无法强制选择模型。

必需配置 ​

核心 ACP 基线：

json5
{
  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",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

线程绑定配置因渠道适配器而异。以 Discord 为例：

json5
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}

如果线程绑定的 ACP spawn 不可用，请首先检查适配器功能标志：

  • Discord：channels.discord.threadBindings.spawnSessions=true

当前会话绑定不需要创建子线程。它需要活动会话上下文以及一个支持 ACP 会话绑定的渠道适配器。

参见 配置参考。

面向 acpx 后端的插件设置 ​

打包安装使用官方 @openclaw/acpx 运行时插件。在使用 ACP 适配层会话前，先安装并启用它：

bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

源码检出环境下，在 pnpm install 后也可以使用本地工作区插件。

启动后运行：

text
/acp doctor

如果你禁用了 acpx、通过 plugins.allow/plugins.deny 阻止了它，或者想切回打包插件，请使用显式包路径：

bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

开发过程中本地工作区安装：

bash
openclaw plugins install ./path/to/local/acpx-plugin

然后验证后端健康：

text
/acp doctor

acpx 命令与版本配置 ​

默认情况下，acpx 插件在网关启动时注册嵌入式 ACP 后端，并在网关发出 ready 信号前等待嵌入式运行时启动探测。只有脚本或有意让启动探测保持禁用的环境才需要设置 OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 或 OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1。运行 /acp doctor 进行显式按需探测。

在插件配置中覆盖命令或版本：

json
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
  • command 接受绝对路径、相对路径（从 OpenClaw 工作区解析）或命令名称。
  • expectedVersion: "any" 禁用严格版本匹配。
  • 自定义 command 路径会禁用插件本地自动安装。

使用结构化参数覆盖单个 ACP 智能体命令，以确保路径或标志值作为一个 argv 令牌：

json
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "claude": {
              "command": "node",
              "args": ["/path/to/custom adapter.mjs", "--verbose"]
            }
          }
        }
      }
    }
  }
}
  • agents.<id>.command 是该 ACP 智能体的可执行文件或现有命令字符串。
  • agents.<id>.args 可选。数组中的每个元素在 OpenClaw 传入当前 acpx 命令字符串注册表前都会经过 shell 引用。

参见 插件。

自动依赖安装 ​

当你通过 npm install -g openclaw 全局安装 OpenClaw 时，acpx 运行时依赖（平台特定二进制文件）会通过 postinstall 钩子自动安装。如果自动安装失败，网关仍能正常启动，并通过 openclaw acp doctor 报告缺失的依赖。

插件工具 MCP 桥接 ​

默认情况下，ACPX 会话不会将 OpenClaw 插件注册的工具暴露给 ACP 适配层。

如果你希望 ACP 智能体（如 Codex 或 Claude Code）调用已安装的 OpenClaw 插件工具（如 memory recall/store），请启用专用桥接：

bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

作用：

  • 在 ACPX 会话启动时注入一个名为 openclaw-plugin-tools 的内置 MCP 服务器。
  • 暴露已安装并启用的 OpenClaw 插件已注册的工具。
  • 该功能默认关闭，需显式启用。

安全与信任说明：

  • 这会扩展 ACP 适配层的工具表面。
  • ACP 智能体只能访问网关中已激活的插件工具。
  • 应将其视为与允许这些插件在 OpenClaw 中执行相同的信任边界。
  • 启用前请检查已安装的插件。

自定义 mcpServers 仍然正常使用。内置插件工具桥接是一个额外的选择性便捷功能，不是通用 MCP 服务器配置的替代品。

OpenClaw 工具 MCP 桥接 ​

默认情况下，ACPX 会话也不会通过 MCP 暴露内置的 OpenClaw 工具。如果需要 ACP 智能体使用选定的内置工具（如 cron），请单独启用核心工具桥接：

bash
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

作用：

  • 在 ACPX 会话启动时注入一个名为 openclaw-tools 的内置 MCP 服务器。
  • 暴露选定的 OpenClaw 内置工具。初始服务器暴露 cron。
  • 核心工具暴露默认关闭，需显式启用。

运行时操作超时配置 ​

acpx 插件为嵌入式运行时启动和控制操作默认提供 120 秒超时。这为较慢的适配层（如 Gemini CLI）提供足够的 ACP 启动和初始化时间。如果主机需要不同的操作限制，可以覆盖它：

bash
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

运行时循环使用 OpenClaw 智能体/运行超时，包括 /acp timeout 和 sessions_spawn.timeoutSeconds。更改此值后需要重启网关。

健康探测智能体配置 ​

当 /acp doctor 或启动探测检查后端时，捆绑的 acpx 插件会探测一个适配层智能体。如果设置了 acp.allowedAgents，则默认为列表中的第一个智能体；否则默认为 codex。如果你的部署需要不同的 ACP 智能体进行健康检查，请显式设置探测智能体：

bash
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 会话在适配层级的紧急开关。

permissionMode ​

控制适配层智能体可以在无需提示的情况下执行哪些操作。

值行为
approve-all自动批准所有文件写入和 shell 命令。
approve-reads仅自动批准读操作；写入和执行需要提示。
deny-all拒绝所有权限提示。

nonInteractivePermissions ​

控制当权限提示本应显示但没有交互式 TTY 时（ACP 会话始终如此）发生什么。

值行为
fail以 AcpRuntimeError 中止会话。（默认）
deny静默拒绝权限并继续运行（优雅降级）。

配置 ​

通过插件配置设置：

bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

更改这些值后需要重启网关。

WARNING

OpenClaw 默认 permissionMode=approve-reads 且 nonInteractivePermissions=fail。在非交互式 ACP 会话中，任何触发权限提示的写入或执行都可能失败并报 AcpRuntimeError: Permission prompt unavailable in non-interactive mode。

如果需要限制权限，应将 nonInteractivePermissions 设为 deny，使会话优雅降级而不是崩溃。

常见问题 ​

如何快速启用 ACP 路由？ ​

保证 acp.enabled: true 和 acp.backend: "acpx" 已配置，安装并启用 @openclaw/acpx 插件，然后运行 /acp doctor 验证健康。

遇到 AcpRuntimeError: Permission prompt unavailable 怎么解决？ ​

默认情况下 nonInteractivePermissions 设为 fail，导致写/执行权限提示时 ACP 会话崩掉。将 nonInteractivePermissions 改为 deny 可让会话静默拒绝并继续；也可将 permissionMode 设为 approve-all 自动批准所有操作（注意安全风险）。

如何让 ACP 智能体调用插件工具或内置 cron 工具？ ​

分别启用 pluginToolsMcpBridge 和 openClawToolsMcpBridge。前者暴露已注册的插件工具，后者暴露内置工具（目前包括 cron）。两个选项默认关闭，需显式配置后重启网关。

相关链接 ​

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策