CI 状态说明: 当前 GitHub-hosted jobs 若显示未启动,仓库 Actions 注释为账户 billing lock;本地与部署验收命令见维护质量。
Telegram + 飞书 ↔ tmux 内 AI CLI(Claude Code / Codex / Oh My Pi)双向桥 —— 远程在 IM 话题发消息推动精确 tmux pane 里的 CLI,输出实时回推同一话题。
不调 API、不走 headless
claude -p/ SDK 路径、用 tmux pane TUI 注入 —— 保留本地交互式 CLI 作为唯一执行面。
Anthropic 文档说明:从 2026-06-15 起,Claude 订阅用户的 Agent SDK / claude -p / Claude Code GitHub Actions / 第三方 Agent SDK app 会走独立的 Agent SDK monthly credit;交互式 Claude Code terminal / IDE 继续走原订阅 usage limits。
| 明确走 Agent SDK credit | 文档说明仍走交互式订阅 usage limits |
|---|---|
| Claude Agent SDK | 交互式 Claude Code terminal / IDE |
claude -p headless / --print mode |
在 IDE 插件里用 Claude Code |
| Claude Code GitHub Actions | Claude web / desktop / mobile conversations |
| 基于 Agent SDK 的第三方应用 | — |
很多 IM ↔ Claude bridge 采用 Agent SDK 或 claude -p headless 子进程路线,这类路径已经被官方明确归入 Agent SDK credit。tmuxbot 的设计目标是避开这些 headless/programmatic 执行面,只远程控制本机已经存在的交互式 TUI。
tmuxbot 用 tmux pane TUI 注入:
- bot 通过
tmux paste-buffer把消息粘到 pane 里 - pane 里的
claude/codex是正常 TUI 模式跑,不是-p/ SDK - jsonl 写到
~/.claude/projects/<encoded-cwd>/*.jsonl,跟人手动跑完全一样
这不是官方政策承诺,而是项目的工程边界:不调用 vendor API、不派 headless 子进程、不把 IM bridge 做成 Agent SDK app。是否以及如何计量最终以各 CLI/vendor 的实际规则为准。
这是 tmuxbot 区别于 SDK/headless bridge 的核心价值。
一个 Python(3.10+)的 IM ↔ AI CLI 双向桥,可插拔架构:
- 前端(IM):Telegram、飞书(lark-oapi WebSocket 长连接)
- 后端(AI CLI):Claude Code、OpenAI Codex CLI、Oh My Pi(OMP)
- 架构原则:一个 IM credential 管多个精确 topic route;每个 route 绑定一个 tmux pane 并选择自己的 adapter
- 不在电脑前时,用手机 TG 或飞书推动本地 AI 跑代码 / 改项目 / 看日志
- 多项目并行:每个项目一个 tmux session 一个 cwd,各自加载项目自己的
CLAUDE.md - 多 CLI 共存:同一个项目群的不同话题可分别接 Claude、Codex、OMP,SSH attach 的仍是同一批真实 pane
要求:Linux、Python 3.10+、tmux,以及至少一个已安装的交互式 CLI(Claude Code / Codex / Oh My Pi)。
uv tool install 'tmuxbot[full]'
tmuxbot doctor
tmuxbot serve --open首次运行会自动打开中文 WebUI,并生成 10 分钟有效、设置成功后立即失效的一次性本机授权。没有 .env、通道或 binding 时 WebUI 也会保持可用;bridge 显示“尚未配置”。运行 tmuxbot doctor 可检查 tmux、Claude Code、Codex、Oh My Pi 和运行目录。
配置入口:
- 配置与运行说明:XDG 路径、Telegram/飞书 credential、
bindings.yaml、systemd、OMP SSH-only 与附件/Web 安全 - bindings.example.yaml:可直接改写的 route 示例
- Admin DM 运维指南:plan → apply → verify 的确定性项目开通流程
- Topic route 设计:endpoint、target、adapter 与 fail-closed 约束
- DEVELOPMENT.md:源码开发、测试和内部架构
为避免弱模型手工拼错 YAML、thread ID、tmux 或 systemd,Admin DM 使用独立 workspace(默认 ~/.local/share/tmuxbot/admin),避免根目录管理规则污染普通项目会话。安装命令会生成统一的 Admin Operations Contract、部署 runbook 和可校验 manifest:
tmuxbot admin --file /path/to/bindings.yaml --service tmuxbot.service \
install-contract
tmuxbot admin --file /path/to/bindings.yaml --service tmuxbot.service \
verify-context --json
tmuxbot admin --file /path/to/bindings.yaml --service tmuxbot.service \
provision-project --name demo-omp --channel telegram \
--credential TG_OMP_BOT_TOKEN \
--topic-link https://t.me/c/CHAT/THREAD \
--cwd /absolute/project/demo --backend omp
# 新话题则改用 --chat-id + --topic-title;核对 plan 后原命令增加 --apply。
# inventory / telegram-topic / feishu-topics / create-topic / bind-topic / verify
# 保留为低层诊断、恢复和迁移接口。事务内部负责完整候选校验、原子 YAML 替换、监督服务重启、post-apply verify 和失败回滚;LLM 只负责提供明确的 endpoint、target、cwd 与 adapter。
推荐先用 Claude Code native installer 安装 claude,并在 .env 里写绝对路径:
curl -fsSL https://claude.ai/install.sh | bash
echo "CLAUDE_BIN=$HOME/.local/bin/claude" >> .envCLAUDE_BIN 会在拉起 Claude 时读取,避免 systemd/tmux 的非交互 shell PATH 找不到 claude,也避免命中坏掉的 npm 全局安装。CODEX_BIN 与 OMP_BIN 同理可指向绝对路径;OMP route 使用 backend: omp,新建 Telegram 通道默认 credential env 为 TG_OMP_BOT_TOKEN。
Codex 的模型不由 tmuxbot 写死。每次新建或恢复 Codex TUI 时,tmuxbot 都读取
~/.codex/config.toml 顶层 model,存在时传递 -m <model>;因此只要修改 Codex
自身配置,之后的新会话和恢复会话都会自动使用新默认模型。配置缺失或无效时会省略 -m,交由 Codex 原生默认行为处理。
Runtime V2 仍然直接操作 tmux 内的交互式 CLI。建议先配置
TMUXBOT_RUNTIME_V2=shadow:线上继续发送兼容路径结果,同时只比较脱敏后的事件结构;
日志无 mismatch 后再切 on。TMUXBOT_CLAUDE_HOOKS=true 会幂等安装 tmuxbot
自有 Claude hooks,用于会话身份与 Stop 最终回复;hooks 只写本地 spool,不会直接发 IM,
JSONL 和终端状态探测仍继续工作。
mkdir -p ~/.config/systemd/user
ln -sf "$(pwd)/deploy/systemd/tmuxbot.service" ~/.config/systemd/user/tmuxbot.service
systemctl --user daemon-reload
systemctl --user enable --now tmuxbot.service
loginctl enable-linger $USER
# 或由安装器生成同一个 unit;健康审计始终非破坏且只检查已有 pane
# tmuxbot install-service --now
# 看日志 / 重启 / 停
journalctl --user -u tmuxbot -f
systemctl --user restart tmuxbot
systemctl --user stop tmuxbot生产主机只应启用一个 tmuxbot.service。同一进程可承载多个 Telegram Bot 和飞书
App credential;每个飞书 App 使用隔离的 SDK event loop,避免 lark-oapi 的模块级
loop 在多 App 间互相覆盖。旧版 tmuxbot-bridge-refresh@*.timer 不再需要:安装器会
停用并删除该周期强制重启 helper,连接恢复由 frontend 自身重连循环负责。
Restart=always 会在主进程或 bridge child 异常退出后 5 秒内自动拉起;unit 关闭
systemd start-limit,瞬时连续故障不会让服务永久停在 failed。运行中可在 WebUI 的
/api/channel-health 查看只读连接审计(连接时间、最近收包、最近有效入站、恢复次数)。
tmux 会话默认按消息懒启动:手动执行 tmux kill-session -t <name>,或在
Telegram/飞书发送 /tmuxstop 后,后台不会周期性复活它;下一条消息到达时会自动重建
tmux,并恢复已绑定的 Claude/Codex/OMP provider 会话。安装器默认设置
TMUXBOT_LIFECYCLE_ENABLED=1,用于非破坏性健康审计。watchdog 默认每 60 分钟仅巡检
已存在的 route pane:验证 provider 前台进程与健康状态,必要时仅恢复该 route 的异常
provider 进程树。它不会按空闲时间退出 Claude/Codex/OMP,不会重建被人工关闭的 tmux,也不会执行
tmux kill-server;缺失 target 仍等下一条精确 route 消息按需恢复。Telegram、飞书和 Web
控制面板都提供带确认的“关闭 tmux”操作,管理记录和历史不会被删除。旧多服务主机的合并、offset 防回吐、
回滚和验收步骤见 docs/single-service-operations.md。
推荐统一入口会启动 Web,并按配置状态监督独立 bridge child:
tmuxbot serve --open默认监听 127.0.0.1:8765。tmuxbot web 仍可只启动 Web;tmuxbot bridge 仍保留严格配置检查。配置、数据和状态默认使用 XDG 目录:~/.config/tmuxbot、~/.local/share/tmuxbot、~/.local/state/tmuxbot。
需要常驻时:
tmuxbot install-service --now
journalctl --user -u tmuxbot -f不要把 Web 端口直接暴露到公网。 远程访问应通过带 TLS 和访问控制的反向代理,
并设置 TMUXBOT_WEB_SECURE_COOKIE=true 与准确的 TMUXBOT_WEB_PUBLIC_ORIGIN。
deploy/systemd/tmuxbot-web.service 提供独立 unit 示例;其中凭证只从 .env 读取,
不会出现在 ExecStart 命令行。
- 零配置中文 WebUI:
uv tool install 'tmuxbot[full]'后运行tmuxbot serve --open;可验证项目目录、显示 Git 与已有 pane、扫描/探测 tmux、Claude Code、Codex、Oh My Pi,登记项目并启动受管 CLI。已有 pane 可先以只读模式直接查看,手动接管后才允许输入;模型候选仍由当前 CLI 的原生/modelpicker 提供。 - 原生 Web TUI:xterm.js 直接 attach 已登记 tmux target,默认只观察;显式接管后才允许键盘输入,断开浏览器不会终止 tmux 会话
- Web 通道向导:可为受管会话配置 Telegram 或飞书,密钥只写入本机
0600配置,不通过 API 回显;浏览器只提交 provider ID,binary、tmux target 和启动参数均由服务端 registry 管理 - TeamRun 多 LLM:确定性 Coordinator / Implementer / Reviewer 三角色协作,唯一写租约、DAG、mailbox、Artifact、重试、独立验收和恢复;Implementer 交付证据后 Reviewer 自动收到只读审查包
- 双前端:Telegram(DM / 普通群 / supergroup forum topic)+ 飞书(群聊 / 私聊,Card JSON 2.0 收发/编辑;操作统一使用
/命令) - 中文控制面板:
/menu主动打开轻量面板(/panel、/settings兼容保留),可切换群聊 @ 策略、执行/status/screen/new/compact/resume/esc/cc。模型候选由当前 tmux CLI 的原生/model选择器实时提供,面板会显示已读取的当前模型。受管 Codex 会话在新建与重启恢复时读取~/.codex/config.toml的model;可在当前会话中用原生/model临时切换,下一次 bot 重启则应用最新配置。面板也提供带二次确认的“重启 CLI”,Codex/Claude 都会恢复原 provider 会话与 transcript,保留上下文;Claude 模型卡额外提供“仅本会话”,避免修改未来新会话默认模型 - @ 策略命令:
/mention on表示无需 @,/mention off表示必须 @,/mention default恢复部署默认,/mention status查看当前策略;设置按 binding 持久化且立即生效 - 按 route 选择 adapter:同一 Telegram Bot/飞书 App credential 可按精确 topic/thread route 混合承载 Claude Code、Codex 和 OMP;不同 credential 仍可并行部署
- 核心命令:
/status/info/whoami/new/resume/rename/esc/cc/eof/screen/restart/tmuxstop。OMP route 的/exit先透传给受管 OMP;随后立即清除旧 transcript pin,并在 3 秒后 clean respawn 一个不带--resume的全新 OMP 会话。新进程会重新读取 OMP 启动配置和已安装插件,完成后在 IM 回报;它不保留上一个会话上下文。/restart仍是保留精确 provider 会话与 transcript 的受管重启。对 OMP,bot/plan是本地帮助:只报告当前 plan 状态,并提示 SSH attach 后使用默认Alt+Shift+P(自定义 keybinding 可能不同),不会向 pane 注入/plan - TUI 透传:
/context/cost/usage/compact/clear等,抓屏结构化反馈 - 工具调用聚合:一个 turn 内的 tool_use 流式刷同一条 IM 消息,真说话单独 push 触发通知;OMP 成功执行
edit时同步显示受限 diff,成功执行普通本地write时同步显示受限代码片段,内部工具 URI 和敏感文件内容不外发 - Codex 计划跟随:
update_plan会维护一条可编辑的“当前计划”消息,TG/飞书里持续显示最新in_progress/pending/completed状态 - 双向附件:Telegram/飞书收到的图片/文件会下载到本机并以
@path注入 TUI;AI 回复里的绝对/相对路径、Markdown 文件链接和图片链接会转成原生 IM 附件,聊天内容不暴露服务器绝对路径 - 统一富消息:Claude/Codex/OMP 共用
ReplyDocument;回复详细信息会显示运行时模型与档位(如gpt-5.6-terra medium);代码围栏可保留语言与filename=...标签,Markdown 表格在 Telegram 退化为对齐的原生<pre>数据块,在飞书使用 Card 2.0 根级table组件;Telegram 继续使用安全 HTML/可展开引用,飞书使用 header、summary、状态色和可选 CardKit 流式更新 - 长回复自动分页:Telegram 按 HTML/UTF-16 安全边界拆成多条消息并保持代码块标签完整;飞书同时按 Card JSON 2.0 的 30KB payload 和每卡最多 50 个 body element 拆成连续卡片,不再因大量短 Markdown 段落触发
element exceeds the limit,也不把普通长回复截断成预览或强制改发 TXT - Telegram 状态标识:Telegram 没有飞书式原生彩色卡片标题,使用
🟡 工作中、🟠 等待输入、✅ 已完成、🔴 错误/阻塞、🔵 信息、⚪ 状态未知作为文本等价呈现 - 飞书状态色:工作中黄色、等待输入橙色、完成/空闲绿色、错误/阻塞红色、普通信息蓝色、未知状态灰色;流式回复从黄色开始并在成功完成后变为绿色
- OMP 精确身份:受管 extension 写入 target-scoped handoff 与 health sidecar;handoff 记录
tmuxTarget/cwd/sessionId/transcriptPath/processId,health 记录同一会话身份与状态。新会话 JSONL 首条消息前可能尚未落盘,此时只接受官方~/.omp/agent/sessions路径、匹配 session ID 且 processId 属于该 pane 的 provider-authored record;文件出现后立即回到 header/cwd 校验。恢复只使用omp --resume <absolute transcript path>,不按 mtime 或 cwd 猜测会话 - OMP 原生运行语义:普通文字和附件在 working/streaming 时进入 steering queue;
/new、/compact等控制命令要求 idle,忙碌时立即拒绝。状态以 provider-authored sidecar 和 JSONL v3 为权威;IM 状态栏优先显示当前上下文已用/上限/余量、会话累计 token、最近一轮缓存命中率、自动压缩、模型与思考强度,用于判断继续、压缩或新建会话。会话文件 MB 不作为 token 指标;原生 footer 仅是版本化弱信号。 - OMP 交互安全:原生菜单、picker、ask、approval、plan review 和确认只通知精确 pane 的 SSH attach 命令;Telegram/飞书不模拟方向键、Enter、批准或取消按键
- 活性指示:provider-authored health、JSONL 进展与严格的当前 live loader 共同判定状态;工作中显示 typing(Telegram),飞书无 typing API
- 消息已读反应:TG 👀 emoji(Bot API 7.0+);飞书 👀 OnIt reaction
- 订阅配额:
/status展示 5h/7d 五窗口 utilization + 精确重置倒计时(走 OAuth API) - 健壮性:tmux paste 等 TUI idle 后提交,并读取 Claude/Codex/OMP 活动输入框确认;OMP steering 是唯一 busy 普通消息例外,控制命令仍 fail fast。OMP 17.3.3 附件
@path打开文件补全时,首个 Enter 只接受补全也不会把消息留在输入框,tmuxbot 会确认草稿仍在并有限重试提交。Telegram 最终回复逐分片校验 Bot APImessage_id,未确认送达时不推进 JSONL offset、下轮自动重试;tailer 另有 512KB 积压保护、GC 强引用和 offsets debounce。源码部署的bin/restart.sh会先重装当前 checkout 的 uv tool,避免 systemd 运行旧 wheel
TG 用户 飞书用户
│ │
├─ @claude_bot ─┐ ┌─ 飞书 App ─┐
│ │ │ │
▼ ▼ ▼ ▼
TelegramFrontend FeishuFrontend
(aiogram polling) (lark-oapi WebSocket)
│ │
└───────────────────────┘
│
dispatch.py (共享命令分发层)
│
┌────────┼────────┐
│ │ │
ClaudeCode Codex OMP
Backend Backend Backend
│ │ │
└────────┼────────┘
│
tmux pane(s)
TUI idle 轮询 → paste-buffer
→ composer 渲染 → Enter → 确认/有限重试
│
jsonl tailer
parse_event + aggregator
│
推回 IM 前端
技术细节看 DEVELOPMENT.md。
飞书默认启用 Card JSON 2.0。需要临时回滚旧卡片时设置
TMUXBOT_FEISHU_CARD_V2=0。CardKit 流式更新默认关闭;确认应用已订阅
card.action.trigger 并拥有 cardkit:card:write 权限后,可设置
TMUXBOT_FEISHU_STREAMING=1 灰度启用。多飞书应用可以使用
FEISHU_CARD_V2、FEISHU_STREAMING 等按 bot_token_env 前缀覆盖。
回复里的本地文件只有在以下目录内才会自动上传:binding 的 cwd、
TMUXBOT_ATTACHMENT_DIR、操作系统临时目录,以及
TMUXBOT_ATTACHMENT_ALLOWED_ROOTS 明确配置的目录。额外目录在 Linux 上使用
冒号分隔。目录、设备、socket、不存在的文件和安全根之外的路径不会上传;
上传失败只向聊天显示安全文件名,不显示服务器绝对路径。
make install-dev
make check
make check-web # 会先按 package-lock 执行 npm ci
# 发布机额外运行(会检查本机 tmux/CLI/运行目录)
make release-checkv0.3.0 是冻结的产品化基线;当前 main / v0.3.1 完成 OMP clean cutover。发布点使用 vMAJOR.MINOR.PATCH
标签保存。产品边界、冻结能力和下一阶段维护债务见
PRODUCTIZATION.md。
持续迭代入口:
- CHANGELOG.md:变更记录
- VERSIONING.md:版本号与发布标签策略
- RELEASE.md:发布检查清单
- CONTRIBUTING.md:贡献与 PR 要求
- SECURITY.md:安全边界与敏感文件规则
- SUPPORT.md:issue/support 信息收集指南
- PRODUCTIZATION.md:长期产品化路线
- M1 ✅ 单文件骨架 + 双 binding + 命令组 + heartbeat
- M2 ✅ 代码审查 + 可插拔重构(
backends/+frontends/+dispatch.py) - M3 ✅ 接入 Codex CLI + 多 bot 共存 + systemd 部署
- M4 ✅ 接入飞书前端(lark-oapi WebSocket + interactive card)+ 多实例支持
- 0.3.0 ✅ Runtime V2、中文 WebUI、XDG/doctor/systemd 安装面、终端接管与 TeamRun 基线
- 0.3.1 ✅ Oh My Pi 原生适配:OMP v3、受管身份 sidecar、精确恢复、SSH-only 原生交互与 Web/doctor/config clean cutover