周红伟：OpenClaw + Claude Code：2 种模式 + 4 层架构，让 AI 开发助手持续跑起来

OpenClaw Claude Code2 种模式 4 层架构图 1OpenClaw Claude Code 核心架构概览你有没有遇到过这样的情况用 Claude Code 写代码聊着聊着上下文就爆了运行/clear清空后它又忘了项目背景第二天打开新会话之前讨论的架构决策全部归零。这些问题的根源是同一个AI 的记忆是临时的没有持久化机制。OpenClaw Claude Code 的组合用职责分离的思路解决了这个问题OpenClaw 负责会话管理和任务编排Claude Code 专注代码执行。两个系统通过 ACP 协议通信实现了真正可持续运行的开发工作流。1. 架构本质不是工具是协作系统ACP 协议编排与执行的桥梁根据 OpenClaw 官方文档的定义ACPAgent Client Protocol是一个让外部编码工具接入的标准协议。支持的工具包括 Pi、Claude Code、Codex、OpenCode、Gemini CLI、Kimi 等。核心定位是这样的代码语言javascriptAI代码解释OpenClaw编排层 ↓ ACP 协议 Claude Code执行层OpenClaw 不直接写代码它负责接收来自 Discord、Telegram、Slack 等渠道的任务管理会话的生命周期追踪任务进度处理异常和重试Claude Code 也不关心会话管理它只管读取代码库编辑文件运行命令执行测试这种分离的好处是各司其职。OpenClaw 可以同时管理多个 Claude Code 实例每个实例处理不同项目而 Claude Code 不需要操心如何跟 Discord 通信这种事专注做好代码工作。会话标识的设计官方文档给出了清晰的会话标识格式类型Session Key 格式Sub-agentagent:agentId:subagent:uuidACP sessionagent:agentId:acp:uuid这个设计让 OpenClaw 能精确追踪每个会话的状态也方便后续通过命令行或 API 操作特定会话。2. 会话管理两种模式应对不同场景ACP 会话有两种运行模式官方文档把它们叫persistent和oneshot。persistent持久化会话这是长期运行任务的核心。持久化会话支持线程绑定——把 OpenClaw 的某个线程绑定到特定的 ACP 会话上后续消息自动路由。启动命令代码语言javascriptAI代码解释/acp spawn claude --mode persistent --thread auto --cwd /workspace/my-project参数说明--mode persistent持久化模式--thread auto自动绑定到当前线程--cwd指定工作目录持久化会话适合这些场景跨天的开发任务需要多轮对话的复杂需求团队协作多人通过同一线程跟进进度oneshot单次执行简单直接执行完任务就关闭会话不留痕迹。代码语言javascriptAI代码解释/acp spawn claude --mode oneshot --thread off适合这些场景快速代码审查一次性 bug 修复简单的文件查询两种会话模式对比持久化模式 vs 单次模式图 2持久化模式与单次模式的特性对比线程绑定机制官方文档详细说明了线程绑定的行为OpenClaw 将线程绑定到目标 ACP 会话后续消息自动路由到绑定的会话ACP 的输出返回到同一线程Unfocus/Close/Archive/Idle-timeout 会移除绑定支持的渠道包括Discord threads/channelsTelegram topics包括群组话题和私聊话题通过 Plugin channels 扩展的其他渠道关键配置示例代码语言javascriptAI代码解释{ session: { threadBindings: { enabled: true, idleHours: 24, // 空闲 24 小时后自动关闭 maxAgeHours: 0, // 不限制最大存活时间 }, }, channels: { discord: { threadBindings: { enabled: true, spawnAcpSessions: true, // 允许线程绑定 ACP 会话 }, }, }, }idleHours: 24是个合理的默认值——太短会频繁重建会话太长会占用资源。根据你的任务特点调整。线程绑定机制流程从消息发送到结果返回的完整流程图 3线程绑定机制的完整工作流程3. 权限配置安全是底线ACP 会话有个关键特点非交互运行。官方文档说得清楚ACP sessions run non-interactively — there is no TTY to approve or deny file-write and shell-exec permission prompts.这意味着你不能像在终端里那样遇到权限提示时手动批准。必须在配置时就想清楚。permissionMode 的三种级别值行为风险适用场景approve-all自动批准所有文件写入和 shell 命令高受信任的内部环境approve-reads仅自动批准读取操作写入和执行需要提示中生产环境推荐deny-all拒绝所有权限提示低极度安全场景但会阻塞任务生产环境建议用approve-reads。它让 Claude Code 能自由读取代码但写入和执行命令时会停下来等你确认。配置命令代码语言javascriptAI代码解释# 设置权限模式 openclaw config set plugins.entries.acpx.config.permissionMode approve-readsnonInteractivePermissions权限冲突怎么办当permissionMode设置为approve-reads时Claude Code 想写文件但没法交互确认怎么办nonInteractivePermissions决定了行为值行为fail中止会话抛出 AcpRuntimeError默认deny静默拒绝权限任务继续优雅降级代码语言javascriptAI代码解释# 设置非交互模式处理 openclaw config set plugins.entries.acpx.config.nonInteractivePermissions failfail是更安全的选择——出问题时你会立刻知道而不是让任务带着错误继续跑。沙箱限制一个重要的坑官方文档明确指出ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox.这意味着如果请求者会话是沙箱化的ACP spawns 会被阻止sessions_spawnwithruntime: acp不支持sandbox: require需要沙箱强制执行时使用runtimesubagent如果你遇到这个错误代码语言javascriptAI代码解释Sandboxed sessions cannot spawn ACP sessions because runtimeacp runs on the host. Use runtimesubagent from sandboxed sessions.解决方案是要么从非沙箱会话启动 ACP要么改用runtimesubagent。4. 四层架构从需求到交付基于官方配置示例可以梳理出一个清晰的四层架构代码语言javascriptAI代码解释┌─────────────────────────────────────────────┐ │ 第一层任务入口层 │ │ Discord / Telegram / Slack / GitHub │ └─────────────────┬───────────────────────────┘ │ ┌─────────────────▼───────────────────────────┐ │ 第二层编排层OpenClaw │ │ 任务解析 / 状态追踪 / 异常处理 │ └─────────────────┬───────────────────────────┘ │ ACP 协议 ┌─────────────────▼───────────────────────────┐ │ 第三层执行层Claude Code │ │ 代码读取 / 文件编辑 / 测试运行 │ └─────────────────┬───────────────────────────┘ │ ┌─────────────────▼───────────────────────────┐ │ 第四层验收层 │ │ lint / typecheck / 测试 / 通知 │ └─────────────────────────────────────────────┘每一层有明确的职责边界入口层只负责接收需求创建线程或话题。它不理解代码只负责把消息传给编排层。编排层是大脑。它解析任务意图决定用哪个 agent追踪执行状态处理失败重试。执行层是手脚。它不关心任务从哪来只管按指令操作代码库。验收层是质检。自动运行 lint、类型检查、单元测试确保代码质量。这种分层的好处是可替换性。执行层可以换成 Codex 或 Gemini CLI入口层可以从 Discord 换成 Slack编排层不需要改动。四层架构图从任务入口到验收的完整分层图 4四层架构的完整结构和职责边界5. 实战配置Discord 自动化工作流来看一个完整的配置示例展示如何在 Discord 上实现任务自动化。完整配置文件代码语言javascriptAI代码解释{ // Discord 渠道配置 channels: { discord: { enabled: true, token: ${DISCORD_TOKEN}, // 从环境变量读取 threadBindings: { enabled: true, spawnAcpSessions: true, }, }, }, // Agent 配置 agents: { list: [ { id: claude, runtime: { type: acp, acp: { agent: claude, backend: acpx, mode: persistent, cwd: /workspace/my-project, }, }, }, ], }, // 会话管理 session: { threadBindings: { enabled: true, idleHours: 24, }, }, // ACP 基础配置 acp: { enabled: true, dispatch: { enabled: true }, backend: acpx, defaultAgent: claude, allowedAgents: [pi, claude, codex, opencode, gemini, kimi], maxConcurrentSessions: 8, }, // 权限配置 plugins: { entries: { acpx: { config: { permissionMode: approve-reads, nonInteractivePermissions: fail, }, }, }, }, }通过 API 启动会话除了命令行还可以通过sessions_spawnAPI 启动会话代码语言javascriptAI代码解释{ task: Review the PR and fix any failing tests, runtime: acp, agentId: claude, thread: true, mode: session, cwd: /workspace/my-project }参数说明task发送给 ACP 会话的初始提示runtime必须设置为acpagentId目标工具 id不填则用默认 agentthread是否请求线程绑定moderun单次或session持久化恢复已有会话如果会话中断了可以用resumeSessionId恢复代码语言javascriptAI代码解释{ task: Continue fixing the remaining test failures, runtime: acp, agentId: claude, resumeSessionId: agent:claude:acp:a1b2c3d4-... }常用命令速查命令功能/acp spawn创建 ACP 会话/acp status查看会话状态/acp steer向运行中的会话发送调整指令/acp cancel取消当前轮次不关闭会话/acp close关闭会话并解除线程绑定/acp sessions列出最近的 ACP 会话/acp doctor检查后端健康状态你在项目中用过类似的自动化方案吗是走 Discord 还是其他渠道评论区聊聊你的实践经验。6. 故障排查常见错误和解决方案官方文档的 Troubleshooting 章节列出了常见问题这里整理几个高频场景错误信息原因解决方案ACP runtime backend is not configured后端插件缺失运行 /acp doctor 检查安装 acpx 插件ACP is disabled by policyACP 全局禁用设置 acp.enabledtrueACP agent id is not allowedAgent 不在白名单更新 acp.allowedAgents 列表Sandboxed sessions cannot spawn ACP沙箱限制改用 runtimesubagent 或从非沙箱会话启动Permission prompt unavailable in non-interactive mode权限模式阻止操作检查 permissionMode 配置排查流程建议先跑/acp doctor这个命令会检查后端健康状态和能力查看/acp sessions确认会话状态和 key 是否正确检查配置项acp.enabled、acp.dispatch.enabled、acp.allowedAgents看沙箱设置确认是否在沙箱化会话中尝试启动 ACP总结什么时候用什么时候不用OpenClaw Claude Code 的组合适合这些场景✅ 需要跨天运行的长期开发任务✅ 团队协作多人通过同一线程跟进进度✅ 多渠道接入Discord、Telegram 等不太适合这些场景❌ 简单的一次性代码查询直接用 Claude Code 更快❌ 需要严格沙箱隔离的环境ACP 目前跑在宿主机❌ 没有多渠道接入需求的个人项目