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）才能发现新问题，会引入不必要的延迟。
- 写入文件：在 IPC 目录下生成一个唯一的 JSON 文件（例如
转发与呈现：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": "What's 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." }- 自由文本输入：第一个问题没有设置
options，Bridge 和 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_ID="auth-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_MS | 300000(5分钟) | 等待用户回复的超时时间。对于复杂决策，可以适当调高。超时后，Claude Code 会收到超时错误。 |
OPENCLAW_BRIDGE_HOST | 127.0.0.1 | 回调服务器绑定的主机。在容器或特殊网络环境下，可能需要改为0.0.0.0。 |
CC_WORKDIR | 当前目录 | 强烈建议设置。提供项目路径，方便定位问题。 |
CC_TASK | (空) | 强烈建议设置。用一句话清晰描述任务，这是最重要的上下文。 |
CC_ID | cc-<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_HOST=0.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_MS=600000（10分钟）。但也不宜过长，以免进程僵死。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 流水线和自动化代码审查脚本后，那种“设置好任务，然后放心去做别的事，只在需要决策时被轻轻提醒一下”的工作流，极大地提升了人机协作的舒适度和整体效率。它或许只是一个小工具，但却精准地解决了一个真实且高频的痛点。
