ACP 控制 Claude 完全指南

📋 目录

ACP 是什么
4 种控制方式
命令行控制
Tmux 会话控制
OpenClaw Sessions 控制
自定义 Agents
完整工作流
高级技巧
故障排除

1. ACP 是什么?

ACP = Anthropic Code Protocol (Anthropic 代码协议)

Claude Code 的底层通信协议
支持会话管理、消息路由、任务分发
可通过多种方式控制 Claude 实例

核心概念

┌─────────────┐
│  用户需求    │
└──────┬──────┘
       │
       ▼
┌─────────────┐     sessions_spawn      ┌──────────────┐
│  主 Claude  │ ──────────────────────> │  ACP Agent   │
│  (协调者)   │ <────────────────────── │  (执行者)    │
└─────────────┘     sessions_send       └──────────────┘

2. 4 种控制方式

方式	难度	灵活性	适用场景
命令行	⭐	⭐⭐⭐	快速交互、测试
Tmux	⭐⭐	⭐⭐⭐⭐	持久会话、本地开发
OpenClaw Sessions	⭐⭐⭐	⭐⭐⭐⭐⭐	集成管理、消息路由
自定义 Agents	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	专业化任务

3. 命令行控制

3.1 基础启动

# 最简单：直接启动
claude

# 指定名称
claude --name my-session

# 指定工作目录
cd /var/www/demo
claude --name demo-dev

3.2 Agent 选择

# 查看可用 agents
claude agents

# 使用特定 agent
claude --agent general-purpose
claude --agent Plan

# 自定义 agent（JSON）
claude --agents '{
  "coder": {
    "description": "代码专家",
    "prompt": "你是编程专家，专注于高质量代码"
  }
}'

3.3 模型选择

# 使用特定模型
claude --model sonnet
claude --model opus
claude --model haiku

# 指定完整模型名
claude --model claude-sonnet-4-6

提示： haiku 最快适合简单任务，sonnet 适合日常开发，opus 最强适合复杂任务。

3.4 权限控制

# 跳过权限确认（受信任目录）
claude --permission-mode bypassPermissions

# 计划模式（只规划不执行）
claude --permission-mode plan

# 自动模式
claude --permission-mode auto

# 默认模式（每次询问）
claude --permission-mode default

3.5 工具控制

# 只允许特定工具
claude --allowed-tools "Bash,Read,Edit"

# 允许特定命令
claude --allowed-tools "Bash(git:*)"

# 禁止特定工具
claude --disallowed-tools "WebSearch,Browser"

# 禁用所有工具
claude --tools ""

4. Tmux 会话控制

4.1 创建会话

# 方式 1：手动创建
tmux new-session -d -s demo-dev
tmux send-keys -t demo-dev 'cd /var/www/demo' Enter
tmux send-keys -t demo-dev 'claude --name demo-dev' Enter

# 方式 2：一键创建
tmux new-session -d -s demo-dev -n dev 'cd /var/www/demo && claude --name demo-dev'

# 方式 3：使用项目管理器
/root/.openclaw/workspace/project-manager-3.sh tmux demo

4.2 连接和分离

# 附加到会话
tmux attach -t demo-dev
# 或简写
tmux a -t demo-dev

# 分离会话（保持后台运行）
# 在 tmux 中按：Ctrl+B, D

# 强制分离
tmux detach -t demo-dev

4.3 发送命令

# 发送简单命令
tmux send-keys -t demo-dev 'ls -la' Enter

# 发送多行
tmux send-keys -t demo-dev 'git status' Enter 'git log -5' Enter

# 发送特殊键
tmux send-keys -t demo-dev C-c      # Ctrl+C
tmux send-keys -t demo-dev C-d      # Ctrl+D
tmux send-keys -t demo-dev Enter    # 回车

4.4 查看输出

# 捕获整个面板
tmux capture-pane -t demo-dev -p

# 只看最后 20 行
tmux capture-pane -t demo-dev -p | tail -20

# 持续监控（类似 tail -f）
watch -n 1 "tmux capture-pane -t demo-dev -p | tail -20"

最佳实践： 使用 Tmux 可以让 Claude 在后台持续工作，随时可以断开和重连，非常适合长时间运行的任务。

5. OpenClaw Sessions 控制

5.1 启动 ACP 会话

mode="session"（持久会话，推荐）

sessions_spawn \
  --runtime "acp" \
  --agentId "claude-code" \
  --mode "session" \
  --thread true \
  --label "demo-dev" \
  --cwd "/var/www/demo" \
  --task "你是 demo 项目的负责人。职责：
1. 维护项目代码
2. 修复 Bug
3. 添加新功能
4. 优化性能
5. 管理项目文档"

特点：

✅ 会话持久化
✅ 可以多次发送消息
✅ 支持消息路由
✅ 适合长期项目

mode="run"（一次性任务）

sessions_spawn \
  --runtime "acp" \
  --agentId "claude-code" \
  --mode "run" \
  --cwd "/var/www/demo" \
  --task "一次性任务：检查代码质量并生成报告"

特点：

✅ 执行完就退出
✅ 适合单次任务
❌ 不支持多次交互
❌ 不需要 thread=true

5.2 参数详解

参数	必需	说明	示例
`runtime`	✅	运行时类型	`"acp"`
`agentId`	✅	ACP 代理 ID	`"claude-code"`
`mode`	✅	会话模式	`"session"` / `"run"`
`thread`	⚠️	线程绑定	`true` (session 模式需要)
`label`	✅	会话标签	`"demo-dev"`
`cwd`	✅	工作目录	`"/var/www/demo"`
`task`	✅	任务描述	`"项目职责说明"`

5.3 发送消息

简单任务

sessions_send \
  --sessionKey "demo-dev" \
  --message "请检查项目状态"

复杂任务

sessions_send \
  --sessionKey "demo-dev" \
  --message "请完成以下任务：
1. 添加用户登录页面
2. 实现表单验证
3. 连接数据库
4. 添加错误处理"

5.4 查看状态

# 列出所有 ACP 会话
sessions_list --kinds acp

# 列出最近活跃的会话
sessions_list --kinds acp --activeMinutes 60

# 查看会话历史
sessions_history --sessionKey "demo-dev" --limit 50

# 查看包含工具调用的历史
sessions_history --sessionKey "demo-dev" --limit 50 --includeTools true

6. 自定义 Agents

6.1 定义自定义 Agent

方式 1：命令行 JSON

claude --agents '{
  "frontend": {
    "description": "前端开发专家",
    "prompt": "你是前端开发专家，专注于 React、Vue、CSS。你善于创建美观、响应式的用户界面。",
    "model": "sonnet"
  },
  "backend": {
    "description": "后端开发专家",
    "prompt": "你是后端开发专家，专注于 Node.js、Python、数据库设计。你善于设计高性能 API。",
    "model": "opus"
  },
  "reviewer": {
    "description": "代码审查专家",
    "prompt": "你是代码审查专家，专注于代码质量、安全性、性能优化。你会仔细检查每一行代码。",
    "model": "sonnet"
  }
}'

方式 2：配置文件

# 创建自定义 agents 配置
mkdir -p ~/.claude
cat > ~/.claude/custom-agents.json << 'EOF'
{
  "security-expert": {
    "description": "安全专家",
    "prompt": "你是网络安全专家，专注于漏洞检测、安全加固、渗透测试",
    "model": "opus"
  },
  "performance-guru": {
    "description": "性能优化专家",
    "prompt": "你是性能优化专家，专注于代码优化、数据库调优、缓存策略",
    "model": "sonnet"
  },
  "ui-designer": {
    "description": "UI/UX 设计师",
    "prompt": "你是 UI/UX 设计师，专注于用户体验、视觉设计、交互设计",
    "model": "sonnet"
  }
}
EOF

# 使用配置文件
claude --settings ~/.claude/custom-agents.json

6.2 使用自定义 Agent

# 列出所有 agents
claude agents

# 使用自定义 agent
claude --agent frontend "创建一个 React 登录组件"
claude --agent backend "设计一个 RESTful API"
claude --agent reviewer "审查这个代码库"

7. 完整工作流

场景 1：创建新项目

# 1. 创建项目目录
mkdir -p /var/www/myapp
cd /var/www/myapp

# 2. 初始化项目
git init
echo "# My App" > README.md

# 3. 启动 ACP 会话
sessions_spawn \
  --runtime "acp" \
  --agentId "claude-code" \
  --mode "session" \
  --thread true \
  --label "myapp-dev" \
  --cwd "/var/www/myapp" \
  --task "你是 myapp 项目的负责人。这是一个 Node.js Web 应用。"

# 4. 发送初始任务
sessions_send \
  --sessionKey "myapp-dev" \
  --message "请初始化项目结构：
1. package.json
2. src/ 目录
3. tests/ 目录
4. .gitignore"

# 5. 查看进度
sleep 5
sessions_history --sessionKey "myapp-dev" --limit 20

场景 2：多项目并行开发

# 启动前端项目
sessions_spawn \
  --runtime "acp" \
  --label "frontend" \
  --cwd "/var/www/frontend" \
  --task "前端项目（React）"

# 启动后端项目
sessions_spawn \
  --runtime "acp" \
  --label "backend" \
  --cwd "/var/www/backend" \
  --task "后端项目（Node.js）"

# 并行发送任务
sessions_send --sessionKey "frontend" --message "创建登录页面 UI"
sessions_send --sessionKey "backend" --message "设计用户认证 API"

# 查看所有项目状态
sessions_list --kinds acp

8. 高级技巧

8.1 并行控制多个会话

# 启动多个项目
for project in frontend backend admin; do
  sessions_spawn \
    --runtime "acp" \
    --label "$project-dev" \
    --cwd "/var/www/$project" \
    --task "$project 项目负责人"
done

# 批量发送任务
sessions_send --sessionKey "frontend-dev" --message "更新组件库"
sessions_send --sessionKey "backend-dev" --message "优化 API 性能"
sessions_send --sessionKey "admin-dev" --message "添加管理功能"

8.2 监控和调试

# 实时监控所有会话
watch -n 5 "sessions_list --kinds acp"

# 查看详细历史
sessions_history --sessionKey "demo-dev" --limit 200 --includeTools true

# 查找特定消息
sessions_history --sessionKey "demo-dev" --limit 500 | grep "ERROR"

# 导出会话历史
sessions_history --sessionKey "demo-dev" --limit 1000 > /tmp/demo-history.json

8.3 性能优化

# 使用更快的模型（简单任务）
sessions_spawn \
  --runtime "acp" \
  --model "haiku" \
  --label "quick-task" \
  --cwd "/var/www/demo" \
  --task "快速检查代码"

# 使用更强的模型（复杂任务）
sessions_spawn \
  --runtime "acp" \
  --model "opus" \
  --label "complex-task" \
  --cwd "/var/www/demo" \
  --task "重构整个架构"

# 设置超时
sessions_spawn \
  --runtime "acp" \
  --timeoutSeconds 1800 \
  --label "timed-task" \
  --cwd "/var/www/demo" \
  --task "30分钟内完成的任务"

9. 故障排除

问题 1：会话无法启动

# 检查 agentId
claude agents

# 检查工作目录
ls -la /var/www/demo

# 检查权限
cd /var/www/demo && pwd

# 查看错误日志
sessions_list --kinds acp

问题 2：消息发送失败

# 检查会话是否存在
sessions_list --kinds acp | grep demo-dev

# 检查 sessionKey
sessions_history --sessionKey "demo-dev" --limit 1

# 查看详细错误
sessions_send --sessionKey "demo-dev" --message "test" 2>&1

问题 3：会话无响应

# 查看历史
sessions_history --sessionKey "demo-dev" --limit 50

# 发送中断
sessions_send --sessionKey "demo-dev" --message "请停止"

# 终止会话
subagents --action kill --target "demo-dev"

注意： 如果会话长时间无响应，可以通过 subagents 工具强制终止，然后重新启动。

🔧 快速参考

常用命令

# 启动会话
sessions_spawn --runtime "acp" --label "demo" --cwd "/var/www/demo" --task "任务"

# 发送消息
sessions_send --sessionKey "demo" --message "任务描述"

# 查看历史
sessions_history --sessionKey "demo" --limit 50

# 列出会话
sessions_list --kinds acp

# 终止会话
subagents --action kill --target "demo"

Tmux 快捷键

快捷键	功能
`Ctrl+B, D`	分离会话
`Ctrl+B, [`	进入复制模式
`Ctrl+B, ]`	粘贴
`Ctrl+B, C`	创建新窗口
`Ctrl+B, N`	下一个窗口
`Ctrl+B, P`	上一个窗口

模型选择

模型	速度	智能度	适用场景
`haiku`	最快	中等	简单任务、快速测试
`sonnet`	快	高	日常开发、代码审查
`opus`	慢	最高	复杂架构、深度分析

相关文档：
• 完整 ACP 控制指南 PDF
• 项目管理体系
• 任务转发流程

🎛️ ACP 控制 Claude 完全指南