🤖 OpenClaw ACP Agent编程完全指南

🎯 为什么选择ACP编程模型？

凌晨3点47分，我的第1024个Agent在云端醒来。它不需要咖啡，不会抱怨加班，只是安静地执行着我交给它的任务。

这就是ACP的魅力所在——它让AI Agent真正成为你的编程伙伴，而不是简单的代码补全工具。

ACP的核心优势

• 上下文感知：ACP Agent理解整个项目结构，不只是当前文件
• 工具调用链：Agent可以串联多个工具完成复杂任务
• 持久化会话：长时间运行的任务不会丢失上下文
• 子Agent编排：一个Agent可以 spawning 多个子Agent并行工作
• 文件系统感知：Agent可以直接操作本地文件系统

🚀 快速开始：你的第一个ACP Agent

步骤1：配置ACP环境

# 在Gateway配置中启用ACP
# ~/.openclaw/config.yaml

acp:
  enabled: true
  defaultAgent: "tc-code-latest"  # 默认使用的Agent模型
  allowedAgents:
    - tc-code-latest
    - claude-code
    - gemini-code
  timeoutSeconds: 300  # 单次Agent运行超时时间

步骤2：创建ACP Agent任务

# 通过 sessions_spawn 创建ACP任务

sessions_spawn({
  "task": "创建一个Python脚本，实现网页内容抓取并保存为Markdown格式",
  "runtime": "acp",
  "agentId": "tc-code-latest",
  "mode": "run",  # run = 一次性任务, session = 持久会话
  "timeoutSeconds": 120
})

步骤3：理解ACP执行流程

📚 ACP核心概念详解

1. Runtime模式

ACP支持两种运行时模式：

• runtime: "acp" - 使用ACP协议的专业编程Agent
• runtime: "subagent" - 轻量级子Agent，适合简单任务

# ACP模式 - 适合复杂编程任务
sessions_spawn({
  "task": "重构这个Python项目，添加类型提示和文档字符串",
  "runtime": "acp",
  "agentId": "tc-code-latest",
  "mode": "session",
  "thread": true  # 创建线程绑定的持久会话
})

# Subagent模式 - 适合快速任务
sessions_spawn({
  "task": "查询今天的天气",
  "runtime": "subagent",
  "mode": "run"
})

2. Mode模式

控制Agent的生命周期：

• mode: "run" - 一次性任务，完成后自动清理
• mode: "session" - 持久会话，可以多次交互

3. Thread线程绑定

# Discord场景：创建线程绑定的ACP会话
sessions_spawn({
  "task": "帮我调试这个React组件的useEffect问题",
  "runtime": "acp",
  "agentId": "claude-code",
  "mode": "session",
  "thread": true  # 绑定到Discord线程，持续对话
})

💡 最佳实践

实践1：任务分解策略

# ❌ 不好的任务描述
"帮我优化网站性能"

# ✅ 好的任务描述
"分析 /var/www/miaoquai/index.html 的加载性能，
找出导致首屏加载慢的原因，
提供具体的优化建议并实施以下改进：
1. 压缩图片资源
2. 添加懒加载
3. 优化CSS交付"

实践2：文件路径处理

ACP Agent会自动继承父级工作目录，确保路径正确：

# 假设当前工作目录是 /root/project
sessions_spawn({
  "task": "读取 config/database.yml 并添加连接池配置",
  "runtime": "acp",
  "cwd": "/root/project"  # 显式指定工作目录
})

实践3：错误处理

# 配置适当的超时时间
sessions_spawn({
  "task": "运行测试套件并生成覆盖率报告",
  "runtime": "acp",
  "timeoutSeconds": 600,  # 长任务设置更长的超时
  "runTimeoutSeconds": 0   # 0表示不限制子Agent运行时间
})

🔧 高级技巧

技巧1：子Agent编排

一个ACP Agent可以 spawning 多个子Agent并行处理：

# 主Agent任务：协调多个子Agent
"分析这个项目，我需要：
1. 生成API文档（ spawning doc-agent ）
2. 运行测试并修复失败项（ spawning test-agent ）
3. 优化数据库查询（ spawning db-agent ）

每个子任务使用 sessions_spawn 并行执行，
最后汇总结果给我。"

技巧2：工具权限控制

# 限制Agent只能使用特定工具
sessions_spawn({
  "task": "分析代码但不修改",
  "runtime": "acp",
  "sandbox": "inherit"  # inherit | require
})

技巧3：上下文传递

# 传递附件给Agent
sessions_spawn({
  "task": "根据这个设计文档实现功能",
  "runtime": "acp",
  "attachments": [{
    "name": "design.md",
    "content": "# 设计文档...",
    "encoding": "utf8"
  }]
})

📊 性能优化

1. Agent池化

对于高频任务，可以预先 spawning 多个Agent等待任务：

# 使用 cleanup: "keep" 保持Agent活跃
sessions_spawn({
  "task": "初始化开发环境",
  "runtime": "acp",
  "cleanup": "keep",  # keep | delete
  "label": "dev-agent-1"
})

# 后续直接给这个Agent发消息
sessions_send({
  "label": "dev-agent-1",
  "message": "现在实现用户认证模块"
})

2. 流式输出

# 实时查看Agent执行过程
sessions_spawn({
  "task": "长时间运行的任务",
  "runtime": "acp",
  "streamTo": "parent"  # 将输出发送到父会话
})

🎓 学习路径建议

1. 第1周：熟悉基本的 sessions_spawn 调用
2. 第2周：练习任务分解和子Agent编排
3. 第3周：学习错误处理和超时配置
4. 第4周：掌握性能优化和Agent池化
5. 第5周+：开发复杂的ACP Skills