1. 项目概述为OpenClaw智能体搭建通往Claude的专属桥梁如果你正在使用OpenClaw框架来构建Discord或Telegram上的AI智能体并且希望让这些智能体拥有Claude的强大推理和工具调用能力那么你很可能已经遇到了一个核心难题OpenClaw遵循OpenAI的API格式而Claude Code CLI命令行工具则使用一套完全不同的交互协议。直接让它们对话就像让一个说英语的人和一个说中文的人直接沟通一样困难。openclaw-claude-bridge这个项目就是为了解决这个“语言不通”的问题而生的。简单来说它是一个轻量级的HTTP代理服务器扮演着“翻译官”和“调度员”的角色。它接收来自OpenClaw智能体的、符合OpenAI API标准的请求将其“翻译”成Claude CLI能理解的指令然后启动或复用Claude CLI进程来处理请求。接着它再将Claude CLI返回的、可能包含特殊XML格式工具调用的结果流实时“翻译”回OpenAI API的格式并流式传输给OpenClaw。整个过程对两端都是透明的OpenClaw智能体以为自己正在调用一个标准的GPT-4接口而Claude CLI则以为自己在一个普通的终端会话中工作。这个项目的核心价值在于它让你无需修改OpenClaw或Claude CLI的任何一行代码就能无缝地将Claude模型集成到你的智能体工作流中。这意味着你可以立即享受到Claude模型如Opus、Sonnet、Haiku在复杂推理、代码生成和长上下文处理方面的优势同时继续使用OpenClaw成熟的工具调用、会话管理和多平台Discord/Telegram集成能力。对于已经基于OpenAI API构建了复杂智能体生态的开发者来说这无疑是一个低成本、高效率的扩展方案。2. 核心架构与设计思路拆解2.1 为什么需要一座“桥”协议差异的本质要理解这座桥的设计首先得看清两端的“语言”差异有多大。OpenAI的Chat Completion API是一个基于HTTP/JSON的请求-响应或流式响应接口。它高度结构化请求体里明确包含了messages数组包含role和content、可选的tools数组定义工具规格以及tool_choice等参数。响应体同样结构化对于工具调用会返回一个包含tool_calls数组的message对象。而Claude Code CLI是一个本地命令行工具。你通过标准输入stdin向它发送纯文本或包含特定格式指令的文本它通过标准输出stdout流式地返回响应。它的“系统提示”、“工具调用协议”都需要通过特定的命令行参数如--system--tools或在输入文本中嵌入XML标签如thinkingtool_call来传达。它没有内置的HTTP服务器也不理解JSON格式的聊天历史。这种差异导致了几个关键挑战协议转换如何将结构化的JSON消息历史转换成一段连贯的、包含上下文和工具调用指令的纯文本提示会话保持HTTP是无状态的但Claude CLI会话是有状态的它会在本地保存会话文件以实现记忆。如何将多个独立的HTTP请求关联到同一个持久的CLI会话流式交互OpenAI API支持Server-Sent EventsSSE流式返回。如何将Claude CLI的stdout流实时地、分块地转换成SSE事件流工具调用循环OpenAI格式中模型一次响应可以包含多个并行工具调用。Claude CLI的工具调用是嵌入在文本流中的XML块。如何准确解析并转换并确保工具执行结果能正确地反馈给下一轮对话openclaw-claude-bridge的架构正是围绕解决这些挑战而设计的。它不是一个简单的请求转发器而是一个有状态的、具备协议翻译和会话管理能力的中间层。2.2 核心工作流程与数据流转让我们跟随一个典型的用户提问到AI响应的全过程来理解这座桥的内部运作请求接收与解析OpenClaw智能体在Discord频道中收到用户消息。它根据配置向http://localhost:3456/v1/chat/completions发送一个POST请求。这个请求的格式与调用gpt-4完全一致包含了当前对话历史messages和可用的工具定义tools。桥接服务运行在3456端口的server.js接收到这个请求。会话路由与查找这是状态管理的核心。桥接器需要为每个“智能体对话频道”的组合维护一个独立的Claude CLI会话以实现记忆功能。它使用channel_id agent_name作为路由键在内存中和持久化的state.json文件里查找是否已存在活跃会话。如果找到则“恢复”该会话如果没找到则创建一个新的会话ID并准备启动一个新的Claude CLI进程。请求翻译与组装convert.js模块开始工作。它将OpenAI格式的messages数组系统消息、用户消息、助手消息、工具消息转换成一个单一的、格式化的文本字符串。这个字符串会模拟一个连贯的对话历史。同时tools.js模块会动态分析请求中的tools数组生成一段详细的、自然语言描述的工具使用说明书。这段说明书会被注入到系统提示通过--system参数或对话上下文的开头告诉Claude“你现在拥有这些工具请按特定XML格式调用它们”。启动/交互CLI进程claude.js模块负责与Claude CLI二进制文件交互。如果是一个新会话它会使用child_process.spawn启动一个Claude CLI子进程并传递一系列参数--model根据请求中的模型字段映射如claude-opus-latest映射为opus。--system包含动态生成工具说明的系统提示。--tools 这是一个关键的安全设置。它禁用了Claude CLI所有原生的、可能具有潜在风险的工具如直接执行Bash命令、读写文件强制Claude只能通过我们定义的、由OpenClaw管理的工具协议来调用功能。--dangerously-skip-permissions由于我们禁用了原生工具这个参数是安全的它允许CLI在无头无终端交互模式下运行。--session指定会话文件路径实现持久化记忆。--effort根据OpenAI请求中的reasoning_effort参数映射为Claude的思考强度lowmediumhigh。流式响应解析与转换桥接器将组装好的提示文本通过stdin发送给Claude CLI进程。然后它开始实时读取CLI的stdout输出流。claude.js中的解析器会严密监控输出流区分以下几种内容普通文本直接清洗后通过SSE以data: {choices:[{delta:{content:...}}]}\n\n的格式流式返回给OpenClaw。思考过程thinking.../thinking如果思考功能开启这部分内容可以被选择性地转发或用于内部调试但通常不会作为最终响应返回给用户。工具调用tool_call id... name...{...}/tool_call这是关键时刻。解析器会捕获完整的XML块将其解析并转换成OpenAI格式的tool_calls数组。然后桥接器会立即结束当前流将一个包含tool_calls的完整message对象返回给OpenClaw。桥接器至此任务完成它不执行工具。完成循环OpenClaw收到包含tool_calls的响应后会用自己的工具执行器Gateway去运行这些工具获取结果。然后OpenClaw会构造一个新的请求其中messages数组会追加一条role为tool的消息包含工具执行的结果。这个新请求再次发送给桥接器。桥接器通过相同的会话路由键找到之前的Claude CLI会话将工具执行结果作为新的输入追加进去Claude CLI便能基于之前的上下文和工具结果继续思考或回复。如此循环直至Claude返回纯文本答案OpenClaw再将其呈现给终端用户。关键设计原则这座桥的职责严格限定在协议转换和会话管理。它绝不越界去执行工具或处理业务逻辑这保证了架构的清晰和安全也使得OpenClaw能够完全掌控工具执行的权限和环境。3. 核心模块深度解析与实操要点3.1 会话管理状态、记忆与生命周期的艺术会话管理是桥接器稳定性的基石。它必须高效、准确地在无状态的HTTP世界和有状态的CLI进程世界之间建立映射。三级会话查找策略 桥接器采用了一个精细的三级查找策略来定位会话确保在异常情况下如进程崩溃、服务重启也能最大程度保持会话连续性内存映射第一优先在服务运行时一个全局的Map对象维护着路由键 - CLI进程句柄/会话信息的映射。这是最快的查找方式。持久化状态文件第二优先所有会话的元数据路由键、会话ID、创建时间、最后活动时间、token使用统计等会定期保存到项目根目录的state.json文件中。当服务重启时会从这里加载历史会话记录。磁盘会话文件校验最终保障仅仅在state.json中有记录还不够。在尝试恢复一个会话前桥接器会检查对应的Claude CLI会话文件通常位于~/.config/claude/sessions/是否真实存在。如果文件丢失可能被手动清理或CLI异常退出桥接器会认为该会话已失效自动将其从状态中清除并为此路由键创建一个全新的会话。这避免了因状态不一致导致的错误。会话清理与资源回收 Claude CLI会话文件会占用磁盘空间。桥接器提供了两种清理机制自动修剪在内部状态维护时会定期检查并移除那些在磁盘上已不存在的会话记录“僵尸”会话。手动清理通过Dashboard的“清理会话”按钮或调用/cleanupAPI可以删除所有超过24小时的CLI会话文件。请注意这只会删除CLI的会话文件桥接器自身的state.json中的记录会在下次尝试恢复时因文件不存在而被自动清理。实操心得会话隔离的妙用由于会话键是channel_id agent_name这意味着在同一个Discord频道里你可以部署多个不同职能的智能体比如一个“研究助手”和一个“代码审查员”它们彼此拥有完全独立的记忆上下文互不干扰。这为构建复杂的多智能体协作场景提供了基础。3.2 工具调用协议动态注入与安全隔离让Claude能够理解并调用OpenClaw定义的工具是整个项目最精妙的部分之一。其核心在于“动态提示词工程”。动态工具协议生成 当桥接器收到一个包含tools数组的请求时tools.js模块会将其转换成一段清晰的自然语言描述。例如一个“获取天气”的工具定义{ type: function, function: { name: get_weather, description: Get the current weather for a city., parameters: {...} } }会被转换成类似这样的文本并插入到系统提示中你拥有以下可以调用的工具。当你需要使用时请严格按照此格式输出 tool_call id一个随机UUID nameget_weather {city: 北京} /tool_call 工具说明get_weather - Get the current weather for a city. 参数city (string, required): The city name.这个过程是完全动态的。无论OpenClaw那边新增、修改或删除了什么工具桥接器都无需更新代码下次请求时自动就会包含最新的工具说明。这实现了与OpenClaw工具生态的松耦合集成。原生工具的安全禁用 Claude CLI本身内置了一些强大的工具如bash执行Shell命令、read、write读写文件。在桥接场景下允许直接使用这些工具是极其危险的因为桥接器通常以服务形式运行权限较高。因此启动Claude CLI时必须加上--tools 参数。这个参数将CLI的原生工具列表设置为空从根本上关闭了这扇风险之门。Claude只能通过我们注入的、受控的协议来调用由OpenClaw Gateway管理和鉴权的工具从而将安全边界牢牢限定在OpenClaw体系内。3.3 流式处理与性能优化为了提供与原生OpenAI API相近的流畅体验桥接器实现了完整的流式响应。非阻塞I/O与背压处理 Node.js的child_process模块允许我们以非阻塞方式与子进程Claude CLI交互。桥接器将CLI的stdout管道连接到可读流并监听data事件。一旦有数据块到达解析器立即工作识别出完整的文本行或XML标签边界然后将其转换为SSE格式通过HTTP响应流写入。这里的关键是处理好背压backpressure——如果HTTP客户端OpenClaw接收速度慢需要适当缓冲或暂停从CLI stdout读取数据防止内存溢出。项目通常利用Node.js流自身的暂停/恢复机制来实现这一点。思考过程Reasoning Effort的处理 Claude的“思考过程”是一个强大的功能。桥接器通过reasoning_effort参数控制它。在内部这个参数被映射为Claude CLI的--effort参数lowmediumhigh和一个环境变量MAX_THINKING_TOKENS。当思考开启时Claude的输出会包含thinking.../thinking标签。桥接器可以配置是丢弃这部分内容仅内部日志可见还是将其作为元数据附加在响应中。对于最终用户体验而言思考过程通常是不可见的它只是模型内部推理的痕迹最终呈现给用户的是思考后的结论。超时与僵尸进程管理 Claude CLI进程可能因为网络问题、模型负载或复杂推理而长时间无响应。桥接器设置了IDLE_TIMEOUT_MS默认2分钟。如果在设定时间内没有从CLI的stdout收到任何新数据桥接器会认为该进程已挂起并强制终止SIGKILL该子进程释放资源同时向客户端返回一个超时错误。这保证了系统的自我修复能力。4. 从零到一的完整部署与配置实操4.1 环境准备与依赖安装在开始之前请确保你的系统满足以下条件操作系统macOSIntel或Apple Silicon或 Linuxx86_64或ARM。Windows系统理论上可通过WSL2运行但非官方支持。Node.js版本18或更高。推荐使用nvm进行版本管理。Claude Code CLI已安装并完成登录认证。这是前置必要条件。OpenClaw已安装并配置好Discord/Telegram网关且网关服务正在运行默认端口18789。第一步安装Claude Code CLI如果你还没有安装请访问Anthropic官方文档获取安装指令。通常可以通过包管理器安装# macOS (Homebrew) brew install claude # Linux (部分发行版) # 请参考官方文档下载对应架构的二进制文件安装后在终端执行claude auth login按照指引完成浏览器登录认证。完成后运行claude --version和claude auth status确认安装和登录成功。第二步获取并初始化桥接器# 克隆项目代码 git clone https://github.com/shinglokto/openclaw-claude-bridge.git cd openclaw-claude-bridge # 安装Node.js依赖这会自动构建Dashboard前端 npm installnpm install命令不仅会安装后端依赖还会自动进入dashboard/目录安装前端依赖并执行构建将生成好的静态文件放入dashboard/dist/。如果前端构建失败你可以手动进入dashboard/目录运行npm install npm run build。第三步配置环境变量项目使用.env文件管理配置。首先复制示例文件cp .env.example .env现在用文本编辑器打开.env文件。以下是一些关键配置项的说明# 仪表盘密码重要。设置后访问 http://your-ip:3458 需要输入用户名 admin 和此密码。 # 如果不设置仪表盘将对局域网开放无密码保护。 DASHBOARD_PASSyour_strong_password_here # Claude CLI模型别名映射。如果你订阅了Claude API并配置了自定义模型别名可以在这里修改。 # 例如如果你将100万上下文的Opus模型别名为“opus-1m”就在这里修改。 OPUS_MODELopus SONNET_MODELsonnet HAIKU_MODELhaiku # 并发控制。防止单个频道或全局请求过多导致资源耗尽。 MAX_PER_CHANNEL2 # 每个频道channel_id同时最多处理2个请求 MAX_GLOBAL20 # 全局同时最多处理20个请求 # CLI进程超时毫秒。如果Claude CLI在120秒内没有输出任何内容进程将被终止。 IDLE_TIMEOUT_MS120000 # 服务端口 OPENCLAW_BRIDGE_PORT3456 # API服务端口仅绑定到localhost OPENCLAW_BRIDGE_STATUS_PORT3458 # 仪表盘端口绑定到所有网络接口0.0.0.0根据你的网络环境和安全需求调整这些值尤其是DASHBOARD_PASS。4.2 启动服务与基础测试配置完成后可以启动服务进行测试# 开发模式启动带日志输出 npm start # 或者以后台进程方式启动使用pm2需额外安装 # npm install -g pm2 # pm2 start src/index.js --name claude-bridge如果一切正常你将在终端看到服务器启动的日志包括API和Dashboard的监听地址。执行健康检查 打开另一个终端运行curl http://localhost:3456/health如果返回{status:ok}说明API服务运行正常。访问仪表盘 在浏览器中打开http://localhost:3458如果在本机。如果你设置了DASHBOARD_PASS会弹出HTTP Basic认证窗口输入用户名admin和你设置的密码。首次进入仪表盘可能是空的因为没有流量经过。界面顶部的状态栏应显示“在线”和正常运行时间。4.3 配置OpenClaw以使用桥接器桥接器就绪后需要告诉OpenClaw它的存在。编辑你的OpenClaw主配置文件通常位于~/.openclaw/openclaw.json在models.providers部分添加一个新的提供商命名为claude-bridge。设置baseUrl为桥接器的API地址http://localhost:3456/v1。apiKey可以任意填写一个非空字符串如not-needed因为桥接器目前不进行API密钥验证。在models数组下定义你希望通过桥接器使用的Claude模型。id字段是OpenClaw内部使用的模型标识符name是显示名称。contextWindow和maxTokens请根据你实际使用的Claude模型版本设置例如Opus 1M上下文版本对应100万。一个完整的配置示例如下{ models: { providers: { claude-bridge: { baseUrl: http://localhost:3456/v1, apiKey: not-needed, api: openai-completions, models: [ { id: claude-opus-latest, name: Claude Opus (via Bridge), contextWindow: 1000000, maxTokens: 128000, reasoning: true }, { id: claude-sonnet-latest, name: Claude Sonnet (via Bridge), contextWindow: 1000000, maxTokens: 64000, reasoning: true }, { id: claude-haiku-latest, name: Claude Haiku (via Bridge), contextWindow: 1000000, maxTokens: 64000, reasoning: false } ] } } } }保存配置文件后重启OpenClaw网关服务使配置生效。4.4 配置Discord/Telegram智能体使用Claude模型最后一步修改你的智能体定义让其使用我们刚刚配置的模型。在你的智能体配置文件例如my_agent.json中找到model字段将其值改为你在上一步中定义的id例如claude-opus-latest。{ name: 我的Claude助手, model: claude-opus-latest, // 指向桥接器提供的模型 system_prompt: 你是一个乐于助人的助手..., // ... 其他配置 }完成以上所有步骤后当你的智能体在Discord或Telegram中被触发时它就会将请求发送到本地的桥接器桥接器再驱动Claude CLI生成响应。你可以立即在Discord频道中与智能体对话测试工具调用并同时在桥接器的仪表盘上观察实时请求、会话状态和资源使用情况。5. 高级配置、监控与故障排查实录5.1 仪表盘你的全景监控中心桥接器内置的React仪表盘是一个强大的运维工具它提供了近乎实时的系统状态可视化。理解每个面板的用途能让你在出现问题时快速定位。头部状态栏提供全局概览。关注“活跃请求数”是否长期居高不下可能并发过高“错误计数”是否持续增长“会话磁盘大小”是否异常膨胀可能需要手动清理。智能体侧边栏列出了所有活跃过的智能体。颜色标识其活跃度绿色5分钟内有活动、琥珀色30分钟内、灰色闲置。点击任一智能体可以过滤下方所有面板的数据这在多智能体环境下排查特定问题非常有用。实时活动流这是最动态的面板。它以日志流的形式展示每一个关键事件并配有表情符号思考Claude开启了内部推理。工具调用Claude请求调用一个工具。恢复会话请求成功关联到了一个已存在的持久化会话。♻️刷新上下文因上下文长度限制会话被重置新建。✅完成请求成功处理完毕。❌错误处理过程中发生错误如CLI进程崩溃、解析失败。上下文卡片以进度条形式展示每个会话的令牌使用情况。颜色从绿40%到黄40-65%再到红65%。红色警告你该会话可能很快会触及上下文窗口限制导致性能下降或需要昂贵的上下文刷新。请求详情表这是进行深度分析的地方。表格列出了每一个历史请求包含时间、频道、会话ID、恢复方式、提示大小、模型、思考级别、输入/输出令牌数、估算成本、缓存命中率、耗时和状态。你可以点击行展开查看该请求的详细活动日志和任何错误信息。支持按频道和恢复方式筛选是排查频道特定问题或工具调用问题的利器。5.2 系统服务化实现开机自启对于生产环境你需要将桥接器设置为系统服务确保它在服务器重启后能自动运行。macOS (使用 launchd) 项目提供了便捷的安装脚本cd openclaw-claude-bridge ./service/install-mac.sh这个脚本会自动检测Node和项目路径读取当前目录下的.env文件并生成一个正确的launchd plist配置文件将其安装到~/Library/LaunchAgents/目录下并立即加载启动。手动管理# 查看服务状态 launchctl list | grep openclaw-claude-bridge # 重启服务例如在修改.env后 launchctl bootout gui/$(id -u)/com.openclaw.claude-bridge launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.claude-bridge.plist # 查看日志日志默认输出到项目目录下的 bridge.log tail -f ~/openclaw-claude-bridge/bridge.logLinux (使用 systemd user service)# 1. 复制服务文件到用户systemd目录 cp service/openclaw-claude-bridge.service ~/.config/systemd/user/ # 2. 可选编辑服务文件确认WorkingDirectory和ExecStart路径正确 # WorkingDirectory/path/to/your/openclaw-claude-bridge # ExecStart/usr/bin/node /path/to/your/openclaw-claude-bridge/src/index.js # 3. 重载systemd配置 systemctl --user daemon-reload # 4. 启用并立即启动服务 systemctl --user enable --now openclaw-claude-bridge # 5. 允许用户服务在未登录时启动关键步骤 loginctl enable-linger $USERLinux服务管理# 查看状态 systemctl --user status openclaw-claude-bridge # 查看最新日志 journalctl --user -u openclaw-claude-bridge -n 50 -f # 重启服务 systemctl --user restart openclaw-claude-bridge # 停止服务 systemctl --user stop openclaw-claude-bridge5.3 常见问题与排查技巧在实际部署和运行中你可能会遇到以下问题。这里提供一套排查思路问题一OpenClaw智能体无响应或返回“Provider Error”检查桥接器服务状态首先确认npm start进程是否在运行或systemd/launchd服务是否处于active (running)状态。运行curl http://localhost:3456/health看是否返回ok。检查OpenClaw配置确认openclaw.json中baseUrl的端口默认3456与桥接器启动端口一致。确认模型id拼写正确。检查网络连接如果OpenClaw和桥接器不在同一台机器确保防火墙放行了3456端口的访问但出于安全考虑建议部署在同一台机器桥接器API端口只绑定localhost。查看桥接器日志在终端或bridge.log文件中查看是否有错误输出。常见的错误包括Claude CLI未找到、认证失败等。问题二Claude CLI进程启动失败或立即退出验证CLI安装与登录在终端直接运行claude --version和claude auth status。确保CLI在运行桥接器的用户环境下已正确安装并登录。检查环境变量桥接器进程是否继承了正确的PATH对于systemd服务有时需要在全路径下指定claude二进制文件或在服务文件中设置EnvironmentPATH...。查看详细错误桥接器在启动CLI子进程失败时会在日志中打印stderr输出。这通常是权限问题或CLI自身错误。问题三工具调用不工作Claude回复“我不知道如何使用这个工具”检查工具协议注入在仪表盘的“实时活动流”中查看请求事件。是否能看到“工具协议已注入”相关的日志如果没有说明请求中可能没有携带tools数组或者桥接器的tools.js模块解析失败。检查OpenClaw Gateway工具的实际执行由OpenClaw Gateway负责。确认Gateway服务端口18789正在运行并且智能体配置的工具在Gateway中已正确注册和启用。查看Claude的输出在仪表盘展开有问题的请求详情查看原始的活动日志。有时Claude可能输出了不符合预期格式的XML导致解析失败。这可能需要调整工具描述的提示词。问题四会话记忆似乎丢失了确认会话路由键记忆是基于channel_id agent_name的。如果你更改了智能体的名称或者频道ID发生了变化例如在开发测试中频繁创建/删除频道就会创建一个全新的会话。检查state.json文件查看项目根目录下的state.json文件。里面是否保存了你期望的会话记录文件权限是否正确桥接器进程有读写权限检查CLI会话文件Claude CLI的会话文件默认在~/.config/claude/sessions/目录下。查看是否存在与state.json中session ID对应的文件。如果文件丢失记忆就无法恢复。查看恢复方式在仪表盘的请求表中“恢复方式”列会显示每个请求是如何处理的。New表示创建了新会话Resume表示恢复了旧会话。如果本该恢复的会话却显示New说明会话查找失败了。问题五性能缓慢或请求超时监控并发数查看仪表盘顶部的“活跃请求数”。如果接近或达到MAX_GLOBAL限制新的请求会被排队。考虑根据服务器配置适当调高该值但注意每个Claude CLI进程都会消耗显著的内存和CPU。检查思考级别reasoning_effort设置为high或xhigh会显著增加Claude的响应时间。对于不需要深度推理的简单对话可以设置为low或不设置关闭思考。查看CLI进程资源占用使用top或htop命令查看claude进程的CPU和内存使用情况。处理复杂请求时Claude模型尤其是Opus可能非常消耗资源。网络问题如果Claude CLI需要联网访问API取决于你的CLI配置网络延迟也会影响速度。确保服务器网络通畅。问题六仪表盘无法访问或白屏检查端口绑定确认桥接器启动日志中显示Dashboard server listening on port 3458。检查防火墙如果从局域网其他机器访问确保服务器防火墙放行了3458端口例如sudo ufw allow 3458。检查前端构建如果仪表盘是白屏打开浏览器开发者工具F12查看控制台Console是否有JavaScript错误。可能是前端资源未正确构建。尝试进入dashboard/目录重新运行npm run build。Basic认证问题如果你设置了DASHBOARD_PASS但忘记了密码只能通过修改.env文件并重启服务来重置。