OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

代理协调

ACP 代理绑定

绑定会话

心智模型

  • 聊天界面 - 人们持续对话的地方（Discord 频道、Telegram 主题、iMessage 聊天）。
  • ACP 会话 - 持久 Codex/Claude/Gemini 运行时状态 OpenClaw 路由到。
  • Child thread/topic - 仅由 --thread ... 创建的可选额外消息传递表面。
  • 运行时工作区 - harness 运行所在的文件系统位置（cwd、仓库检出目录、后端工作区）。与聊天界面相互独立。

当前对话绑定

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

示例：

text
/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）回退到后端默认值；其他访问错误 （e.g. EACCES） 表现为生成错误。
  • 网关管理命令在绑定会话中保留在本地 - 即使正常的后续文本路由到绑定的 ACP 会话，/acp ... 命令也由 OpenClaw 处理；每当为该表面启用命令处理时，/status 和 /session 也会保持本地状态。
线程绑定会话

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

  • OpenClaw 会将线程绑定到目标 ACP 会话。
  • 该线程中的后续消息会路由到已绑定的 ACP 会话。
  • ACP 输出会回送到同一个线程。
  • /session unbind、关闭、存档、空闲超时或 max-age 到期会删除绑定。 /session unbind 仅分离当前会话并让 ACP 会话保持运行。
  • /acp close、/acp cancel、/acp status、/status 和 /session 是网关命令，不是对 ACP harness的提示。

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

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

线程绑定支持是特定于适配器的。如果活动通道适配器不支持线程绑定，则 OpenClaw 返回明确的 unsupported/unavailable 消息。

线程支持通道
  • 公开 session/thread 绑定功能的任何通道适配器。
  • 当前内置支持：Discord threads/channels， Telegram主题（论坛主题groups/supergroups和DM主题）。
  • 插件频道可以通过同一绑定接口添加支持。

持久频道绑定

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

绑定模型

bindings[].type"acp"

标记一个持久 ACP 对话绑定。

bindings[].matchobject

标识目标对话。按频道的形状如下：

  • Discord channel/thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Slack channel/DM： match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>"。优先选择稳定的Slack ids；通道绑定还匹配该通道线程内的回复。
  • Telegram 论坛主题: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • WhatsApp DM/group： match.channel="whatsapp" + match.peer.id="<E.164|group JID>"。使用 E.164 号码（例如 +15555550123）进行直接聊天，使用 WhatsApp 群组 JID（例如 [email protected]）进行群组。
  • iMessage DM/group： match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"。优选 chat_id:* 以获得稳定的基团结合。
bindings[].agentIdstring

所属的 OpenClaw agent id。

bindings[].acp.mode"persistent" | "oneshot"

可选的 ACP 覆盖。

bindings[].acp.labelstring

面向操作者的可选标签。

bindings[].acp.cwdstring

可选的运行时工作目录。

bindings[].acp.backendstring

可选的后端覆盖。

每个 agent 的运行时默认值

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

  • agents.entries.*.runtime.type="acp"
  • agents.entries.*.runtime.acp.agent（harness ID、e.g. codex 或 claude）
  • agents.entries.*.runtime.acp.backend
  • agents.entries.*.runtime.acp.mode
  • agents.entries.*.runtime.acp.cwd

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

  1. bindings[].acp.*
  2. agents.entries.*.runtime.acp.*
  3. 全局 ACP 默认值 （e.g. acp.backend）

配置的绑定还转发所属代理的显式模型和思维策略。对于具有 runtime.type: "acp" 的代理，agents.entries.*.model.primary 选择 ACP harness模型，即使其值也看起来像本机 provider/model 参考。 OpenClaw-side 调用（例如 /btw 和内部实用程序）使用 agents.defaults.model 作为其本机默认值。显式本机会话覆盖和专用实用程序或子代理模型设置仍然适用。所选的本地提供商需要有自己的凭据； ACP harness登录不会验证 OpenClaw 的本机调用。

对于现有配置，即使 ACP 主要是有效的本机引用，这也可能会更改本机提供程序。 openclaw doctor 描述了每个 ACP 代理的harness模型并解析了本机默认值，而无需重写配置。 agents.defaults.model中选择本机默认值；本机会话、实用程序和子代理覆盖仍然可用于其各自的操作。

对于支持模型回退的本机调用，省略代理 model.fallbacks 继承 agents.defaults.model.fallbacks。显式本机后备列表会替换该列表，并且 fallbacks: [] 会禁用它。这些条目必须是本机 OpenClaw 模型引用，而不是仅限harness的 ID。 /btw 使用其选择的本机模型，没有模型后备链。

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

更改配置的模型或思考值会在下一轮之前更新现有会话，而不会替换对话。每个选项仅在harness接受后才会保存；被拒绝的选项会返回错误并保留该选项之前的选择。模型和思维的改变是独立的，不是原子批次的。删除默认值会使用任何剩余的配置策略；如果没有剩余，OpenClaw 保留会话的最后选择。省略不是后端重置。要明确改变思维，请使用 /acp set thinking <level> 以及harness支持的级别。对于 Codex ACP，off 仅省略新会话的启动覆盖。不支持将现有会话切换到 off，并且会返回错误而不清除其当前的推理工作或对话。

示例

json5
{  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 会话 key。
  • 由线程绑定生成创建的运行时绑定仍然适用于存在的情况。
  • 对于未显式指定 cwd 的跨 agent ACP spawn，OpenClaw 会从 agent 配置继承目标 agent 工作区。
  • 缺失的继承工作区路径会回退到后端默认 cwd；真实的访问失败会作为 spawn 错误暴露出来。
本页有帮助吗？