MetaBot：用飞书远程操控 Claude Code

前言

Claude Code 是 Anthropic 官方推出的 AI 编程助手，能在终端中直接理解代码、执行命令、完成开发任务。但它有一个明显的限制——必须坐在电脑前打开终端才能使用。

MetaBot 就是为了打破这个限制而生的开源项目。它作为一个桥接服务，将 Claude Code 的能力延伸到飞书（Feishu/Lark）聊天中。无论你在通勤路上还是出差途中，都能通过手机发消息让 Claude Code 为你干活。

本文将完整记录 MetaBot 的搭建全过程，并深入解析它的工作原理与技术架构，希望能帮助有同样需求的读者快速上手。

适用读者：有一定编程基础的开发者，熟悉 Node.js 环境搭建，需要一个能随时随地使用的 AI 编程助手。

---

什么是 MetaBot？

MetaBot 是一个桥接服务（Bridge Service），它的核心作用是在两个系统之间建立通信通道：

• 前端：飞书（Feishu/Lark）——你在手机上聊天的 IM 工具
• 后端：Claude Code（或其他 AI 引擎）——运行在你电脑上的 AI 编程助手

你 → 飞书 → MetaBot → Claude Code → 你的电脑

工作流程如下：你在飞书发送一条消息，MetaBot 收到后将其转发给 Claude Code，Claude Code 执行任务后将结果返回，MetaBot 再推送回飞书。整个过程采用实时流式传输，你可以在手机上看到 Claude 一步步思考、编写代码、执行命令的全过程。

项目地址：https://github.com/xvirobotics/metabot

---

技术架构

整体架构

MetaBot 是 TypeScript 写的 Node.js 应用（ESM 模块）。核心模块如下：

src/
├── index.ts                 # 入口：创建飞书客户端、启动服务
├── config.ts                # 配置加载 (dotenv加载.env)
├── feishu/
│   ├── event-handler.ts     # 接收飞书消息，解析 @提及
│   ├── card-builder.ts      # 构建飞书交互卡片 (彩色卡片显示Claude回复)
│   ├── message-sender.ts    # 发送/更新卡片、上传图片文件
│   └── doc-reader.ts        # 读取飞书文档
├── bridge/
│   ├── message-bridge.ts    # 核心编排器：路由消息、管理会话
│   ├── outputs-manager.ts   # 管理Claude产出的文件
│   ├── rate-limiter.ts      # 限流(飞书API有频率限制)
│   └── command-handler.ts   # 处理 /reset /stop 等命令
├── engines/
│   ├── claude/executor.ts   # Claude引擎：通过SDK启动claude子进程
│   ├── kimi/executor.ts     # Kimi引擎
│   ├── codex/executor.ts    # Codex引擎
│   └── stream-processor.ts  # 解析SDK流式输出 → 卡片状态
├── api/
│   ├── peer-manager.ts      # 多实例发现、任务转发
│   ├── voice-handler.ts     # 语音接口 (STT + TTS)
│   └── http-server.ts       # HTTP API 服务
├── memory/                  # MetaMemory知识库集成
├── sync/                    # 飞书Wiki同步
├── web/                     # Web UI (React SPA)
└── scheduler/               # 定时任务

消息流转过程

飞书消息 → WebSocket长连接
    ↓
EventHandler (解析文本/图片, 去掉@提及, 判断群聊/私聊)
    ↓
MessageBridge (路由判断)
    ├─ 命令 → 直接处理 (/reset, /stop, /memory等)
    ├─ 对话 → ClaudeExecutor
    │       ↓
    │   claude-agent-sdk (官方SDK)
    │       ↓
    │   spawn claude.exe (子进程)
    │       ↓
    │   Claude推理 → 使用工具(读文件/写代码/执行命令)
    │       ↓
    │   流式输出 (stream-json格式)
    │       ↓
    │   StreamProcessor (解析流 → CardState)
    │       ↓
    │   CardBuilder (构建飞书卡片JSON)
    │       ↓
    │   MessageSender (推送到飞书)
    │       ↓
    你手机看到实时回复

关键设计决策

特性	说明
WebSocket 长连接	不需要公网 IP，MetaBot 主动连飞书服务器，适合内网环境
BypassPermission 模式	因为终端没有交互式审批，使用 --dangerously-skip-permissions 跳过工具调用审批
会话隔离	每个聊天（chatId）有独立 Claude session，群聊/私聊互不干扰
2人小群 = 私聊	群聊只有2个成员（1人+1bot）时自动当私聊处理，无需@提及
流式卡片	飞书卡片会实时更新：蓝色=思考中，绿色=完成，红色=报错
文件输出	Claude 生成的图片/文件自动扫描并上传到飞书

---

安装过程实录

环境准备

我的环境：

• OS：Windows 11 中文版
• Node.js：24.15.0（已安装）
• PM2：进程管理器，让 MetaBot 在后台常驻运行（已安装）
• Git：E:\software_tool\tool_software\Git\（v2.45.2.windows.1，已安装）
• Claude Code CLI：@anthropic-ai/claude-code（通过 npm 全局安装）
• AI 提供商：DeepSeek（第三方 Claude 兼容 API）
• 飞书机器人：用于消息收发

第一步：获取 DeepSeek API Key

MetaBot 底层调用 Claude Code，而 Claude Code 可以使用兼容 Anthropic API 格式的第三方提供商。这里选择 DeepSeek：

1. 访问 DeepSeek 开发者平台
2. 注册账号，进入控制台 → 「API Keys」 → 「Create new secret key」
3. 复制生成的密钥（格式：sk-...）

DeepSeek 新用户完成实名认证后可获得约 100 万 tokens 免费额度，有效期 180 天。

第二步：配置 Claude Code 使用 DeepSeek

Claude Code 的配置文件位于 ~/.claude/settings.json，在里面配置 DeepSeek 的第三方 API：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的key",
    "ANTHROPIC_MODEL": "deepseek-v4-flash"
  }
}

配置完成后，在终端验证：

claude -p "hello，用中文回复"

如果能正常回复，说明 Claude Code + DeepSeek 的链路已经通了。这是后续一切的基础。也可以使用CC-Switch配置，但这并不是这篇文章的重点

第三步：一键安装 MetaBot

MetaBot 提供了一键安装脚本（PowerShell），不需要手动克隆仓库和安装依赖：

$env:METABOT_HOME="E:\software_tool\tool_AI\metabot"
irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex

安装脚本会自动完成以下操作：

阶段	操作	状态
环境检查	检测 Git、Node.js、npm	✅ 全部通过
克隆仓库	从 GitHub 拉取 MetaBot 代码（~14MB）	✅
安装依赖	npm install，402 个包	✅
生成配置	交互式填写飞书凭证、工作目录等	⚠️ 部分成功
安装 Skills	metaskill、metamemory、metabot 等安装到 Claude	✅
启动服务	通过 PM2 启动 MetaBot 后台进程	✅

⚠️ 注意事项：

• 自动安装过程中需要从 GitHub 克隆仓库，国内网络可能出现访问失败的情况。建议提前准备 GitHub 加速工具（如 Steam++ 或代理）。
• 安装时需要配置 MetaBot 安装路径和 Claude Code 工作目录，安装路径不能是已存在的文件夹。
• 官方安装文档（更详细）：MetaBot 官方指南

交互式配置过程

安装脚本会依次询问以下信息：

1. 工作目录：Claude Code 的项目工作目录 → D:\Users\Aeonio\lisihan\AIworkspace\metabot-workspace
2. 认证方式：选择 Claude Code Subscription（OAuth）或第三方 API → 这里用第三方 API，但安装后通过 .env 配置
3. IM 平台：选择「飞书」
4. 飞书凭证：填写 App ID（cli_aa8b834a93fa5cd8）和 App Secret
5. 机器人名称：命名为 claudecode-bot

第四步：创建飞书应用

在飞书开发者后台创建应用（安装脚本中已填写凭证的应用）：

1. 创建自定义应用，填写名称和描述
2. 开启机器人功能
3. 配置权限：im:message、im:resource、im:chat:readonly
4. 事件订阅方式选择 长连接（WebSocket）——这里务必选择"长连接"而非"HTTP 回调"，因为 MetaBot 是通过 WebSocket 接收消息的
5. 订阅 im.message.receive_v1 事件
6. 发布应用（创建版本 → 审核通过后上线）
   官方文档参考：https://xvirobotics.com/metabot/zh/getting-started/feishu-app-setup/

第五步：验证与启动

安装完成后，PM2 会自动启动 MetaBot。可以通过以下命令管理：

pm2 status              # 查看进程状态
pm2 logs metabot        # 查看实时日志
pm2 restart metabot     # 重启
pm2 stop metabot        # 停止

也可用开发模式前台运行（方便调试）：

cd E:\software_tool\tool_AI\metabot
npm run dev

遇到的问题和修复

整个安装过程并不是一帆风顺的，我遇到了三个需要手动修复的问题。

问题 1：bots.json 为空文件（安装脚本 Bug）

bots.json 是 MetaBot 的机器人配置文件，存放在安装根目录下（\bots.json，与 .env 同级）。它定义了一组飞书/Telegram 机器人的凭证和运行参数——包括机器人名称、App ID、App Secret、工作目录、并发数等。

安装完成后，PM2 显示 MetaBot 一直在反复重启（status: waiting restart，已重启 10 次）。

排查日志发现：安装脚本 Phase 5 生成 bots.json 时出现了 JSON 序列化错误：

SyntaxError: Expected property name or '}' in JSON at position 10

结果 bots.json 被写成了 0 字节的空文件。loadAppConfig() 解析空文件直接抛出异常，进程崩溃退出，PM2 不断重启又不断失败。

解决：手动创建正确的 bots.json：

{
  "feishuBots": [
    {
      "name": "claudecode-bot",
      "description": "Claude Code AI assistant via Feishu",
      "feishuAppId": "cli_aa8b834a93fa5cd8",
      "feishuAppSecret": "你的App Secret",
      "defaultWorkingDirectory": "D:\\Users\\Aeonio\\lisihan\\AIworkspace\\metabot-workspace",
      "maxConcurrentTasks": 3,
      "budgetLimitDaily": 5.0
    }
  ]
}

修复后重启，MetaBot 正常启动。

问题 2：Claude Code process exited with code 1

MetaBot 启动成功，飞书也连接上了（日志显示 Feishu bot is running），但发消息给机器人后报错：

Error: Claude Code process exited with code 1

原因是两件事：

1. 执行路径配错了：安装脚本把 CLAUDE_EXECUTABLE_PATH 设成了 claude.ps1（PowerShell 脚本），但 Node.js 的子进程 spawn 不能直接执行 .ps1 文件。Windows 上需要用 .cmd 文件或 .exe。

2. DeepSeek 配置没传给 Claude：.env 中缺少 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 这三项。MetaBot 启动 Claude 子进程时需要这些环境变量来使用 DeepSeek 的 API。

解决：修改 .env 文件：

# 修复：claude.ps1 → claude.cmd
CLAUDE_EXECUTABLE_PATH=C:\Users\31707\AppData\Roaming\npm\claude.cmd

# 新增：DeepSeek 第三方提供商配置（传给 Claude 子进程）
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_AUTH_TOKEN=sk-你的key
ANTHROPIC_MODEL=deepseek-v4-flash

问题 3：端口冲突（EADDRINUSE）

在调试过程中，先通过 PM2 后台启动了 MetaBot，然后又手动运行 npm run dev。两个进程抢同一个端口：

Error: listen EADDRINUSE: address already in use 0.0.0.0:9100

原因：PM2 进程和 npm run dev 进程同时运行，都试图监听 9100（API）和 8100（MetaMemory）端口。

解决：二选一。如果 PM2 已在运行，就不用再 npm run dev；如果想前台调试，先 pm2 delete metabot 停掉 PM2 进程。

---

配置总结

最终有效的配置方案是：

.env（MetaBot 根目录）— 核心环境变量：

BOTS_CONFIG=./bots.json
API_PORT=9100
API_SECRET=生成的密钥

CLAUDE_EXECUTABLE_PATH=C:\Users\31707\AppData\Roaming\npm\claude.cmd
CLAUDE_DEFAULT_WORKING_DIRECTORY=D:\Users\Aeonio\lisihan\AIworkspace\metabot-workspace
CLAUDE_CODE_GIT_BASH_PATH=E:\software_tool\tool_software\Git\bin\bash.exe
LOG_LEVEL=info

# DeepSeek 第三方 API
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_AUTH_TOKEN=sk-你的key
ANTHROPIC_MODEL=deepseek-v4-flash

META_MEMORY_URL=http://localhost:8100

bots.json（MetaBot 根目录）— 飞书机器人配置：

{
  "feishuBots": [
    {
      "name": "claudecode-bot",
      "feishuAppId": "cli_aa8b834a93fa5cd8",
      "feishuAppSecret": "你的App Secret",
      "defaultWorkingDirectory": "D:\\Users\\Aeonio\\lisihan\\AIworkspace\\metabot-workspace",
      "maxConcurrentTasks": 3,
      "budgetLimitDaily": 5.0
    }
  ]
}

~/.claude/settings.json — Claude Code CLI 配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的key",
    "ANTHROPIC_MODEL": "deepseek-v4-flash"
  }
}

验证方法

全部配置完成后：

1. 确保 PM2 运行中：pm2 status → 显示 online
2. 在飞书中找到机器人 claudecode-bot，私聊发送消息
3. 观察日志：pm2 logs metabot
4. 正常响应链路：消息收到 → Claude 开始推理 → 流式输出 → 飞书卡片实时更新

最终效果

现在在飞书里和机器人对话，Claude 会实时响应：

1. 飞书收到消息 → 显示蓝色标题卡片（“思考中…”）
2. Claude 开始推理 → 卡片内容实时更新
3. Claude 使用工具（读文件、写代码等）→ 卡片显示工具调用列表
4. 任务完成 → 卡片变绿色，显示最终回复和统计（耗时、费用等）

---

为什么能用飞书操控电脑

这个问题的答案其实很简单：

MetaBot 只是一个代理，真正干活的是你电脑上的 Claude Code。

当你通过飞书发消息时：

1. MetaBot 收到消息，启动一个 claude.exe 子进程
2. 这个 claude.exe 运行在你的电脑上，拥有你电脑的完整访问权限
3. Claude 可以执行 Bash 命令、读写文件、调用 MCP 工具
4. 结果流式传回飞书

本质上，你只是在飞书里"远程操作"你电脑上的 Claude Code CLI。Claude Code 能做什么，飞书上的 bot 就能做什么。

安全考虑

• BypassPermission 模式：因为终端没有交互式审批，MetaBot 默认跳过工具调用确认。这意味着 Claude 可以自由执行命令——所以它信任你给它的 prompt
• 会话隔离：不同群聊/私聊有独立会话，不会互相干扰
• 单任务限制：每个聊天同时只能跑一个任务
• 超时保护：1小时无响应自动终止

---

演示

总结

MetaBot 以最简单直接的方式实现了"手机操控 AI 编程助手"这一需求。对于有自部署能力、希望随时随地使用 Claude Code 的开发者来说，它是一个非常实用的工具。

从搭建到使用，整个链路的核心优势在于：

优势	说明
零公网依赖	WebSocket 长连接，无需公网 IP 或服务器
成本极低	一台能跑 Node.js 的电脑 + 免费飞书账号即可
实时交互	流式卡片推送，手机上实时查看推理过程
第三方兼容	DeepSeek 等第三方 API 完美替代官方 Anthropic 订阅

最有价值的地方在于：将 Claude Code 从终端解放到了手机端。通勤路上、午休间隙，随时可以发一条消息让 Claude 干活，不必每次都打开电脑打开终端。

第三方 API + MetaBot 的组合，让 Claude Code 的使用门槛降到了最低——不需要 Anthropic 官方订阅，不需要公网服务器，只需要一台能跑 Node.js 的电脑和一个免费的飞书账号。

---

参考资源：

• MetaBot 项目地址：https://github.com/xvirobotics/metabot
• MetaBot 官方文档：https://xvirobotics.com/metabot/zh/
• DeepSeek 开发者平台：https://platform.deepseek.com/
• CCS（Claude Code Switch）：https://www.npmjs.com/package/@georgedong32/ccs

本文为个人实践记录，如有问题欢迎留言交流。