ACP 代理控制
会话目标解析¶
大多数 /acp 操作接受可选的会话目标(session-key、session-id 或 session-label)。
解析顺序:
- 显式目标参数(或针对
/acp steer的--session) - 先尝试键
- 然后是 UUID 形式的会话 ID
- 再然后是标签
- 当前线程绑定(如果此对话/线程已绑定到某个 ACP 会话)。
- 当前请求者会话回退。
当前会话绑定和线程绑定都参与第 2 步。
如果没有解析到目标,OpenClaw 会返回明确的错误(Unable to resolve session target: ...)。
会话所有者与执行器(harness)¶
拥有会话的 OpenClaw 代理与 ACP 所选的外部执行器是分开的。例如,由 work 拥有的会话可以运行 claude 执行器。感知所有者的管理器调用会携带 agentId;agent 仍然是执行器名称。配置的绑定会独立地使用其 OpenClaw 代理所有者及其配置的 ACP 执行器。sessions_spawn 对原始执行器使用请求者作为所有者,对 ACP 别名使用配置的代理作为所有者。/acp spawn 保留其现有的执行器命名空间。
诸如 global 这样的裸键在所有权明确时要求显式所有者。ACP 会保持诸如 shared-project 这样的任意逻辑键不变;ACPX 则按所有者界定后端资源名称的作用域。代理限定的主别名即使解析到 global,也仍保留其所有者。冲突的所有者/键对会明确失败。无法隔离裸会话的后端必须先升级,然后这些会话才能运行。
ACP 控制命令¶
| 命令 | 功能 | 示例 |
|---|---|---|
/acp spawn |
创建 ACP 会话;可选绑定当前会话或线程。 | /acp spawn codex --bind here --cwd /repo |
/acp cancel |
取消目标会话正在进行的轮次。 | /acp cancel agent:codex:acp:<uuid> |
/acp steer |
将指令排队,在当前轮次结束后运行。 | /acp steer --session support inbox prioritize failing tests |
/acp close |
关闭会话并解除线程目标绑定。 | /acp close |
/acp status |
显示后端、模式、状态、运行时选项和功能。 | /acp status |
/acp set-mode |
设置目标会话的运行时模式。 | /acp set-mode plan |
/acp set |
通用运行时配置选项写入。 | /acp set model openai/gpt-5.4 |
/acp cwd |
设置运行时工作目录覆盖。 | /acp cwd /Users/user/Projects/repo |
/acp permissions |
设置审批策略配置。 | /acp permissions strict |
/acp timeout |
设置运行时超时时间(秒)。 | /acp timeout 120 |
/acp model |
设置运行时模型覆盖。 | /acp model anthropic/claude-opus-4-6 |
/acp reset-options |
移除会话运行时选项覆盖。 | /acp reset-options |
/acp sessions |
从存储中列出最近的 ACP 会话。 | /acp sessions |
/acp doctor |
后端健康状况、功能、可行的修复方案。 | /acp doctor |
/acp install |
打印确定性的安装和启用步骤。 | /acp install |
运行时控制命令(spawn、cancel、steer、close、status、set-mode、set、cwd、permissions、timeout、model 和 reset-options)要求外部渠道提供所有者身份,内部 Gateway 客户端则要求 operator.admin 权限。获得授权的非所有者发送者仍可使用 sessions、doctor、install 和 help。对于非所有者发送者,/acp sessions 仅列出当前绑定的会话或请求者会话;所有者身份和 operator.admin 客户端可看到所有近期会话。
/acp steer 将后续指令排队;它无法向正在运行的 ACP 轮次添加输入。该指令会等待当前轮次结束,然后在同一会话和上下文中运行。命令会在后续指令完成后才返回响应。若要重定向正在进行的工作,请先运行 /acp cancel,然后再发送新指令。
/acp status 显示生效的运行时选项以及运行时级别和后端级别的会话标识符。当后端缺少某项功能时,不支持的控件错误会明确显示出来。接受目标令牌(session-key、session-id 或 session-label)的命令会通过网关会话发现机制解析它们,包括自定义的每个代理 session.store 根目录。/acp sessions 不接受目标令牌。
运行时选项映射¶
/acp 提供便捷命令和通用设置器。等效操作:
| 命令 | 映射到 | 备注 |
|---|---|---|
/acp model <id> |
运行时配置键 model |
对于 Codex ACP,OpenClaw 会将 openai/<model> 规范化为适配器模型 ID,并将斜杠推理后缀(如 openai/gpt-5.4/high)映射到 reasoning_effort。 |
| 命令 | 映射到 | 备注 |
|---|---|---|
/acp set thinking <level> |
规范选项 thinking |
OpenClaw 会在存在后端通告的等效项时发送该等效项,优先使用 thinking,然后 effort、reasoning_effort 或 thought_level。对于 Codex ACP,适配器会将值映射到 reasoning_effort。 |
/acp permissions <profile> |
规范选项 permissionProfile |
OpenClaw 会在存在后端通告的等效项时发送该等效项,例如 approval_policy、permission_profile、permissions 或 permission_mode。 |
/acp timeout <seconds> |
规范选项 timeoutSeconds |
OpenClaw 会在存在后端通告的等效项时发送该等效项,例如 timeout 或 timeout_seconds。 |
/acp cwd <path> |
运行时 cwd 覆盖 | 在下一个运行时操作时应用,该操作会先关闭上一个句柄再替换它。 |
/acp set <key> <value> |
通用 | key=cwd 使用 cwd 覆盖路径。 |
/acp reset-options |
清除所有运行时覆盖 | 关闭保留的运行时,而不启动新的后端。 |
当后端返回其已接受的控件时,OpenClaw 会将已选择的思考级别与该响应保持同步。模型切换可能会降低级别或移除思考支持;后续轮次和重连会使用已接受的选择,而不是重放旧级别。后端默认值不会成为新的会话覆盖,并且模型引用会保留其 OpenClaw 提供商前缀。
在 Cursor 中,模型请求可以使用精确的通告 ID、具有一个通告变体的选择器,或指向其中任一者的 OpenClaw provider/model 引用。未知或模糊的请求会明显失败。包含 / 的精确通告 ID 优先于将其解释为带提供商限定的引用。
模型覆盖会在提示提交之前进行验证,包括重连之后。在新会话初始化期间被丢弃的不受支持的继承默认值不会被保存为覆盖。
当旧的工作目录或模型覆盖阻止后端启动时,/acp reset-options 在重启后也可用。如果关闭保留的运行时失败,这些选项仍可用于重试。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw