ACP 智能体绑定

绑定会话¶

心智模型¶

聊天界面 - 人们持续交谈的地方（Discord 频道、Telegram 主题、iMessage 聊天）。
ACP 会话 - OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。
子线程/主题 - 仅通过 --thread ... 创建的可选附加消息界面。
运行时工作区 - 运行框架执行所在的文件系统位置（cwd、仓库检出、后端工作区）。与聊天界面无关。

当前会话绑定¶

/acp spawn <harness> --bind here 将当前会话固定到生成的 ACP 会话 - 不创建子线程，使用相同的聊天界面。OpenClaw 继续负责传输、认证、安全和消息投递。该会话中的后续消息都会路由到同一会话；/new 和 /reset 会就地重置会话；/acp close 会移除绑定。

示例：

/codex bind                                              # native Codex bind, route future messages here
/codex model gpt-5.4                                     # tune the bound native Codex thread
/codex stop                                              # control the active native Codex turn
/acp spawn codex --bind here                             # explicit ACP fallback for Codex
/acp spawn codex --thread auto                           # may create a child thread/topic and bind there
/acp spawn codex --bind here --cwd /workspace/repo       # same chat binding, Codex runs in /workspace/repo

绑定规则与互斥性

--bind here 和 --thread ... 互斥。
--bind here 仅在声明支持当前会话绑定的频道上有效；否则 OpenClaw 会返回明确的“不支持”提示信息。绑定在网关重启后仍然保留。
在 Discord 上，spawnSessions 会控制 --thread auto|here 的子线程创建，但不控制 --bind here。
如果你在没有 --cwd 的情况下生成到另一个 ACP 智能体，OpenClaw 默认继承目标智能体的工作区。若继承的路径缺失（ENOENT/ENOTDIR），则回退到后端默认路径；其他访问错误（如 EACCES）会以生成错误的形式呈现。
网关管理命令在绑定会话中保持本地处理 - 即使普通后续文本路由到绑定的 ACP 会话，/acp ... 命令也由 OpenClaw 处理；只要该界面启用了命令处理，/status 和 /session 也会保持本地处理。

线程绑定会话

当频道适配器启用了线程绑定时：

OpenClaw 将线程绑定到目标 ACP 会话。
该线程中的后续消息会路由到所绑定的 ACP 会话。
ACP 的输出会投递回同一线程。
/session unbind、关闭、归档、空闲超时或最大时长过期都会移除绑定。/session unbind 仅解除当前会话的绑定，并让 ACP 会话继续运行。
/acp close、/acp cancel、/acp status、/status 和 /session 是网关命令，而不是发送给 ACP 运行框架的提示词。

线程绑定 ACP 所需的功能开关：

acp.enabled=true
acp.dispatch.enabled 默认开启（设置为 false 可暂停自动的 ACP 线程分发；显式调用 sessions_spawn({ runtime: "acp" }) 仍然有效）。
频道适配器线程会话生成已启用（默认：true）：
Discord/Telegram：session.threadBindings.spawnSessions=true

线程绑定支持因适配器而异。如果当前频道适配器不支持线程绑定，OpenClaw 会返回明确的不支持/不可用提示信息。

支持线程的频道

任何暴露会话/线程绑定能力的频道适配器。
当前内置支持：Discord 线程/频道、Telegram 主题（群组/超级群组中的论坛主题以及私聊主题）。
插件频道可以通过相同的绑定接口添加支持。

持久化频道绑定¶

对于非临时性工作流，请在顶层 bindings[] 条目中配置持久化的 ACP 绑定。

绑定模型¶

bindings[].type "acp" (path)

标记持久化的 ACP 会话绑定。

bindings[].match object (path)

标识目标会话。各频道的匹配形态：

Discord 频道/线程： match.channel="discord" + match.peer.id="<channelOrThreadId>"
Slack 频道/私聊： match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>"。建议使用稳定的 Slack ID；频道绑定也会匹配该频道线程内的回复。
Telegram 论坛主题： match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
WhatsApp 私聊/群组： match.channel="whatsapp" + match.peer.id="<E.164|group JID>"。对于直接聊天使用 E.164 号码，例如 +15555550123；对于群组使用 WhatsApp 群组 JID，例如 120363424282127706@g.us。
iMessage 私聊/群组： match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"。建议使用 chat_id:* 以获得稳定的群组绑定。

bindings[].agentId string (path)

所属 OpenClaw 智能体的 ID。

bindings[].acp.mode "persistent" | "oneshot" (path)

可选的 ACP 覆盖。

bindings[].acp.label string (path)

可选的操作者可见标签。

bindings[].acp.cwd string (path)

可选的运行时工作目录。

bindings[].acp.backend string (path)

可选的后端覆盖。

每智能体的运行时默认值¶

使用 agents.entries.*.runtime 为每个智能体一次性定义 ACP 默认值：

agents.entries.*.runtime.type="acp"
agents.entries.*.runtime.acp.agent（运行框架 ID，例如 codex 或 claude）
agents.entries.*.runtime.acp.backend
agents.entries.*.runtime.acp.mode
agents.entries.*.runtime.acp.cwd

ACP 绑定会话的覆盖优先级：

bindings[].acp.*
agents.entries.*.runtime.acp.*
全局 ACP 默认值（例如 acp.backend）

配置的绑定还会传递所属智能体的显式模型和思考策略。对于 runtime.type: "acp" 的智能体，agents.entries.*.model.primary 会选择 ACP 运行框架的模型，即使其值看起来也像原生的 provider/model 引用。OpenClaw 侧的调用（如 /btw 和内部工具）使用 agents.defaults.model 作为其原生默认值。显式的原生会话覆盖以及专门的工具或子智能体模型设置仍然适用。所选择的原生提供方需要自己的凭据；ACP 运行框架的登录不会为 OpenClaw 的原生调用提供身份验证。

对于现有配置，即使 ACP 主项是有效的原生引用，这也可能会更改原生提供商。openclaw doctor 会描述每个 ACP 代理的框架模型和解析后的原生默认值，而不会重写配置。请在 agents.defaults.model 中选择原生默认值；原生会话、实用工具和子代理覆盖仍可用于其各自的操作。

对于支持模型回退的原生调用，省略的代理 model.fallbacks 会继承 agents.defaults.model.fallbacks。显式的原生回退列表会替换该列表，而 fallbacks: [] 会禁用它。这些条目必须是原生 OpenClaw 模型引用，而不是仅框架使用的 ID。/btw 使用其选定的原生模型，而不使用模型回退链。

Thinking 使用代理的 thinkingDefault，然后是每模型 agents.defaults.models["provider/model"].params.thinking，然后是 agents.defaults.thinkingDefault。如果没有配置策略，外部框架会保留其自身默认值。

更改已配置的模型或 thinking 值会在其下一轮之前更新现有会话，而不会替换对话。每个选项只有在框架接受后才会保存；被拒绝的选项会返回错误，并保留该选项之前的选择。模型和 thinking 更改是独立的，不是原子批处理。移除默认值会使用任何剩余的已配置策略；如果没有剩余策略，OpenClaw 会保留会话的最后选择。省略不是后端重置。若要显式更改 thinking，请使用 /acp set thinking <level>，并指定框架支持的级别。对于 Codex ACP，off 仅省略新会话的启动覆盖。将现有会话切换到 off 不受支持，会返回错误，而不会清除其当前推理强度或对话。

示例¶

{
  agents: {
    ownership: "explicit",
    entries: {
      codex: {
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      claude: {
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    },
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

行为¶

OpenClaw 会在通道特定准入之后、使用之前确保已配置的 ACP 会话存在。
该通道、主题或聊天中的消息会路由到已配置的 ACP 会话。
已配置的 ACP 绑定拥有其会话路由。通道广播扇出不会替换匹配绑定所对应的已配置 ACP 会话。
在已绑定会话中，/new 和 /reset 会就地重置相同的 ACP 会话键。
由线程绑定生成创建的运行时绑定在存在时仍然适用。
对于没有显式 cwd 的跨代理 ACP 生成，OpenClaw 会从代理配置继承目标代理工作区。
缺失的继承工作区路径会回退到后端默认 cwd；非缺失路径的访问失败会表现为生成错误。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw