1. 项目概述:一个基于Claude Code的多平台AI助手网关

如果你和我一样,经常需要在Telegram、Discord、Slack和WhatsApp这些不同的聊天平台之间切换,同时希望有一个能记住上下文、能调用各种工具、还能处理定时任务的AI助手,那么OpenClaudeClaw这个项目绝对值得你花时间研究一下。简单来说,它是一个开源的、始终在后台运行的“网关”服务,能把Claude Code这个强大的AI编程助手,变成一个可以跨平台对话的智能体。

这个项目的核心价值在于“统一”和“增强”。它统一了你散落在各个聊天应用里的AI交互入口——你不再需要为每个平台单独配置机器人,或者在不同的AI服务之间跳转。你只需要跟一个“智能体”对话,而这个智能体背后是完整的Claude Code能力,包括代码解释、工具调用、MCP(模型上下文协议)集成以及对话记忆。更关键的是,它通过一个守护进程(Daemon)实现了“永远在线”,这意味着你可以像跟一个真人助手聊天一样,随时给它发消息、布置任务,它会在后台处理,甚至能按你自然语言描述的周期(比如“每天早上9点”)来提醒你。

我最初被它吸引,是因为厌倦了在命令行、网页聊天界面和各种零散的自动化脚本之间来回切换。OpenClaudeClaw把Claude Code变成了一个基础设施级别的服务,就像在你本地部署了一个私人的、全能的AI副驾,并且通过最常用的IM软件与你连接。这对于开发者、项目经理或者任何需要频繁处理信息、执行重复性数字任务的人来说,效率提升是显而易见的。

2. 核心架构与设计思路拆解

2.1 为什么是“网关”模式?

OpenClaudeClaw的设计精髓在于其“网关(Gateway)”架构。这并非一个简单的脚本或一次性运行的机器人,而是一个常驻的Node.js服务。这种设计带来了几个关键优势:

会话持久化与状态管理 :每个聊天对话(无论是与Telegram的某个用户,还是Discord的某个频道)都会被网关分配一个独立的、持久的会话(Session)。这个会话对象保存了与Claude Code交互的完整上下文历史。这意味着你可以中断对话几个小时甚至几天,回来接着说,AI依然记得之前的全部内容。这是通过项目中的 sessionManager.js 模块实现的,它负责将聊天平台ID映射到本地存储的会话文件上。

资源隔离与安全控制 :网关作为唯一的入口点,统一处理来自不同平台的身份验证(Auth)。例如,对于未知联系人发来的消息,网关会生成一个8位配对码,要求用户在本地CLI中手动批准( pair 命令)。这种设计确保了你的AI助手不会被陌生人随意调用。所有的授权逻辑(白名单、开放、配对三种策略)都集中在 auth.js 模块中,与具体的聊天平台实现解耦。

统一的任务调度中心 :网关内置了一个Cron调度器( cron.js )。当你在聊天中告诉Claude“每周一提醒我开会”,Claude可以通过网关暴露的HTTP API( POST /cron/create )创建一个定时任务。这个任务由网关的守护进程管理,到点触发,并将执行结果(比如一条提醒消息)发送回对应的聊天会话。这实现了一种“离线智能”,AI的承诺可以被可靠地执行。

2.2 核心工作流程解析

项目文档中的ASCII流程图非常直观,但我们可以更深入地拆解每一步:

  1. 消息接收 gateway.js 作为核心,加载并管理各个渠道模块( channels/ 目录下的 telegram.js , whatsapp.js 等)。这些模块使用各自平台的官方协议(Telegram Bot API的轮询、Discord的Gateway WebSocket)监听消息。
  2. 会话路由 :收到消息后,网关根据“平台+聊天ID”生成一个唯一键,从 SessionManager 中查找或创建对应的会话。会话中包含了模型选择、历史消息、以及可能正在执行的工具调用状态。
  3. 智能体调用 :这是最关键的一步。网关不会直接与AI模型的API对话,而是 生成(spawn)一个独立的Claude Code进程 。它通过命令行调用类似 claude -p “用户消息” --resume <会话文件路径> 的方式。这样做有几个深层原因:
    • 工具能力继承 :Claude Code进程天然具备所有已配置的工具(如文件操作、终端命令)和MCP服务器连接能力。网关无需重新实现这些复杂逻辑。
    • 进程隔离 :每个请求在一个独立的子进程中处理。即使某个对话中的Claude进程崩溃或卡死,也不会影响网关主进程和其他会话的稳定性。
    • 灵活性 :你可以使用全局安装的 claude 命令,也可以指向自己从源码构建的特定版本(通过配置 claudeBin 参数),方便调试和定制。
  4. 响应回传 :Claude Code进程执行完毕,将生成的文本(或语音)响应输出到标准输出(stdout)。网关捕获这个输出,再通过对应的渠道模块原路发送回用户。
  5. 状态保存 :Claude Code在 --resume 模式下会自动更新会话文件。网关确保这个更新后的会话被 SessionManager 正确持久化,供下次使用。

这种“网关调度 + 独立智能体进程”的模式,在灵活性和稳定性之间取得了很好的平衡。网关专注于网络、状态和调度,而最复杂的AI推理和工具使用则交给专业的Claude Code去处理。

2.3 技术栈选型背后的考量

  • Node.js + Bun :项目要求Node.js 22+和Bun 1.1+。Bun的快速启动和优秀的包管理性能,对于需要频繁生成子进程的场景(每个消息生成一个Claude进程)是有益的。同时,Node.js庞大的生态确保了集成各种聊天平台SDK的便利性。
  • 零依赖的核心网关 :项目自豪地宣称核心网关部分“Zero npm dependencies”。这意味着 gateway.js sessionManager.js 等核心模块只使用Node.js原生模块(如 child_process , fs , http )。这极大地提升了项目的可靠性和安全性,减少了依赖冲突和供应链攻击的风险。第三方依赖(如Baileys for WhatsApp)被严格隔离在渠道插件中。
  • 渠道集成策略
    • Telegram/Discord/Slack :均采用官方推荐的、无需维护长连接复杂状态的方案。Telegram用长轮询(Long Polling),Discord用Gateway,Slack用Socket Mode。这避免了自行维护WebSocket连接状态的心跳、重连等复杂性。
    • WhatsApp :通过Baileys库实现。这是一个逆向工程库,意味着它可能随着WhatsApp官方客户端更新而需要调整,但它是目前非官方集成中最稳定、功能最全的选择之一。项目将其单独列为依赖,也暗示了其潜在的不稳定性,用户需要知晓。
  • 配置管理 :使用 ~/.claude/gateway.json 单一配置文件,并支持热重载( config.js )。这种基于文件的方式,比环境变量更适合管理结构复杂的配置(如多个模型的API密钥、不同渠道的开关状态)。交互式的 onboard 命令( onboard.js )极大地简化了初始化配置的难度。

注意:关于“从源码构建” :项目文档中“Build Claude Code from source”这一步,对于大多数只想使用的用户来说其实 不是必须的 。如果你已经通过 npm install -g @anthropic-ai/claude 等方式安装了官方的Claude CLI,网关默认就会使用它。从源码构建主要适用于想要体验最新、未发布特性,或需要对Claude Code本身进行修改的开发者。

3. 详细部署与配置实操指南

3.1 环境准备与项目初始化

假设你在一台macOS或Linux开发机上操作(Windows可通过WSL2获得类似体验)。

第一步:安装基础运行时

# 确保Node.js版本 >= 22.x
node --version
# 如果版本过低,建议使用nvm进行版本管理
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

# 安装Bun (版本 >= 1.1)
# 官方安装脚本
curl -fsSL https://bun.sh/install | bash
# 安装后,根据提示将Bun添加到PATH,或重启终端
bun --version

第二步:克隆项目并安装依赖

git clone https://github.com/composio-community/openclaudeclaw.git
cd openclaudeclaw
# 使用npm或bun安装依赖均可,项目声明了Bun但package.json通常兼容npm
npm install
# 将openclaudeclaw命令链接到全局,方便在任何目录调用
npm link

执行 npm link 后,你可以在终端任何位置直接输入 openclaudeclaw 命令。你可以用 which openclaudeclaw 验证是否成功。

第三步:(可选)构建Claude Code 如果你没有安装官方Claude CLI,或者想使用特定版本,才需要这一步。

npm run build

这个过程会从Anthropic的仓库克隆Claude Code源码并编译,第一次运行可能需要几分钟,取决于网络和机器性能。完成后会在 dist/ 目录下生成 cli.js 文件。你可以验证:

node dist/cli.js --version
node dist/cli.js login # 这会打开浏览器,完成Anthropic账户认证

3.2 交互式配置向导详解

核心配置命令是 openclaudeclaw onboard 。这是一个交互式菜单,会引导你完成所有设置。我强烈建议第一次使用时完整走一遍这个流程。

openclaudeclaw onboard

运行后,你会看到一个终端菜单,通常包含以下部分:

  1. 渠道配置

    • Telegram :你需要先通过 @BotFather 创建一个新的Bot,获取 botToken 。在菜单中输入这个Token即可。 dmPolicy (私聊策略)建议新手保持默认的 pairing (需要配对码)。
    • WhatsApp :选择启用后,首次运行网关时,终端会显示一个二维码。用你的WhatsApp手机客户端扫描此二维码即可链接。这里依赖 Baileys 库,请注意其使用条款。
    • Discord :你需要去 Discord开发者门户 创建一个Application,再在其下创建一个Bot,获取 botToken 。同样,在菜单中输入。
    • Slack :配置稍复杂。需要创建一个Slack App,启用 Socket Mode 以获得 appToken ,并为Bot分配 chat:write 等权限范围(Scopes)来获取 botToken 。两个Token都需要在菜单中输入。
  2. 模型配置

    • Anthropic(默认) :如果你已经用 claude login 登录,这里会自动使用你的认证。你可以选择默认模型(如sonnet)。
    • 其他提供商(OpenAI, DeepSeek, Qwen等) :你需要提供对应服务的API Key和Base URL(如果使用第三方代理)。菜单会引导你逐一添加。
  3. Composio集成 :如果你想使用其上千种工具(连接GitHub、Notion等),这里会引导你登录Composio账户并完成OAuth授权。这是一个强大的扩展,但非必需。

  4. 语音功能 :如果你想支持Telegram语音消息转文字(STT)或文字转语音回复(TTS),需要确保系统已安装 ffmpeg whisper (可通过 pip install openai-whisper 安装)。在菜单中启用即可。

配置完成后,所有信息会保存到 ~/.claude/gateway.json 。你可以随时再次运行 openclaudeclaw onboard openclaudeclaw onboard telegram 来修改某一项配置。

3.3 启动网关与守护进程管理

配置完成后,你可以选择两种运行方式:

方式一:前台运行(用于测试和调试)

openclaudeclaw gateway start

终端会保持在前台,并打印出详细的连接和消息处理日志。这是排查问题的最佳方式。按 Ctrl+C 可停止服务。

方式二:后台守护进程(用于生产环境,保持始终在线)

openclaudeclaw gateway install-daemon

这个命令会根据你的操作系统,安装一个后台服务:

  • macOS :会在 ~/Library/LaunchAgents/ 下创建一个 com.openclaudeclaw.gateway.plist 文件,并加载到 launchd 。它会随用户登录自动启动,并在崩溃后尝试重启。
  • Linux(使用systemd的系统) :会在 ~/.config/systemd/user/ 下创建一个 openclaudeclaw-gateway.service 文件,并启用这个用户级服务。

安装后,守护进程会自动启动。你可以使用以下命令管理:

# 查看网关状态
openclaudeclaw gateway status

# 停止守护进程(但服务配置仍在,下次开机或手动会启动)
openclaudeclaw gateway stop

# 彻底卸载守护进程(从启动项中移除)
openclaudeclaw gateway uninstall-daemon

一个关键的实操细节:更新代码后重启守护进程 如果你通过 git pull 更新了项目代码,需要重启守护进程以使新代码生效。

# macOS
launchctl unload ~/Library/LaunchAgents/com.openclaudeclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/com.openclaudeclaw.gateway.plist

# Linux (systemd user mode)
systemctl --user restart openclaudeclaw-gateway

3.4 配对与首次对话

假设你已经配置好了Telegram Bot并启动了网关(无论是前台还是后台)。

  1. 在Telegram中找到你的Bot,发送任意一条消息(如“hello”)。
  2. 此时,因为你的账号不在白名单且策略是 pairing ,Bot不会直接回复你。相反, 网关会在终端日志(如果前台运行)或系统日志中,生成一个8位的配对码
  3. 在终端中执行配对命令:
    openclaudeclaw pair ABCD1234 # 将ABCD1234替换为实际的配对码
    
  4. 配对成功后,Bot会立即回复你刚才的消息。此后,在这个聊天中的对话将不再需要配对。

你可以随时查看待处理的配对请求:

openclaudeclaw pairs

或者查看所有活跃的会话:

openclaudeclaw sessions

4. 高级功能与深度使用技巧

4.1 多模型切换与混用策略

OpenClaudeClaw支持在对话中无缝切换模型,这是其一大亮点。你可以通过 /model 命令来实现。

  • /model :列出所有已配置的可用模型及其提供商。
  • /model opus :将会话的默认模型切换到Claude Opus。
  • /model gpt-4o :切换到OpenAI的GPT-4o(假设你已配置)。

背后的原理 :当你切换模型时,网关会更新当前会话的配置。下一次你发送消息时,网关会根据新模型选择不同的调用策略:

  • 如果是Anthropic模型,则使用 claude CLI,享受完整的工具链。
  • 如果是其他OpenAI兼容API的模型(如GPT、DeepSeek),网关会直接向对应的API端点发送Chat Completion请求,格式化为与Claude Code类似的会话历史。

使用技巧:根据任务类型选择模型

  • 复杂推理与编程 :切换到 opus sonnet ,利用Claude最强的代码和推理能力。
  • 快速聊天与摘要 :切换到 haiku gpt-3.5-turbo ,响应更快,成本更低。
  • 本地隐私任务 :配置Ollama,切换到本地模型如 llama3.2 ,数据完全不出境。
  • 需要最新知识 :某些第三方聚合平台(如OpenRouter)提供的模型可能知识更新,可以临时切换。

4.2 利用Composio解锁千种外部工具

Composio的集成将Claude的能力从本地扩展到了整个互联网。配置成功后,Claude可以直接调用工具。

典型工作流

  1. 你在Telegram中对Bot说:“帮我看看composio-community/openclaudeclaw这个仓库最新的3个PR是什么状态。”
  2. Claude Code识别出这个请求需要调用GitHub工具。由于网关配置了Composio,Claude会通过MCP协议向本地的Composio MCP服务器发送请求。
  3. Composio MCP服务器处理OAuth(如果你已授权)和API调用,从GitHub获取数据。
  4. 数据返回给Claude,Claude组织成自然语言回复给你。

配置要点

  • onboard 菜单中启用Composio后,首次使用需要授权。Claude会引导你完成一个OAuth流程,通常在终端会弹出授权链接。
  • 你可以在Composio网页控制台精细管理每个工具集的权限(Scopes)。
  • 注意API调用频率和成本,尤其是那些调用第三方付费API的工具。

4.3 持久化定时任务(Cron Jobs)

这是将AI从“聊天机器人”升级为“个人自动化助理”的关键功能。

如何创建 :直接用自然语言告诉Claude。

“从明天开始,每个工作日的下午5点,在Discord的#daily频道里提醒大家写日报。” “每周一早上9点,检查我的日历,把当天的第一个会议主题摘要发到我的Telegram私聊。”

底层机制

  1. Claude理解你的指令后,会通过网关暴露的HTTP API ( POST /cron/create ) 创建一个定时任务记录。
  2. 这个任务被持久化到文件系统中(与会话存储类似)。
  3. 网关内部的Cron调度器( cron.js )在后台运行,检查是否有到期的任务。
  4. 任务触发时,网关会 重新生成一个Claude Code进程 ,并将任务描述作为输入。Claude执行后,结果会通过网关发送到你指定的聊天渠道。

管理任务

# 通过CLI查看当前所有定时任务(需要网关HTTP API运行)
curl http://127.0.0.1:18789/cron/list

你也可以通过HTTP API来删除任务。任务信息同样保存在 ~/.claude/ 目录下,便于备份。

4.4 语音消息处理管道

语音功能为Telegram渠道增添了实用性。

工作流程

  1. 用户在Telegram中发送一条语音消息。
  2. telegram.js 渠道处理器收到语音文件,将其下载到临时目录。
  3. voice.js 模块被调用。它首先使用 ffmpeg 将语音文件(可能是ogg、m4a格式)转换为Whisper模型需要的wav格式。
  4. 然后调用本地安装的 whisper 命令行工具(或库)进行语音识别(STT),将结果转为文本。
  5. 文本被送入Claude处理。
  6. (可选)如果配置中 replyWithVoice true ,Claude的文本回复会通过macOS的 say 命令(或其他TTS引擎)合成语音,并发送回Telegram。

性能与精度考量

  • 速度 :语音转文本是主要耗时环节,取决于语音长度和机器性能。初次使用Whisper需要下载模型(默认是 base 模型),也可能较慢。
  • 精度 :Whisper的识别精度很高,但对于专业术语或嘈杂环境仍有出错可能。Claude的上下文理解能力有时可以纠正一些小的识别错误。
  • 依赖 :确保 ffmpeg whisper 在系统PATH中可访问。 whisper 的安装务必成功,可以通过在终端运行 whisper --help 测试。

5. 故障排除与性能优化实战记录

5.1 常见问题与解决方案速查表

问题现象 可能原因 排查步骤与解决方案
openclaudeclaw 命令未找到 npm link 未成功或全局node_modules路径不在PATH中 1. 在项目根目录重新运行 npm link
2. 检查 which openclaudeclaw 输出路径是否在PATH中。
3. 尝试使用绝对路径运行: node /path/to/project/gateway/cli.js
网关启动失败,端口被占用 默认端口18789已被其他程序使用 1. 修改 ~/.claude/gateway.json 中的 gateway.port 为其他值(如18790)。
2. 杀死占用端口的进程:`lsof -ti:18789
守护进程安装成功但未启动 launchd/systemd服务配置文件有误或权限问题 1. macOS : launchctl list | grep openclaudeclaw 查看状态, launchctl error <code> 查错误码。检查plist文件语法( plutil ~/Library/LaunchAgents/com.openclaudeclaw.gateway.plist )。
2. Linux : systemctl --user status openclaudeclaw-gateway 查看详细错误日志。常见问题是 .service 文件中 WorkingDirectory ExecStart 路径错误。
Claude处理消息无响应或超时 Claude CLI进程卡住、网络问题或模型API故障 1. 在前台模式( gateway start )下观察日志,看Claude进程是否被生成以及是否有错误输出。
2. 测试Claude CLI本身: claude -p “hello” 看是否正常响应。
3. 检查Anthropic或其他模型API的密钥是否有效、额度是否充足。
配对码不出现或配对失败 网关未收到消息、认证策略配置错误、配对码过期 1. 确认网关正在运行( gateway status )。
2. 确认渠道配置正确(Bot Token无误)。
3. 检查 dmPolicy 设置。如果是 allowlist ,需要预先在配置文件中添加用户ID。
4. 配对码有一定有效期,超时后需要重新发送消息生成新码。
语音消息无法识别 ffmpeg或whisper未安装、路径问题、语音文件格式不支持 1. 在终端分别运行 ffmpeg -version whisper --help 确认安装。
2. 查看网关日志(前台模式),通常会有详细的错误信息。
3. 尝试手动转换一个语音文件测试: ffmpeg -i input.ogg output.wav
Composio工具调用失败 OAuth未授权、工具权限不足、Composio服务连接问题 1. 在聊天中尝试让Claude调用一个简单工具(如“获取时间”),Claude通常会返回具体的错误信息。
2. 前往Composio控制台,检查对应工具集的连接状态和授权是否有效。
3. 检查网络连接,Composio服务器可能在海外。

5.2 性能调优与资源管理

会话存储优化 :默认情况下,每个会话的历史记录都保存在 ~/.claude/sessions/ 目录下的JSON文件中。长时间使用后,文件可能变大,影响读取速度。

  • 定期清理 :可以手动删除不再需要的会话文件,或编写脚本定期清理超过一定天数的会话。
  • 调整 maxTurns :在 gateway.json agent 部分,设置 ”maxTurns”: 20 (默认可能是50或更高)。这限制了单次会话保留的对话轮数,防止历史记录无限增长。Claude Code本身有上下文窗口限制,过长的历史也可能影响其性能。

网关进程资源监控 :网关本身是轻量级的,但每个Claude Code进程会消耗较多内存和CPU。

  • 使用 htop 或系统监控工具,观察 claude 子进程的数量和资源占用。如果发现大量僵尸进程或内存泄漏,可以考虑定期重启网关守护进程。
  • 对于低配VPS,谨慎使用 opus 等大型模型,它们消耗资源更多。可以将会话默认模型设为 haiku

网络与稳定性

  • 代理配置 :如果你的环境需要网络代理才能访问OpenAI或Anthropic的API,需要确保Node.js进程能使用代理。可以设置环境变量 HTTP_PROXY HTTPS_PROXY ,或者在启动网关前设置。
    export HTTPS_PROXY=http://your-proxy:port
    openclaudeclaw gateway start
    
  • 重试机制 :网关本身对渠道连接(如Telegram轮询)有基本的重试,但对于模型API调用失败,目前主要依赖Claude CLI自身的逻辑。对于关键任务,可以考虑在更高层级(如使用systemd的 Restart=on-failure )实现重启。

5.3 安全加固建议

  1. 最小化暴露 :网关的HTTP API(默认 127.0.0.1:18789 )只监听在本地回环地址,这是正确的。切勿将其端口暴露到公网。
  2. 谨慎使用 dmPolicy
    • pairing (默认):最安全,适合个人或小团队使用。
    • allowlist :适合固定成员使用,需预先在配置文件中添加用户的平台ID(如Telegram的 user_id )。
    • open 极度危险 ,任何知道Bot信息的人都可以与之对话并调用AI能力(可能产生费用)和工具(可能有数据安全风险)。除非在完全受控的私有环境中测试,否则不要使用。
  3. API密钥管理 gateway.json 中存储了所有模型的API密钥。确保该文件的权限设置为仅当前用户可读( chmod 600 ~/.claude/gateway.json )。
  4. 定期审查Composio授权 :定期登录Composio控制台,检查已授权的工具和连接,撤销不再需要的授权。
  5. 守护进程用户 :确保守护进程以非root的普通用户身份运行。 launchd systemd --user 默认就是如此,这是最佳实践。

6. 扩展思路与自定义开发

OpenClaudeClaw的模块化设计使其易于扩展。如果你有新的聊天平台需要集成,或者想增加新的功能模块,可以遵循其模式进行开发。

添加一个新的聊天渠道

  1. gateway/channels/ 目录下创建一个新的文件,例如 matrix.js
  2. 该模块需要导出一个符合接口的类,至少包含 init(client) start() stop() sendMessage(chatId, text) 等方法。可以参考 telegram.js 的实现。
  3. gateway.js 的核心代码中,找到渠道加载的部分,将你的新渠道像其他渠道一样导入和初始化。
  4. onboard.js 的交互菜单中,添加对新渠道的配置选项。
  5. 更新 gateway.json 的配置结构,包含新渠道的配置字段。

自定义模型提供商

  1. gateway.js 中,找到模型调用分发逻辑。目前主要分两类:Anthropic(调用CLI)和其他(调用OpenAI格式API)。
  2. 如果你要接入一个全新的、非OpenAI兼容的API,需要在此处添加一个新的处理分支,实现相应的HTTP请求和响应解析逻辑。

修改会话存储 :默认使用文件系统存储会话。如果你需要将会话存入数据库(如Redis,用于多实例部署),可以修改 sessionManager.js 模块,将 loadSession saveSession 方法的实现改为读写数据库。

一个实用的自定义案例:添加消息推送渠道 除了接收消息,你还可以让网关主动推送信息。例如,你可以创建一个简单的HTTP端点,接收外部系统的Webhook,然后让网关将这个通知通过已连接的聊天渠道(比如你的Telegram私聊)发送给你。这需要你在网关的HTTP API( gateway.js 中定义的路由)中添加一个新的端点,并在该端点处理函数中调用现有渠道的 sendMessage 方法。

这个项目提供了一个坚实的、生产可用的基础框架。将它作为你的数字生活与强大AI模型之间的智能管道,通过不断的调优和自定义,它能够演化成真正贴合你个人工作流的、不可替代的助手。

Logo

欢迎加入DeepSeek 技术社区。在这里,你可以找到志同道合的朋友,共同探索AI技术的奥秘。

更多推荐