xvirobotics/metabot

支持 Claude Code、Kimi Code 和 Codex CLI 三大引擎 — 订阅 / API Key 任你选，每个 Bot 可独立选引擎。

git clone https://github.com/xvirobotics/metabot.git ~/metabot
cd ~/metabot && bash install.sh

安装器引导一切：工作目录 → 引擎选择（Claude / Kimi / Codex） → 订阅登录 → IM 平台 → PM2 自动启动。5 分钟上手。

自定义安装目录（默认 ~/metabot）：把 ~/metabot 换成你想要的路径即可，或 METABOT_HOME=/opt/metabot bash install.sh。Windows: .\install.ps1 -Dir C:\opt\metabot。

也可以一行直装：curl -fsSL https://raw.githubusercontent.com/xvirobotics/metabot/main/install.sh | bash。

---

🔑 自托管 & 鉴权（个人版）

MetaBot 开箱即是可自托管的个人版：本地跑、单 token 鉴权、不依赖任何 SSO / 企业登录。

• 本地优先：metabot-core 默认只监听 http://localhost:9200，首次启动自动生成本地 API token（写入 ~/.metabot-core/token）。CLI 与 Web 控制台都用它鉴权。数据默认落在 ~/.metabot-core/。
• 无需 SSO：不需要 OAuth / OIDC / 企业 VPN。要多人或公网访问时，自行在前面挂一个反向代理（可选 oauth2-proxy）即可，应用层不强制。
• 分发端点默认上锁：/cli/*、/install/* 安装分发端点默认需要 token；确认你的构建不含密钥后，可设 METABOT_PUBLIC_DISTRIBUTION=1 放开匿名下载。

---

三引擎：Claude Code ✕ Kimi Code ✕ Codex CLI 并列一等支持

MetaBot 不是只绑定一家 — 三大顶级 AI 编码 Agent 都内置原生支持，你的订阅直接用。

配置只需一行 — 每个 Bot 独立选引擎：

{ "name": "bulma", "engine": "kimi",   "kimi": { "thinking": true } }
{ "name": "goku",  "engine": "claude" }
{ "name": "vegeta", "engine": "codex", "codex": { "model": "gpt-5.4-codex" } }

Codex 支持通过本机 codex exec --json CLI 接入，并使用 codex exec resume 续接聊天会话。启动 MetaBot 前，请先执行 codex login 或配置好 Codex API key/profile。MetaBot 会把飞书侧的 / ... 调用统一转成 Codex 的 $ ... 显式技能调用（例如安装了 /metaschedule 后，Codex 会收到 $metaschedule ...）。

Codex 迁移：复用 .claude 配置

Claude/Kimi 和 Codex 的发现路径不同。MetaBot 安装、更新和 Skill Hub 安装时会自动镜像内置 skills：

已有项目可以直接让 Codex 帮你迁移：

/model codex
请根据当前项目的 .claude 配置，为 Codex 创建对应的 .codex/skills 和 AGENTS.md：
- 把 .claude/skills/* 镜像到 .codex/skills/*
- 根据 CLAUDE.md 生成或更新 AGENTS.md
- 如果存在 .claude/agents/*.md，把这些 subagent 的角色、路由表和工作流整合进 AGENTS.md

如果你的宿主机禁用了 unprivileged user namespace，Codex CLI 的 workspace-write sandbox 可能在命令执行前报 bwrap: No permissions to create a new namespace。MetaBot 的 Codex 默认改用 danger-full-access 避开这个问题；需要更强隔离时可以通过 CODEX_SANDBOX 或 codex.sandbox 显式覆盖。

前端 Bot 用 Claude、后端 Bot 用 Kimi？完全可以。Agent 总线让它们互相委派任务，对面跑什么引擎对调用方透明。

---

你能用它做什么

• 手机写代码 — 地铁上用飞书给 Claude Code / Kimi Code / Codex CLI 发消息，它帮你改 bug、提 PR、跑测试
• 多 Agent 协作 — 前端 Bot、后端 Bot、运维 Bot，各自独立工作空间（甚至独立引擎），通过 Agent 总线互相委派任务
• 知识自生长 — Agent 把学到的东西存入 MetaMemory，组织每天都在变聪明，无需重新训练
• 自动化流水线 — “每天早上9点搜 AI 新闻，总结 Top 5，存档” — 一句话搞定
• 语音助手（Jarvis 模式） — AirPods 说 “Hey Siri, Jarvis”，免手免屏语音控制任意 Agent
• 自生长的组织 — 管理者 Bot 按需创建新 Agent，分配任务，安排后续跟进

为什么选 MetaBot

工作原理

飞书/TG/微信 → IM Bridge → Engine Router ──┬─→ Claude Code Agent SDK
                                            ├─→ Kimi Agent SDK（@moonshot-ai/kimi-agent-sdk）
                                            └─→ Codex CLI（codex exec --json 子进程）
                              ↕
                    MetaMemory（共享知识库）
                    定时调度（CC 原生 CronCreate / /loop；可选 /metaschedule 持久化）
                    Agent 总线（跨 Bot 通信，引擎无关）
                    Agent 工厂（可选 /metaskill，按需安装）

引擎层已抽象 —— Kimi 事件流和 Codex JSONL 都被翻译成 Claude 形状的 SDKMessage，流式卡片、工具调用追踪、MetaMemory/调度/Agent 总线在三种引擎下表现一致。

仓库布局（Monorepo）

MetaBot 从 2026-05-19 起把 metabot-core 合并进同一个 monorepo（npm workspaces）。Bridge 运行时仍在仓库根目录，吸收进来的中心服务侧在 packages/ 下面：

metabot/                       # 仓库根 —— bridge 运行时（bot 主机用 PM2 跑）
├── src/                       # bridge 引擎、流处理、Feishu/Telegram/微信桥接
├── bin/                       # CLI（metabot 单一入口 / doubao-tts）
├── web/                       # bridge 自带的浏览器 SPA
├── packages/                  # 吸收进来的 metabot-core
│   ├── server/                # 中心 HTTP 后端（ECS 部署单元）
│   ├── cli/                   # `metabot ` 功能 CLI 实现
│   ├── web-ui/                # 中心 SPA（Vite，编译后由 server/static/ 提供）
│   ├── cli-core/              # CLI/客户端共享底层
│   ├── metamemory/            # /api/memory 的瘦客户端
│   ├── skill-hub/             # /api/skills 的瘦客户端
│   └── skills/                # 默认 skill bundle 源（metabot SKILL.md）
└── docs/                      # 全量文档

两半之间只通过 HTTP /api/* 通信，不允许跨包 import（由 ESLint no-restricted-imports + packages/server/package.json exports 锁双重护栏）。Bridge 主机的 install.sh 只安装 bridge 自己 + CLI/CLI-Core 所需依赖，不会拉中心服务专属的 fastify / react / vite / 服务端 better-sqlite3。中心 server 部署仍走 cd packages/server && bash deploy/install.sh（脚本内部用 $PKG_DIR，不受路径迁移影响）。

多端接入

MetaBot 支持 4 种方式与你的 Agent 团队交互：

Web UI

浏览器端全功能聊天界面，部署即可用。访问地址：https://your-server/web/

• 实时流式聊天 — WebSocket 推送，Markdown 渲染，工具调用展示
• 电话语音模式 — 点击电话图标，全屏免手对话，VAD 自动检测说完
• RTC 实时通话 — 基于火山引擎 RTC 的双向语音/视频通话
• 群聊模式 — 多个 Agent 在一个对话中协作，@mention 路由
• MetaMemory 浏览器 — 搜索和浏览共享知识库
• 团队看板 — 查看 Agent 组织状态概览
• 文件支持 — 上传/下载文件，内联预览
• 明暗主题 — 跟随系统或手动切换

技术栈：React 19 + Vite + Zustand + react-markdown

语音功能需要 HTTPS。推荐用 Caddy 反向代理，自动管理证书。详见 Web UI 文档。

核心能力

快速开始

Telegram（30 秒）

1. 找 @BotFather → /newbot → 复制 token
2. 写入 bots.json → 完成（长轮询，无需 Webhook）

微信（灰测中）

1. iPhone 微信 8.0.70+ → 设置 → 插件 → 开启 ClawBot
2. 运行 install.sh，选 3) WeChat ClawBot — 扫码绑定
3. 详见 微信接入指南

飞书

1. open.feishu.cn 创建应用 → 添加「机器人」能力
2. 开通权限：im:message、im:message:readonly、im:resource、im:chat:readonly
3. 先启动 MetaBot，再开启「长连接」+ im.message.receive_v1 事件
4. 发布应用

不需要公网 IP。飞书用 WebSocket，Telegram 和微信用长轮询。

Web UI：启动 MetaBot 后访问 http://localhost:9100/web/，输入 API_SECRET 即可使用。

示例 Prompt

刚接触 MetaBot？以下是你可以直接在飞书/Telegram 中发送的真实 prompt：

MetaMemory — 持久化知识库

把我们刚讨论的部署方案写入 MetaMemory，放到 /projects/deployment 下面。

搜索一下 MetaMemory 里有没有关于 API 设计规范的文档。

定时任务（Claude Code 原生）

直接用 CC 内置的 CronCreate 和 /loop，会话内即开即用：

设个每天早上9点的定时任务：搜索 Hacker News 和 TechCrunch 的 AI 新闻，
总结 Top 5，保存到 MetaMemory。

/loop 每隔 5 分钟检查一下 PR #123 的 CI 状态，跑完为止

想跨重启活下来、其他 Bot 也能看到/取消？装可选的 /metaschedule skill （cp src/skills/metaschedule/SKILL.md ~/.claude/skills/metaschedule/）， 就能用 metabot schedule cron / HTTP API 提交到 MetaBot 服务端调度器。

Agent 团队 — 运行时协作

你来当主导工程师。并行派出一个前端专家和一个后端专家：
前端负责 React UI 改造，后端加上新的 /api/reports 接口，
你负责 review 两边的 PR，全部通过后再合并。

目标循环

/goal PR #123 的 CI 全绿、部署成功。
每 10 分钟检查一次，搞定后告诉我。

MetaSkill — Agent 工厂（可选）

/metaskill 默认不装。先启用：cp -r src/skills/metaskill ~/.claude/skills/，然后：

/metaskill 给这个 React Native 项目创建一个 agent 团队 ——
我需要一个前端专家、一个后端 API 专家、一个 code reviewer。

Agent-to-Agent 协作

把这个 bug 委派给 backend-bot 处理："修复 /api/users/:id 的空指针异常"。

让 frontend-bot 更新仪表盘 UI，同时让 backend-bot 加上新的 API 接口。
两边都把进度记录到 MetaMemory。

组合工作流

读一下这个飞书文档 [粘贴链接]，提取产品需求，拆成任务，
然后设一个每天下午6点的定时任务，对照需求跟踪开发进度。

（先 cp src/skills/metaskill 到 ~/.claude/skills/ 以启用 /metaskill）
/metaskill 创建一个 "daily-ops" agent，让它每天早上8点跑：
检查服务健康状态、review 昨晚的错误日志、发一份运维摘要。

飞书使用技巧

配置

bots.json — 定义你的 Bot：

{
  "feishuBots": [{
    "name": "metabot",
    "feishuAppId": "cli_xxx",
    "feishuAppSecret": "...",
    "defaultWorkingDirectory": "/home/user/project"
  }],
  "telegramBots": [{
    "name": "tg-bot",
    "telegramBotToken": "123456:ABC...",
    "defaultWorkingDirectory": "/home/user/project"
  }]
}

聊天命令

模型切换：每个会话可独立设置模型，默认 claude-fable-5。Fable 5 使用 Claude Code 原生 1M 上下文、128k max output 和 adaptive thinking；Opus/Sonnet 仍默认保持 200k 上下文，可在模型名后加 [1m] 启用 1M，例如 /model claude-opus-4-8[1m]。 Codex Skill 调用：飞书里发的 / ... 在 Codex 会话下会被 MetaBot 自动改写成 $ ...，例如 $metaschedule ...。

开发

npm run dev          # 热重载开发服务器（tsx）
npm test             # 运行测试（vitest）
npm run lint         # ESLint 检查
npm run build        # TypeScript 编译

Roadmap

• [ ] 插件市场（MCP Server 一键安装）
• [ ] 更多 IM 平台（Slack、Discord、钉钉）

关于

MetaBot 由 XVI Robotics 打造（人形机器人大脑公司）。我们在内部用 MetaBot 把公司打造成 Agent Native 组织 —— 一个小团队的人类，监督自我进化的 AI Agent。

我们开源它，因为我们相信这是未来公司的运行方式。

License

MIT