OpenClaw ACP 命令使用指南

什么是 ACP？

ACP（Agent Client Protocol）是 OpenClaw 用于连接外部编程工具（如 Claude Code、Codex、OpenCode、Gemini CLI）的协议。通过 ACP，你可以在聊天中直接调用这些强大的代码工具来完成编程任务。

📋 命令速查表

命令	用途	使用频率
`/acp spawn`	创建 ACP 会话	⭐⭐⭐⭐⭐
`/acp steer`	发送指令到运行中的会话	⭐⭐⭐⭐⭐
`/acp close`	关闭会话	⭐⭐⭐⭐
`/acp status`	查看会话状态	⭐⭐⭐⭐
`/acp sessions`	列出所有会话	⭐⭐⭐
`/acp cancel`	取消当前任务	⭐⭐⭐
`/acp doctor`	检查 ACP 健康状态	⭐⭐
`/acp cwd`	设置工作目录	⭐⭐⭐
`/acp model`	切换模型	⭐⭐
`/acp permissions`	设置权限策略	⭐⭐

---

🚀 核心命令详解

1. 创建会`/acp spawn`

基础语法：

/acp spawn <agent> [选项]

常用选项：

--mode persistent|oneshot - 持久模式（默认）或一次性模式
--thread auto|here|off - 线程绑定方式
--cwd <路径> - 设置工作目录
--label <名称> - 给会话起个短名字

场景示例：

场景 1：日常代码编写（持久会话）

/acp spawn claude --mode persistent --label myproject --cwd /home/user/myproject

适用场景：长期项目开发，需要保持上下文记忆

场景 2：临时任务（一次性会话）

/acp spawn claude --mode oneshot --cwd /tmp 帮我写一个 Python 脚本来计算斐波那契数列

适用场景：一次性小任务，不需要保留会话

场景 3：群聊中创建绑定会话

/acp spawn claude --mode persistent --thread auto

适用场景：在 Discord/Telegram 群聊中创建专属线程

---

2. 发送指`/acp steer`

基础语法：

/acp steer [--session <会话>] <指令>

场景示例：

场景 1：给指定会话发送指令

/acp steer --session myproject 帮我修复刚才代码中的 bug

场景 2：给当前绑定的会话发送指令（不需要指定会话）

/acp steer 继续优化性能

场景 3：使用完整会话 ID

/acp steer --session agent:claude:acp:f67730ac-7d0e-4317-8ae4-1b2494ba6300 重新运行测试

---

3. 查看状`/acp status`

用途：查看当前 ACP 会话的运行状态、配置选项和后端信息

示例：

/acp status

输出示例：

Session: agent:claude:acp:xxx
Backend: acpx
Mode: persistent
Cwd: /home/user/myproject
Status: running

---

4. 关闭会`/acp close`

基础语法：

/acp close [--session <会话>]

场景示例：

场景 1：关闭当前绑定的会话

/acp close

场景 2：关闭指定标签的会话

/acp close --session myproject

场景 3：关闭所有会话（批量）

/acp sessions  # 先查看所有会话
/acp close --session agent:claude:acp:xxx
/acp close --session agent:codex:acp:yyy

---

5. 列出会`/acp sessions`

用途：查看所有活跃的 ACP 会话

示例：

/acp sessions

输出示例：

Active ACP sessions:
1. agent:claude:acp:f67730ac... (label: myproject, mode: persistent)
2. agent:codex:acp:8b9d7be9... (label: temp-task, mode: oneshot)

---

6. 取消任`/acp cancel`

用途：取消正在执行的任务（当 Claude/Code 卡住或执行太久时）

示例：

/acp cancel                    # 取消当前会话的任务
/acp cancel --session myproject # 取消指定会话的任务

---

7. 设置工作目`/acp cwd`

用途：动态更改会话的工作目录

示例：

/acp cwd /home/user/another-project
/acp cwd /tmp

---

8. 切换模`/acp model`

用途：在会话中切换不同的 AI 模型

示例：

/acp model anthropic/claude-opus-4-6
/acp model openai/gpt-5.4

---

9. 设置权`/acp permissions`

用途：设置文件操作和命令执行的权限策略

示例：

/acp permissions strict   # 严格模式（每次都要确认）
/acp permissions approve-all  # 自动批准所有操作

---

10. 健康检`/acp doctor`

用途：检查 ACP 后端是否正常工作

示例：

/acp doctor

---

🎯 完整工作流程示例

示例 1：Web 开发项目

# 1. 创建持久会话，指定项目目录
/acp spawn claude --mode persistent --label webapp --cwd /home/user/webapp

# 2. 初始化项目结构
/acp steer --session webapp 创建一个 React + TypeScript 项目，使用 Vite

# 3. 开发具体功能
/acp steer --session webapp 帮我写一个登录页面，包含邮箱和密码输入

# 4. 修复问题
/acp steer --session webapp 修复登录页面的样式问题，按钮没有对齐

# 5. 添加测试
/acp steer --session webapp 为登录页面添加单元测试

# 6. 完成后关闭
/acp close --session webapp

示例 2：数据分析任务

# 1. 创建一次性会话
/acp spawn codex --mode oneshot --cwd /home/user/data

# 2. 直接发送任务
/acp steer 分析这个 CSV 文件，生成数据可视化图表

# 3. 会话自动关闭（因为是 oneshot 模式）

示例 3：多项目并行开发

# 项目 A - 后端 API
/acp spawn claude --mode persistent --label backend --cwd /home/user/backend

# 项目 B - 前端页面  
/acp spawn claude --mode persistent --label frontend --cwd /home/user/frontend

# 切换到后端开发
/acp steer --session backend 添加用户认证 API

# 切换到前端开发
/acp steer --session frontend 集成登录接口

# 查看所有会话
/acp sessions

# 完成后关闭
/acp close --session backend
/acp close --session frontend

---

⚠️ 常见问题排查

问题 1：无法创建会话

Error: ACP runtime backend is not configured

解决：运行 /acp doctor 检查配置，确保 acpx 插件已安装

问题 2：权限被拒绝

AcpRuntimeError: Permission prompt unavailable in non-interactive mode

解决：设置权限模式

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw gateway restart

问题 3：找不到会话

Unable to resolve session target: xxx

解决：

运行 /acp sessions 查看可用会话
使用完整的会话 ID 或正确的 label

问题 4：Thread 绑定不可用

Thread bindings are unavailable for feishu.

解决：飞书私聊不支持 thread 绑定，使用 --thread off

---

💡 最佳实践

1. 使用 Label 简化操作

# ✅ 推荐：使用 label
/acp spawn claude --label myproject
/acp steer --session myproject 帮我写代码

# ❌ 不推荐：使用长 ID
/acp steer --session agent:claude:acp:f67730ac-7d0e-4317-8ae4-1b2494ba6300 帮我写代码

2. 合理选择模式

- **持久模式 persistent)**：长期项目，需要上下文记忆

- **一次性模式 oneshot)**：临时任务，用完即走

3. 及时关闭不用的会话

避免占用资源，养成用完关闭的习惯。

4. 为不同项目创建不同会话

避免上下文混淆，每个项目独立会话。

---

🔧 支持的 ACP Agent

Agent	说明	适用场景
`claude`	Claude Code	通用编程、代码审查
`codex`	OpenAI Codex	快速代码生成
`opencode`	OpenCode	开源替代方案
`gemini`	Gemini CLI	Google AI 工具
`pi`	Pi	轻量级任务
`kimi`	Kimi	国内模型选择

---

📚 进阶配置

配置默认 Agent

openclaw config set acp.defaultAgent claude

配置允许的 Agent 列表

openclaw config set acp.allowedAgents '["pi", "claude", "codex", "opencode", "gemini", "kimi"]'

配置权限模式

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

---

📖 总结

你想做什么	使用命令
开始一个新项目	`/acp spawn claude --mode persistent --label xxx --cwd /path`
发送指令给 Claude	`/acp steer --session xxx <指令>`
查看运行状态	`/acp status`
结束工作	`/acp close --session xxx`
查看所有会话	`/acp sessions`
取消卡住的任务	`/acp cancel --session xxx`
检查 ACP 健康	`/acp doctor`

[指南]ACP详细命令指南

OpenClaw ACP 命令使用指南

什么是 ACP？

📋 命令速查表

🚀 核心命令详解

1. 创建会/acp spawn

场景 1：日常代码编写（持久会话）

场景 2：临时任务（一次性会话）

场景 3：群聊中创建绑定会话

2. 发送指/acp steer

场景 1：给指定会话发送指令

场景 2：给当前绑定的会话发送指令（不需要指定会话）

场景 3：使用完整会话 ID

3. 查看状/acp status

4. 关闭会/acp close

场景 1：关闭当前绑定的会话

场景 2：关闭指定标签的会话

场景 3：关闭所有会话（批量）

5. 列出会/acp sessions

6. 取消任/acp cancel

7. 设置工作目/acp cwd

8. 切换模/acp model

9. 设置权/acp permissions

10. 健康检/acp doctor

🎯 完整工作流程示例

示例 1：Web 开发项目

示例 2：数据分析任务

示例 3：多项目并行开发

⚠️ 常见问题排查

问题 1：无法创建会话

问题 2：权限被拒绝

问题 3：找不到会话

问题 4：Thread 绑定不可用

💡 最佳实践

1. 使用 Label 简化操作

2. 合理选择模式

3. 及时关闭不用的会话

4. 为不同项目创建不同会话

🔧 支持的 ACP Agent

📚 进阶配置

配置默认 Agent

配置允许的 Agent 列表

配置权限模式

📖 总结

评论区

[指南]ACP详细命令指南

1. 创建会`/acp spawn`

2. 发送指`/acp steer`

3. 查看状`/acp status`

4. 关闭会`/acp close`

5. 列出会`/acp sessions`

6. 取消任`/acp cancel`

7. 设置工作目`/acp cwd`

8. 切换模`/acp model`

9. 设置权`/acp permissions`

10. 健康检`/acp doctor`