1. 项目概述为无头Claude Code装上“耳朵”和“嘴巴”如果你和我一样经常在服务器上跑一些自动化的AI编码任务比如用Claude Code来重构代码库或者批量修复安全漏洞那你肯定遇到过这个经典难题当AI在后台默默执行时一旦遇到需要人工决策的关键节点比如“该用JWT还是会话来处理认证”、“这个新服务叫什么名字好”整个流程就会卡住。传统的做法要么是预先写好一堆复杂的决策规则——这往往不切实际要么就是让AI自己“猜”结果常常跑偏。这个痛点正是totorospirit/cc-openclaw-bridge这个项目诞生的背景。简单来说OpenClaw Bridge 是一个 MCP 服务器。它的核心使命就是为在无头headless模式下运行的 Claude Code 提供一个与真人用户实时沟通的通道。你可以把它想象成给一个埋头苦干的“盲人”程序员配上了一副智能耳机和麦克风。当 Claude Code 在后台执行任务遇到需要人类智慧介入的决策点时它会通过这个桥接器将问题精准地“说”给你听而你无论正坐在电脑前还是在通勤路上用手机都可以通过 Telegram、Signal、Discord 等任何你常用的通讯应用轻松地给出答复。你的指令会实时传回Claude Code 便能继续它的工作。这个设计巧妙地将 AI 的自动化执行能力与人类的即时判断能力结合了起来。它不是一个复杂的聊天机器人框架而是一个极其专注的“通信中继”。项目通过 Claude 官方的Model Context Protocol标准接入这意味着它和 Claude Code 的集成是原生、稳定且高效的。我实际部署使用了几周最大的感受是它把那种需要频繁在终端和通讯软件之间切换的割裂感彻底消除了让 AI 辅助编程真正变得“流式”和“无感”。2. 核心架构与通信流程拆解要理解这个桥接器为何高效我们需要深入其通信架构。整个流程设计得非常清晰遵循了 Unix 哲学中“做一件事并做好”的原则同时利用了文件系统和 HTTP 这两种成熟、可靠的通信机制。2.1 核心组件与职责整个系统涉及五个核心角色它们协同完成一次“提问-回答”的闭环Claude Code任务的执行者。它在无头模式下运行通过-p参数调用项目预定义的 MCP 工具。OpenClaw Bridge核心的 MCP 服务器。它负责接收 Claude Code 的请求将其转换为标准格式并触发后续流程。IPC 目录一个临时文件系统目录默认为/tmp/cc-openclaw-bridge/。它是 Bridge 与 OpenClaw Agent 之间的异步通信缓冲区所有待处理的问题和通知都以 JSON 文件的形式暂存于此。OpenClaw Agent用户消息的调度中心。它监听 IPC 目录的变化读取问题文件并将内容转发到用户配置的通讯平台如 Telegram。用户最终的决策者。在 Telegram 等应用上接收问题并回复。2.2 一次完整的问答时序解析让我们跟随一个典型问题“该选择 JWT 还是会话来处理认证”的旅程看看数据是如何流动的发起提问Claude Code 在执行claude -p “refactor the auth module”时遇到认证方案的选择点。它调用 Bridge 提供的ask_user工具并附上问题详情。写入与唤醒Bridge 接收到请求后执行两个关键操作写入文件在 IPC 目录下生成一个唯一的 JSON 文件例如ask-abc123.json里面完整记录了问题内容、选项以及一个至关重要的callbackUrl。这个 URL 是 Bridge 临时启动的一个微型 HTTP 服务器端点专为接收本次答案而设。发送唤醒信号Bridge 通过 OpenClaw 的系统事件机制主动通知 OpenClaw Agent“有新的问题来了快去 IPC 目录看看”注意这个“写入后唤醒”的机制是保证低延迟的关键。如果只写入文件而不通知Agent 可能需要等待下一次轮询polling才能发现新问题会引入不必要的延迟。转发与呈现OpenClaw Agent 被唤醒后立即扫描 IPC 目录找到新的ask-*.json文件。它解析文件内容并将其格式化为适合 Telegram 等平台的消息例如将选项变成按钮或清晰的列表然后发送给用户。用户回复用户在 Telegram 上看到问题点击“JWT”按钮或直接输入“JWT”。回传答案OpenClaw Agent 捕获用户的回复按照约定格式封装例如{“answer”: “JWT”}然后向 Bridge 之前提供的那个唯一的callbackUrl发起一个 HTTP POST 请求。返回与继续Bridge 的微型 HTTP 服务器收到 POST 请求验证后将答案返回给正在等待的 Claude Code。Claude Code 获得答案“JWT”随即基于此决策继续执行重构认证模块的任务。整个流程在几秒内完成对用户而言就像是在通讯软件里和朋友快速确认了一个选择一样自然。这种基于文件系统持久化、易调试和 HTTP 回调实时、准确的混合通信模式在可靠性和实时性之间取得了很好的平衡。3. 从零开始的部署与配置实战理论讲清楚了我们动手把它跑起来。部署过程非常 straightforward但有些细节配置决定了使用体验的上限。3.1 基础环境准备与一键安装首先确保你的环境已经安装了 Node.js建议 LTS 版本和 Claude Code。然后通过 Git 获取项目代码。git clone https://github.com/totorospirit/cc-openclaw-bridge.git cd cc-openclaw-bridge接下来运行项目提供的安装脚本。这个脚本做了三件重要的事情./install.sh注册 MCP 服务器它会将 OpenClaw Bridge 作为一台 MCP 服务器添加到 Claude Code 的配置中。这样Claude Code 在运行时就知道去哪里调用ask_user和notify_user这些工具了。创建持久化目录如果你是在一个临时目录克隆的项目脚本会自动将必要的文件复制到~/.local/share/cc-openclaw-bridge/这个永久位置避免临时目录被清理后服务失效。更新用户手册脚本会在你的~/.claude/CLAUDE.md文件末尾追加本桥接器的使用说明和示例方便你随时查阅。实操心得第一次运行安装脚本后建议打开~/.claude/CLAUDE.md看一眼确认说明已添加。同时可以检查 Claude Code 的 MCP 服务器配置通常位于~/.config/claude/mcp.json或类似路径确认cc-openclaw-bridge已被正确列入。3.2 与 OpenClaw Agent 的集成配置Bridge 本身只是一个“传声筒”它需要 OpenClaw Agent 来真正地把消息送到你手上。因此你需要在你的 OpenClaw Agent 配置中告诉它去监听 Bridge 使用的 IPC 目录。打开你的 OpenClaw Agent 配置文件通常是AGENTS.md或HEARTBEAT.md添加如下任务### 监听 Claude Code 桥接器 - **检查目录**: /tmp/cc-openclaw-bridge/ - **处理逻辑**: - 如果发现 ask-*.json 文件读取内容将问题转发给用户并将用户的回复 POST 到文件内指定的 callbackUrl。 - 如果发现 notify-*.json 文件读取内容作为单向通知转发给用户。 - 如果发现 summary-*.json 文件读取内容作为任务完成总结转发给用户。关键配置解析目录路径默认是/tmp/cc-openclaw-bridge/必须与 Bridge 使用的OPENCLAW_BRIDGE_IPC_DIR环境变量一致。文件模式ask-*.json和notify-*.json是 Bridge 动态创建的。你的 Agent 需要能够匹配这种通配符模式。回调请求对于ask-*.json务必要提取其中的callbackUrl字段并将用户的答案以正确的 JSON 格式下文详述POST 到这个 URL。这是整个流程能闭环的关键。3.3 在容器化环境中的特殊设置如果你和我一样喜欢在 Docker 容器内运行 OpenClaw 的整套生态那么需要额外注意文件系统的映射和内部通信。首先你需要确保 Docker 容器能够访问宿主机上的/tmp/cc-openclaw-bridge/目录。这通常在运行容器时通过-v参数挂载卷来实现docker run -v /tmp/cc-openclaw-bridge:/tmp/cc-openclaw-bridge ... your-openclaw-image其次在容器内部Bridge 需要知道如何正确地通知到同样运行在容器内的 OpenClaw Agent。项目提供了一个setup-env.mjs脚本来辅助配置容器内的环境。在容器内运行node setup-env.mjs这个脚本会根据容器环境自动调整一些内部通信的配置确保唤醒事件能正确送达。这是一个非常贴心的设计避免了我们手动去折腾容器内的进程间通信。4. 核心工具详解与高级使用技巧Bridge 目前提供了两个核心工具ask_user用于交互式提问notify_user用于发送单向通知。用好它们能极大地提升自动化脚本的智能度和用户体验。4.1ask_user设计高效的交互式提问ask_user工具的强大之处在于其灵活性。它支持单次调用提出最多 4 个问题每个问题都可以被精细地设计。基础单问题提问 这是最常见的场景。Claude Code 在代码生成过程中遇到一个明确的选择点。{ questions: [ { question: Which database library should I use for this Python project?, header: DB Choice, options: [ { label: SQLAlchemy, description: Full-featured ORM, complex projects }, { label: Tortoise-ORM, description: Async-first, modern }, { label: Raw SQL, description: Direct control, simple queries } ] } ], context: Starting a new async web backend with moderate complexity. }question: 直接显示给用户的问题文本。header: 一个简短的标签用于在消息中高亮显示问题类别帮助用户快速聚焦。options: 一个包含label和description的数组。label是返回给 Claude Code 的值description是给用户的解释。一个优秀的描述能极大减少用户的决策成本。context: 整个提问的上下文背景。这个信息非常重要它会被 Bridge 和 OpenClaw Agent 一起呈现给用户。想象一下你突然在 Telegram 上收到一个没头没尾的问题“选A还是B”你肯定会懵。而加上“我正在重构用户认证模块”这样的上下文你立刻就能理解这个决策的意义。高级功能批量提问与自由输入当任务启动时可能需要一次性确认多个前置条件。{ questions: [ { question: Whats the primary color for the UI theme?, header: UI Theme // 不提供options意味着允许用户自由输入文本 }, { question: Enable dark mode by default?, header: Dark Mode, options: [ { label: Yes, description: Use dark theme }, { label: No, description: Use light theme } ] }, { question: Which features should be included in the MVP?, header: MVP Scope, options: [ { label: user-auth, description: User registration and login }, { label: file-upload, description: Upload profile pictures }, { label: payment, description: Stripe integration }, { label: analytics, description: Basic user dashboard } ], allowMultiple: true // 允许用户多选 } ], context: Initial setup for the new dashboard project. }自由文本输入第一个问题没有设置optionsBridge 和 Agent 会将其渲染为一个文本输入框用户可以输入任意内容如 “#3b82f6”。多选支持第三个问题设置了allowMultiple: true。用户可以选择多个选项返回给 Claude Code 的答案将是一个数组例如[“user-auth”, “file-upload”]。实操心得设计问题时description字段是你的朋友。用一两句话点明每个选项的适用场景或利弊能帮用户很可能就是未来的你快速做出符合项目意图的决定。避免使用只有你自己懂的缩写或行话。4.2notify_user让自动化流程保持透明notify_user工具用于发送不需要回复的通知。这是建立用户对自动化流程信任的关键。{ message: ✅ All unit tests passed. Successfully refactored 15 files in the auth/ module. Creating pull request #42 now., context: Auth Module Refactor - Completion }使用场景任务开始/结束“开始部署生产环境 v1.2.0”。“数据库迁移完成服务已重启”。关键里程碑“成功合并 PR #101主分支已更新”。“性能测试通过平均响应时间 200ms”。预警信息“检测到 API 调用错误率上升至 5%正在检查日志”。“定时备份任务已启动预计耗时 10 分钟”。一个好的通知应该像一位尽责的助手在合适的时机告诉你发生了什么让你无需时刻盯着日志也能心中有数。context字段在这里同样重要它让通知有了明确的归属方便你在繁忙的信息流中快速分类。4.3 会话总结为每次协作画上句号这是一个非常优雅的自动化特性。当 Claude Code 进程结束时Bridge 会自动生成一个summary-*.json文件记录本次会话中所有交互的摘要。摘要内容通常包括会话的开始时间、持续时间。执行的任务描述来自CC_TASK环境变量。提出的所有问题及用户给出的答案。发送的所有通知。OpenClaw Agent 可以将这份摘要转发给你。这相当于一份自动生成的“工作日志”让你回顾这次 AI 协作到底做了什么、经历了哪些决策点。对于审计、知识沉淀或者单纯满足好奇心都极具价值。5. 多实例并行与上下文优化在实际工作中我们可能会同时运行多个 Claude Code 实例来处理不同的任务例如一个在重构前端一个在优化后端 API。Bridge 对此有良好的支持。5.1 并行运行机制每个独立的 Claude Code 进程启动时Bridge 会为其创建一个唯一的标识符默认基于进程 PID如cc-12345。这个 ID 会用于隔离 IPC 文件每个实例的问题和通知文件都会包含这个 ID避免文件名冲突。独立回调服务器每个实例会绑定不同的随机端口来启动其 HTTP 回调服务器用于接收答案。OpenClaw Agent 在读取/tmp/cc-openclaw-bridge/目录下的文件时可以看到来自不同实例的请求。一个成熟的 Agent 实现应该能够将这些请求分组或打上标签呈现给用户例如“【前端重构任务】提问...”“【后端API任务】通知...”。5.2 环境变量为任务注入丰富上下文为了让 OpenClaw Agent以及最终的你在收到消息时能立刻明白“这是哪个任务在问问题”强烈建议在启动 Claude Code 前设置以下环境变量export CC_WORKDIR$PWD # 当前工作目录通常是项目根路径 export CC_TASK修复用户登录接口的速率限制漏洞 # 用清晰的语言描述当前任务 export CC_IDauth-fix-$(date %s) # 自定义一个更有意义的ID而不仅仅是PID设置后再运行你的命令claude -p review the auth/login.py file这样当问题通过 Telegram 发到你手机上时显示的就不仅仅是干巴巴的问题而是【任务修复用户登录接口的速率限制漏洞】 【目录/home/user/projects/myapp】 问题 (Auth): 选择哪种速率限制算法 - Token Bucket: 平滑允许突发流量 - Fixed Window: 实现简单但边界可能超限拥有这样的上下文你几乎不需要回忆就能做出准确的判断极大提升了远程决策的效率。配置变量总览环境变量默认值描述与建议OPENCLAW_BRIDGE_IPC_DIR/tmp/cc-openclaw-bridge临时文件交换目录。确保所有相关进程Bridge, Agent都有读写权限。OPENCLAW_BRIDGE_TIMEOUT_MS300000(5分钟)等待用户回复的超时时间。对于复杂决策可以适当调高。超时后Claude Code 会收到超时错误。OPENCLAW_BRIDGE_HOST127.0.0.1回调服务器绑定的主机。在容器或特殊网络环境下可能需要改为0.0.0.0。CC_WORKDIR当前目录强烈建议设置。提供项目路径方便定位问题。CC_TASK(空)强烈建议设置。用一句话清晰描述任务这是最重要的上下文。CC_IDcc-PID实例标识符。建议按“项目-任务”格式自定义便于区分。6. 故障排查与效能提升指南即使设计再精良在实际部署和长期使用中也可能遇到问题。下面是我在实战中总结的一些常见坑点及其解决方案。6.1 常见问题速查表现象可能原因排查步骤与解决方案Claude Code 调用ask_user后长时间无反应最终超时。1. OpenClaw Agent 未运行或未正确配置监听目录。2. IPC 目录权限不足Bridge 无法写入文件。3. 网络/防火墙阻止了callbackUrl的回调。1.检查 Agent确认 OpenClaw Agent 进程在运行且配置中监听了正确的IPC_DIR。2.检查文件在 Claude Code 执行时立刻去IPC_DIR查看是否有新的ask-*.json文件生成。如果没有检查目录权限 (ls -la /tmp/cc-openclaw-bridge/)。3.检查回调查看ask-*.json文件中的callbackUrl如http://127.0.0.1:54321/callback/abc123。尝试用curl -X POST手动模拟一个回答看 Bridge 是否有日志输出。用户在 Telegram 上回答了但 Claude Code 没有收到回复任务卡住。1. OpenClaw Agent 未能正确解析用户回复并 POST 到callbackUrl。2. Bridge 的回调 HTTP 服务意外终止。3. 答案格式不正确。1.检查 Agent 日志查看 OpenClaw Agent 的日志确认它是否成功读取了用户回复并发起了 POST 请求。2.检查网络连通性从 Agent 所在机器用curl测试能否访问callbackUrl的主机和端口。3.检查答案格式确保 Agent POST 的数据是准确的 JSON例如单问题用{“answer”: “value”}多问题用{“answers”: [{“answer”: “v1”}, {“answer”: “v2”}]}。通知 (notify_user) 没有发送到通讯软件。1.notify-*.json文件未被 Agent 处理。2. Agent 的消息发送模块如 Telegram Bot配置错误或失效。1.检查 IPC 目录确认生成了notify-*.json文件。2.测试 Agent 基础功能通过其他方式测试你的 OpenClaw Agent 是否能正常向 Telegram 等平台发送消息。在 Docker 容器内运行整个流程不工作。1. IPC 目录 (/tmp/cc-openclaw-bridge) 未在容器和宿主机间正确挂载共享。2. 容器内部网络导致127.0.0.1的回调地址无法被宿主机上的 Claude Code 访问。1.确认 Volume 挂载使用docker inspect container_id检查容器的挂载点。2.调整绑定主机在容器内运行 Bridge 时设置环境变量OPENCLAW_BRIDGE_HOST0.0.0.0使其监听所有接口。确保 Claude Code 能访问到容器的 IP 和映射端口。6.2 效能与稳定性优化建议IPC 目录的清理/tmp/cc-openclaw-bridge/目录下的文件在会话结束后可能不会自动清理。长期运行后可以设置一个定时任务cron job来定期清理过时的.json文件例如删除 1 小时前的文件find /tmp/cc-openclaw-bridge -name “*.json” -mmin 60 -delete。超时时间的权衡OPENCLAW_BRIDGE_TIMEOUT_MS默认 5 分钟。对于简单的二选一问题这个时间足够。但如果问题需要你查阅文档或思考可能会超时。可以根据任务性质调整在启动 Claude Code 前export OPENCLAW_BRIDGE_TIMEOUT_MS60000010分钟。但也不宜过长以免进程僵死。OpenClaw Agent 的消息聚合如果你同时运行多个任务可能会在短时间内收到大量提问。一个优秀的 OpenClaw Agent 实现应该具备消息聚合能力比如将 1 分钟内来自同一CC_ID的多个问题合并为一条消息发送避免刷屏。答案的验证与重试在复杂的网络环境下从 Agent 到 Bridge 的回调 POST 可能会失败。可以在 Agent 端实现简单的重试逻辑例如3 次重试每次间隔 2 秒并在失败时给用户一个提示让用户知道需要重新发送答案。安全考量回调服务器 (callbackUrl) 是临时启动的 HTTP 服务。虽然它通常只监听本地回环地址 (127.0.0.1)且会话结束后就关闭但在多用户系统或特殊网络配置下仍需注意。确保不要将OPENCLAW_BRIDGE_HOST随意设置为0.0.0.0除非你清楚网络环境是安全的。这个桥接器的设计哲学在于“专注”和“解耦”。它不试图接管你的消息平台也不干预 Claude Code 的运作逻辑只是忠实地在两者之间传递结构化的数据。这种简洁性使得它异常稳定和可靠。在我将其集成到日常的 CI/CD 流水线和自动化代码审查脚本后那种“设置好任务然后放心去做别的事只在需要决策时被轻轻提醒一下”的工作流极大地提升了人机协作的舒适度和整体效率。它或许只是一个小工具但却精准地解决了一个真实且高频的痛点。