ACP 智能体 — 设置

有关概述、操作员运行手册和概念，请参阅 ACP 智能体。

本页介绍 acpx harness 配置、MCP 桥接的插件设置以及权限配置。

仅在设置 ACP/acpx 路由时使用本页。对于原生 Codex app-server 运行时配置，请参阅 Codex harness。对于 OpenAI API 密钥或 Codex OAuth 模型提供商配置，请参阅 OpenAI。

Codex 有两条 OpenClaw 路由：

除非你明确需要 ACP/acpx 行为，否则优先使用原生路由。

acpx harness 支持（当前）¶

内置的 acpx harness 别名（来自固定的 acpx 依赖）：

factory-droid 和 factorydroid 也会解析为内置的 droid 适配器。

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

直接使用 acpx CLI 也可以通过 --agent <command> 定向到任意适配器，但这个原始逃生通道是 acpx CLI 的特性（不是常规的 OpenClaw agentId 路径）。

模型控制取决于适配器的能力。Codex ACP 模型引用由 OpenClaw 在启动前规范化。其他 harness 需要一个通过 session/set_config_option 声明的模型配置选项，或通过 session/set_model 使用的旧版 ACP models。如果没有受支持的 ACP 模型控制或适配器特定的启动模型标志，OpenClaw/acpx 就无法强制选择模型。

原生聊天中的 GitHub Copilot CLI¶

GitHub Copilot CLI 可以通过已安装智能体的模型选择器为普通 OpenClaw 聊天提供服务，包括 Web 聊天和频道。该路由使用本地的 copilot --acp --stdio 进程，而不是 OpenClaw API 提供商的凭据。

安装支持 ACP 的 CLI，并在运行 Gateway 的同一操作系统帐户下登录。Copilot CLI 1.0.86 支持通过 ACP 进行模型发现和选择：

npm install -g @github/copilot
copilot --version
copilot login

刷新模型目录，然后选择 acp-copilot/<model-id> 条目。OpenClaw 只使用该 CLI 声明的模型；它不提供静态模型列表。仅仅检测到安装并不能证明身份验证或模型访问权限。要阻止新的原生 Copilot 轮次和目录发现，请将 plugins.entries.acpx.config.nativeAgents.copilot 设置为 false。经典的 /acp spawn copilot 会话与 acp.allowedAgents 是相互独立的。

Copilot 负责身份验证和计费：

• 原生 GitHub 身份验证使用 CLI 的 OAuth 登录或其支持的 GitHub token 路由，包括已认证的 gh 回退。环境变量 token（COPILOT_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN）可以覆盖已存储的登录。
• Copilot 模型使用会消耗账户套餐额度。不要仅因为目录条目可用就假设某个模型免费；请检查账户包含的使用量和额外使用预算。
• 显式 CLI BYOK 配置（COPILOT_PROVIDER_*、COPILOT_PROVIDERS_CONFIG 或 CLI 的 providers.json）即使 GitHub 登录可用，也可能将模型请求路由到单独计费的提供商。请有意配置该路由。OpenClaw 不会选择它，也不会将 OpenClaw API 凭据复制到原生 harness。

有关账户和套餐要求，请参阅 GitHub 的 CLI 身份验证指南 和 Copilot 计费指南。 下文中的原生聊天权限和沙箱边界仍然适用。

已安装的原生代理保留其自己的登录状态。在发现过程中，/models 可以报告 检查原生代理，而不需要 OpenClaw API 密钥。如果可用性未确认，请检查 Gateway 主机上的原生应用并再次运行 /models。

原生聊天运行时权限¶

当原生运行时无法执行该聊天的可选 OpenClaw 工具、沙箱或工作区限制时，Control UI 会向管理员提供 为此聊天继续。选择运行时或使用现有选择发送消息时，也适用相同的确认。

确认后会选择 完全访问，关闭该聊天的可选沙箱，并针对确切的原生运行时记录同意。随后，原生代理将在 Gateway 主机上使用其自身权限。OpenClaw 不声称在该代理内部执行其可选工具限制。其他聊天和全局设置保持不变，由 OpenClaw 托管的工具保留其现有策略。

拒绝会保持权限不变，并让消息保持未发送状态。首次发送可以创建一个空聊天，以便确认绑定到该聊天，但在你确认之前，不会保存或运行任何消息。确认会保存权限，并重试该消息一次，包括聊天的第一条消息，而不会固定其默认模型。仅选择确认不会发送草稿。同意不会被另一个聊天继承，并在会话重置或所选运行时更改时清除。不识别同意的旧版主机保留其先前的限制检查。

必需沙箱、必需工作区边界以及不兼容的远程执行放置不能通过此确认豁免。受限用户必须向管理员请求或选择兼容的运行时。

必需配置¶

核心 ACP 基线：

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "qwen",
    ],
    stream: {
      deliveryMode: "live",
    },
  },
}

线程绑定配置在受支持的频道适配器之间共享：

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

如果线程绑定的 ACP 生成不工作，请先验证适配器功能标志：

• Discord: session.threadBindings.spawnSessions=true

当前会话绑定不需要创建子线程。它们需要一个活动的会话上下文和一个公开 ACP 会话绑定的频道适配器。

请参阅 配置参考。

修复现有裸会话历史¶

ACPX 按 OpenClaw 所有者隔离裸会话名称。如果会话报告 SESSION_OWNER_MIGRATION_REQUIRED，请停止 Gateway 并运行 openclaw doctor --fix，然后重启。Doctor 使用与 Gateway 相同的服务工作区；ACPX 的默认状态目录是 <service workspace>/state。

修复需要一个当前、无歧义的规范所有者声明，并且后端标识符匹配。它会保留原始历史、事件日志引用、上游会话 ID、时间戳、选项和使用量。持久记录名称会移动到所有者限定的资源；现有的一次性物理 ID 和历史记录保持完整。模糊、过期、冲突、不可读或活动记录会保留在原位置并附带诊断信息。在重试之前，请解决所报告的证据问题；重置会话不会绕过此修复。

这是一个离线、可崩溃恢复的迁移，具有原子目标文件发布。文件和 SQLite 不是一个原子事务。中断的修复可以重新运行：Doctor 在完成元数据更新并归档旧持久记录之前，会检查现有目标和规范声明。

acpx 后端插件设置¶

打包安装使用用于 ACP 的官方 @openclaw/acpx 运行时插件。在使用 ACP harness 会话之前，请安装并启用它：

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

源代码检出也可以在 pnpm install 之后使用本地工作区插件。

从以下开始：

/acp doctor

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

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

开发期间的本地工作区安装：

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

然后验证后端健康状态：

/acp doctor

acpx 运行时启动探测¶

acpx 插件直接嵌入 ACP 运行时（没有单独的 acpx 二进制文件或需要配置的版本）。默认情况下，它会在 Gateway 启动期间注册嵌入式后端，并在 Gateway ready 信号之前等待一次健康探测。该探测还提供失败诊断，并受 plugins.entries.acpx.config.timeoutSeconds 限制；不健康结果不会触发第二次探测。仅当脚本或环境有意保持启动探测禁用时，才设置 OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 或 OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1。运行 /acp doctor 以进行显式的按需探测。

当路径或标志值应保持为单个 argv 参数时，使用结构化参数覆盖单个 ACP agent 命令：

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "claude": {
              "command": "node",
              "args": ["/path/to/custom adapter.mjs", "--verbose"]
            }
          }
        }
      }
    }
  }
}

• agents.<id>.command 是该 ACP agent 的可执行文件或现有命令字符串。已存在的绝对可执行文件路径即使包含空格，也保持为单个参数。
• agents.<id>.args 是可选的。每个项都会原样传递，包括空字符串、空格、引号和反斜杠。不要在数组内添加 shell 引号。

在 Windows 上，将可执行文件路径放在 command 中，将其标志放在 args 中。 使用命令字符串时，请为包含空格的相对可执行文件路径添加引号。 生成的适配器包装器也使用 argv 数组。重新连接未更改的会话会保留其已保存的命令表示和对话历史。

参见 插件。

自动适配器下载¶

acpx 会在首次使用时通过 npx 自动下载 ACP 适配器（例如 Claude 和 Codex ACP 桥接）。你无需手动安装适配器包，OpenClaw 本身也没有单独的 postinstall 步骤。如果适配器下载或 spawn 失败，/acp doctor 会报告该失败。

插件工具 MCP 桥接¶

默认情况下，ACPX 会话不会向 ACP harness 暴露 OpenClaw 插件注册的工具。

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

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

它的作用：

• 向 ACPX 会话引导注入一个名为 openclaw-plugin-tools 的内置 MCP 服务器。
• 暴露已由已安装并启用的 OpenClaw 插件注册的插件工具。
• 将当前 ACP 会话身份传递给插件工具工厂，使 agent 作用域的工具保留在该 agent 的命名空间中。
• 保持该功能显式且默认关闭。

安全与信任注意事项：

• 这会扩大 ACP harness 的工具面。
• ACP agent 只能访问 Gateway 中已激活的插件工具。
• 将其视为与让这些插件在 OpenClaw 本身中执行相同的信任边界。
• 启用前请审查已安装的插件。

自定义 mcpServers 仍按之前方式工作。内置 plugin-tools 桥接是额外的可选便利功能，不是通用 MCP 服务器配置的替代。

OpenClaw 工具 MCP 桥接¶

默认情况下，ACPX 会话也不会通过 MCP 暴露内置 OpenClaw 工具。当 ACP agent 需要选定的内置工具（例如 cron）时，启用独立的 core-tools 桥接：

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

它的作用：

• 向 ACPX 会话引导注入一个名为 openclaw-tools 的内置 MCP 服务器。
• 暴露选定的内置 OpenClaw 工具。初始服务器暴露 cron。
• 保持核心工具暴露显式且默认关闭。

运行时操作超时配置¶

acpx 插件默认给嵌入式运行时启动和控制操作 120 秒。这为 Gemini CLI 等较慢的 harness 提供了足够时间完成 ACP 启动和初始化。如果你的主机需要不同的操作限制，请覆盖它：

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

运行时回合使用 OpenClaw agent/run 超时，包括 /acp timeout。 交互式回合可以持续到超过插件操作限制，直到其回合预算耗尽、harness 完成或你取消它。 sessions_spawn 不接受按调用超时覆盖；操作员路径为 agents.defaults.subagents.runTimeoutSeconds。在默认混合重载模式下，更改 timeoutSeconds 会自动重新加载插件。参见 配置热重载。

健康探测 agent 配置¶

当 /acp doctor 或启动探测检查后端时，内置的 acpx 插件会探测一个 harness agent。如果设置了 acp.allowedAgents，则默认使用第一个允许的 agent；否则默认使用 codex。如果你的部署需要不同的 ACP agent 用于健康检查，请显式设置探测 agent：

openclaw config set plugins.entries.acpx.config.probeAgent claude

在默认混合重载模式下，此更改会自动重新加载插件。 运行 /acp doctor 以检查更新后的后端。

权限配置¶

ACP 会话在没有交互式 TTY 的情况下运行，以处理文件写入和 shell 执行权限提示。这不会禁用通过频道传递的回合期间的 ACP 表单或 URL 征询：这些请求会改用临时 Gateway 问题。 acpx 插件提供两个控制 harness 权限的配置键：permissionMode 和 nonInteractivePermissions，两者均在下面说明。

这些 ACPX harness 权限独立于 OpenClaw exec 审批，也独立于 CLI 后端供应商绕过标志（例如 Claude CLI --permission-mode bypassPermissions）。ACPX approve-all 是 ACP 会话的 harness 级紧急开关。

若要更广泛地比较 OpenClaw tools.exec.mode、Codex Guardian 审批和 ACPX harness 权限，请参见 权限模式。

permissionMode¶

控制 harness 代理可以在不提示的情况下执行哪些操作。

nonInteractivePermissions¶

控制当需要显示权限提示但没有可用的交互式 TTY 时发生什么（对于 ACP 会话，这种情况总是如此）。

配置¶

通过插件配置设置：

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

在默认的混合重载模式下，这些更改会自动重新加载插件。 有关其他重载模式，请参阅 配置热重载。

相关¶

• ACP 代理 — 概述、操作员运行手册、概念
• 子代理
• 多代理路由
• ACPx 插件参考 — acpx 运行时插件的清单和配置，包括 Pi 会话目录