CodexClaw

![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/en/download/current)

一个Telegram机器人，让你远程访问 @openai/codex 通过具有两个Codex后端的Node.js运行时：Codex SDK和传统的CLI/PTy路径。\ 它的灵感来源于 RichardAtCT/claude-code-telegram，但该项目是为CodeX SDK/CLI+MCP+子代理路由实现的。

这是什么？

该机器人将Telegram连接到Codex，并将任务路由到正确的执行界面：

编码任务 ->Codex SDK线程或Codex CLI/PTy会话
明确的工具任务 ->次级代理商(/mcp, GitHub Skill)
主动自动化 ->用于每日摘要和推送通知的Cron调度程序

关键设计目标：

在Telegram上保持Codex互动会话的顺畅和流媒体安全
仅使用白名单用户强制执行零信任访问
通过将Codex MCP与Bot MCP的职责分开，避免重复的MCP调用
对于新安装，更喜欢SDK后端，同时保留CLI后端作为后备

像使用技能一样使用它

它做什么

安装面向Telegram的Codex运行时
将Codex实时会议的范围限定为 chat + repo
管理机器人端MCP和GitHub子代理
从Telegram公开仓库切换、状态和最小的前端开发服务器控制

安装

git clone https://github.com/MackDing/CodexClaw.git
cd CodexClaw
npm install
cp .env.example .env

配置最小值

BOT_TOKEN=123456789:telegram-token
ALLOWED_USER_IDS=123456789
STATE_FILE=.codex-telegram-claws-state.json
WORKSPACE_ROOT=.
CODEX_WORKDIR=.
CODEX_BACKEND=sdk

开始技能

npm run start

Telegram快速使用

/status
/repo
/skill
/dev status
/gh create repo my-new-app

有关面向代理的设置，请参阅技能.md.

快速开始

先决条件

Node.js 20+https://nodejs.org/en/download/current
Codex CLI——https://github.com/openai/codex
Telegram Bot令牌--来自 @BotFather

开发命令

npm run start -启动bot
npm run dev -地方发展观察模式
npm run check -存储库的TypeScript类型和语法验证
npm run typecheck -在中运行TypeScript编译器 --noEmit 模式
npm run lint -ESLint用于源代码、测试、脚本和本地JS/CJS配置文件
npm run lint:fix -使用安全的棉绒固定
npm run format -使用Prettier格式化存储库文件
npm run format:check -验证格式
npm test -运行完整的测试套件
npm run healthcheck -静态运行时就绪性检查
npm run healthcheck:strict -更严格的以生产为导向的健康检查
npm run healthcheck:live -实时Codex+Telegram对配置的后端和机器人令牌进行探测
npm run telegram:smoke -当真正的机器人代币可用时，实时Telegram API烟雾测试

建筑

Telegram Message
  -> src/bot/handlers.ts
  -> src/orchestrator/router.ts
     -> src/runner/ptyManager.ts        (coding tasks -> Codex SDK or Codex CLI)
     -> src/orchestrator/skills/*.ts    (general tasks -> MCP/GitHub subagents)
  -> src/bot/formatter.ts
  -> Telegram sendMessage/editMessageText

核心模块：

src/index.ts：引导和生命周期
src/config.ts：env解析和验证
src/bot/：身份验证中间件、格式化、命令处理程序
src/orchestrator/：路由+MCP客户端+技能
src/runner/ptyManager.ts：SDK线程、CLI/PTy会话和CLI exec回退的Codex运行器抽象
src/cron/scheduler.ts：主动计划推送

企业目标架构：文档/企业架构.md 企业第一阶段路线图： docs/第一阶段路线图.md

路由和MCP边界

为了避免重复的上下文获取：

编码请求 直接发送到Codex（SDK或CLI后端；Codex可以使用自己的MCP堆栈）
机器人侧MCP 仅由显式使用 /mcp ... 命令

这可以防止：

对同一MCP服务器的重复查询
额外的延迟/令牌/工具成本
来自两个独立MCP执行面的上下文漂移

子代理

在这个存储库中，“子代理”是指路由器后面的专用技能执行者，而不是第二个自由形式的Codex会话。

当前子代理：

github skill-本地git操作，通过GitHub API创建repo，以及测试作业跟踪
mcp 技能明确的MCP服务器检查、启用/禁用、工具列表和工具调用

它们是如何触发的：

显式命令总是直接指向匹配的子代理：

- /gh ... ->GitHub技能 - /mcp ... ->MCP技能

当路由器看到支持的GitHub风格请求时，纯文本也可能路由到子代理，例如 git push, commit，或 run test
其他一切都可以追溯到Codex

发生这种情况的地方：

路由器决策顺序： router.ts
每次聊天的技能切换： skill注册表.ts
电报命令入口点：手柄ts

在操作上，子代理是机器人的控制平面。Codex仍然是编码执行平面。

命令

概述：

/start -引导消息
/help -命令摘要
/status -显示当前聊天状态、活动运行器模式、工作目录、模型覆盖、MCP服务器和内部超级权限工作流阶段
/pwd -显示此聊天的当前项目目录
/repo -在下面列出可切换的git项目 WORKSPACE_ROOT
/repo -将当前聊天切换到另一个项目
/repo -模糊匹配项目；如果只有一个匹配项，则切换，否则列出候选人
/repo -当没有直接匹配时，建议最接近的项目名称
/repo recent -显示当前聊天的最新项目
/repo - -切换回上一个项目
/new -清除当前项目的已保存Codex对话，并重新开始下一条消息
/exec -在不保存项目上下文的情况下强制执行一次性Codex运行
/auto -强制一次性全自动Codex运行，而不保存项目上下文
/plan -仅向食品法典委员会索取计划，没有直接的文件修改意图
/continue -重播上次被阻止的同一工作目录Codex请求一次
/model [name|reset] -显示或设置当前聊天的模型覆盖
/language [en|zh|zh-HK] -显示或设置当前聊天的系统语言
/verbose [on|off] -显示或切换当前聊天的系统通知
/skill list -显示当前聊天的技能切换
/skill status -别名 /skill list
/skill on -为当前聊天启用技能
/skill off -禁用当前聊天的技能
/dev start -启动当前的repo前端服务器(dev那么 start)
/dev stop -停止当前的repo前端服务器
/dev status -显示当前仓库前端服务器状态
/dev logs -显示当前repo前端服务器日志尾部
/dev url -显示检测到的本地前端URL
/sh -在当前项目中运行安全的已分配Linux命令（默认情况下禁用）
/sh --confirm -启用可写模式时确认危险命令
/restart -从Telegram显式重启机器人进程
/interrupt -中断当前的Codex运行
/stop -终止当前的Codex运行
/cron_now -立即触发每日摘要

MCP技能：

/mcp list
/mcp status [server]
/mcp reconnect
/mcp enable
/mcp disable
/mcp tools
/mcp call {"query":"..."}

GitHub技能：

/gh commit "feat: message" ->明确的GitHub写入操作
/gh push ->明确推动当前分支
/gh create repo my-new-repo ->在下显式创建兄弟仓库 WORKSPACE_ROOT
/gh confirm ->确认待处理的GitHub写入操作并执行它
纯文本写入请求，例如 create repo ..., commit，或 push 被拦截并转化为制导；他们不再直接执行GitHub写操作
/gh run tests ->启动测试作业
/gh test status ->读取测试状态/输出尾部

电报改编说明：

纯文本消息的行为类似于正常的Codex对话
/exec 运行一次性Codex任务，不会覆盖已保存的项目对话槽
/auto 使用以下命令运行一次性Codex任务 approvalPolicy=never 在SDK后端，或 codex exec --full-auto 在CLI后端
/new 由机器人实现，并重置当前聊天会话
/new 仅清除当前项目保存的Codex对话槽
/status 由bot实现，并报告本地运行时状态
/status 还可对内部进行表面处理 superpowers 工作流系统和当前聊天/项目会话的最后检测到的工作流阶段
/repo 由bot实现，并在内部切换每个聊天的工作目录 WORKSPACE_ROOT
/skill 由机器人实现，并将每个聊天技能开关保持在运行时状态
/skill 仅列出可切换的机器人技能； superpowers 显示为内部工作流程，而不是可切换的技能
/dev 由bot实现，每个repo工作目录管理一个前端服务器，在聊天中共享
/dev start 偏爱 package.json 脚本 dev 并回落到 start
/sh 由bot实现，从不调用shell解释器，只接受配置的命令前缀
/sh 默认情况下为只读；可以配置危险前缀，并要求 --confirm 启用可写模式时
/plan 转化为仅计划提示，而不是传递原始提示 /plan 对Codex执行斜线命令
如果另一个聊天在同一个工作目录中已经有一个活动的Codex运行，机器人会阻止新的请求并要求 /continue 进行一次超控
默认系统语言为英语；使用 /language zh 或 /language zh-HK 用于本地化机器人响应
/verbose off 通过隐藏当前聊天的回退、启动和会话退出通知来保持Telegram输出安静

流媒体和推理可视化

Codex输出以节流方式流式传输 editMessageText 更新。

油门：由控制 STREAM_THROTTLE_MS （默认值 1200)
长输出：自动分块为Telegram安全的消息大小
MarkdownV2:转义以避免解析失败
推理标签： ... 提取并呈现为：

- 扰流板(||...||，默认） - 引用块（如果 REASONING_RENDER_MODE=quote)

开 CODEX_BACKEND=sdk，Telegram流式传输结构化的Codex SDK事件，并保留每个项目的线程ID
开 CODEX_BACKEND=cli，机器人更喜欢PTY会话；如果 node-pty 无法在当前主机上生成，它将回退到 codex exec
在CLI exec回退模式下，Telegram输出被清理以隐藏Codex横幅、原始工具跟踪、， mcp startup，并复制 tokens used 页脚
在macOS上，启动自动修复 node-pty 助手在第一个PTY会话之前执行权限

项目范围对话状态

对话状态现在按以下方式跟踪 chat + project，而不仅仅是聊天。

当你切换到 /repo ，bot将该项目的最后一个Codex会话id保持在运行时状态
稍后切换回同一项目时，下一个纯文本任务将恢复该项目的Codex线程/会话
/new 仅清除当前项目的已保存对话槽；同一Telegram聊天中的其他项目未受影响
/exec, /auto，以及 /plan 按设计保持一次性，不替换已保存的项目对话
在SDK后端，项目还原使用 resumeThread(threadId)
在CLI后端，项目还原使用PTY resume或 codex exec resume

工作区冲突防护

当另一个机器人管理的聊天在同一个工作目录中已经有一个活动的Codex任务时，该机器人现在会阻止第二次Codex运行。

默认情况下，警告很强，因为在同一工作目录中同时写入很容易损坏
/continue 为当前聊天回放一次最近被阻止的请求
切换项目会清除挂起的已阻止请求
这个守卫在此过程中只看到机器人管理的聊天；如果您还在终端中直接使用Codex，请使用单独的git工作树以避免冲突

前端调试层

该机器人包括一个最小的回购范围的前端运行时层：

/dev start 启动当前仓库的前端命令
/dev stop 阻止它
/dev status 显示它是否正在运行
/dev logs 返回最近的输出尾部
/dev url 从日志中返回第一个检测到的本地URL

选择规则：

更喜欢 package.json 脚本 dev
如果 dev 已丢失，请退回 start
每个repo工作目录只保留一个活动前端服务器
不要通过以下方式公开任意shell执行 /dev

后端选择

选择执行后端 CODEX_BACKEND:

sdk -首选新安装；避免PTY脆弱性，并使用持久的Codex SDK线程
cli -遗留后端；在可用时使用PTY，然后回退到 codex exec

SDK相关选项：

CODEX_BACKEND=sdk
CODEX_SDK_CONFIG={}
CODEX_SDK_SKIP_GIT_REPO_CHECK=true
CODEX_SDK_SANDBOX_MODE=danger-full-access
CODEX_SDK_APPROVAL_POLICY=never
CODEX_SDK_REASONING_EFFORT=high
CODEX_SDK_NETWORK_ACCESS_ENABLED=true
CODEX_SDK_WEB_SEARCH_MODE=live
CODEX_SDK_ADDITIONAL_DIRECTORIES=["/abs/path/extra-worktree"]

如果 CODEX_SDK_SANDBOX_MODE 如果未设置，机器人现在将SDK线程默认为完全访问： danger-full-access 和 approvalPolicy=never。将其明确设置为 workspace-write 或 read-only 只有当你想要一个更受限制的模式时。

CLI相关选项：

CODEX_BACKEND=cli
CODEX_COMMAND=codex
CODEX_ARGS=

事件驱动自动化

node-cron 内置主动行为：

每日总结时间表： CRON_DAILY_SUMMARY （默认值 0 9 * * *)
目标用户： PROACTIVE_USER_IDS
摘要包括提交计数、更改的文件、插入/删除和最近的提交

使用 /cron_now 用于调试期间的手动触发。

配置

必修的：

BOT_TOKEN=...
ALLOWED_USER_IDS=123456789,987654321
STATE_FILE=.codex-telegram-claws-state.json
WORKSPACE_ROOT=.
CODEX_WORKDIR=.

常见选项：

TELEGRAM_API_BASE=https://api.telegram.org
TELEGRAM_PROXY_URL=
CODEX_COMMAND=codex
CODEX_ARGS=
CODEX_BACKEND=sdk
CODEX_SDK_CONFIG={}
CODEX_SDK_SKIP_GIT_REPO_CHECK=true
CODEX_SDK_SANDBOX_MODE=
CODEX_SDK_APPROVAL_POLICY=
CODEX_SDK_REASONING_EFFORT=
CODEX_SDK_NETWORK_ACCESS_ENABLED=
CODEX_SDK_WEB_SEARCH_MODE=
CODEX_SDK_ADDITIONAL_DIRECTORIES=[]
WORKSPACE_ROOT=/Users/yourname/projects
STATE_FILE=/path/to/codex-telegram-claws-state.json
SHELL_ENABLED=false
SHELL_READ_ONLY=true
SHELL_ALLOWED_COMMANDS=["pwd","ls","git status","git diff --stat","npm test","npm run check"]
SHELL_DANGEROUS_COMMANDS=["git add","git commit","git push","rm","mv","cp","npm publish"]
SHELL_TIMEOUT_MS=20000
SHELL_MAX_OUTPUT_CHARS=12000
STREAM_THROTTLE_MS=1200
STREAM_BUFFER_CHARS=120000
REASONING_RENDER_MODE=spoiler

CRON_DAILY_SUMMARY=0 9 * * *
CRON_TIMEZONE=Asia/Shanghai
PROACTIVE_USER_IDS=123456789

MCP：

MCP_SERVERS=[]

github：

GITHUB_TOKEN=ghp_xxx
GITHUB_DEFAULT_WORKDIR=.
GITHUB_DEFAULT_BRANCH=main
E2E_TEST_COMMAND=npx playwright test --reporter=line

CI和发布自动化

GitHub操作现在包括：

CI 推送和拉取请求的工作流程
Telegram Smoke 配置存储库机密时用于实时bot令牌验证的手动工作流
Release 工作流打开 v* 标签，重新运行验证并发布GitHub版本

实时烟雾检查的存储库秘密：

TELEGRAM_BOT_TOKEN
TELEGRAM_EXPECTED_USERNAME （可选）
TELEGRAM_SMOKE_CHAT_ID （可选）

将实时验证输出从git历史记录和发布说明中删除。Bot用户名、线程ID和聊天ID是特定于环境的操作员数据，应由每个用户在本地或通过GitHub secrets进行配置。

推荐的本地释放门：

BOT_TOKEN=dummy-token ALLOWED_USER_IDS=1 npm run release:check
npm run healthcheck:live
npm run telegram:smoke

v1.0.0 只有在完全释放门、Telegram烟雾检查和存储库元数据同步完成后，才应标记。详细的检查表和主题同步命令已上线 release.md.

发布参考：

安全基线

仅限白名单访问(ALLOWED_USER_IDS)是强制性的
不要承诺 .env、令牌或会话工件
在生产环境中，使用受限制的操作系统用户运行机器人
保持 CODEX_WORKDIR 作用域为安全的工作区根
保持 WORKSPACE_ROOT 仅限于父目录，该目录仅包含您希望机器人访问的项目
保持 /sh 残疾，除非你需要；启用后，仅公开只读或范围狭窄的命令前缀
/sh 用途 spawn(..., { shell: false })，拒绝管道/重定向/子shell语法，并在当前项目目录内运行
保持 SHELL_READ_ONLY=true 除非你有充分的理由允许写命令
如果允许写入命令，请在中标记高风险前缀 SHELL_DANGEROUS_COMMANDS 并要求 /sh --confirm ...
偏好最低权限GitHub PAT

运营

推荐的生产主管是PM2。

ecosystem.config.ts 是规范配置文件。以以下方式启动PM2 ecosystem.config.cjs，它只将PM2桥接到TypeScript源代码中。

基本流程：

pm2 start ecosystem.config.cjs
pm2 status CodexClaw
pm2 logs CodexClaw
pm2 restart CodexClaw

每个机器人令牌只运行一个轮询过程。

你应该启用吗 `/sh`?

通常不适合一般用户。Codex本身可以将命令作为编码任务的一部分运行，因此 /sh 对于正常的代码编辑工作流来说，这不是必需的。

当您需要Telegram的确定性运算符操作时，它很有用，例如：

pwd
git status
git diff --stat
npm test

将其视为仅限管理员的操作通道，而不是通用的远程shell。

MCP和技能控制平面

Telegram可以管理Bot端MCP的运行时使用和技能，但不能从聊天中安装任意新服务器。

MCP服务器是进程级运行时资源：列出、检查、重新连接、启用、禁用
技能是聊天级别的路由开关：每个聊天都可以启用或禁用 github 和 mcp 独立地
Codex自己的MCP仍然是独立的，不通过这些机器人命令进行管理
运行时状态持久化为 STATE_FILE，所以 /mcp enable|disable, /skill on|off, /language, /verbose，并且每个项目的Codex对话槽在机器人重启后仍然有效

故障排除

Bot没有响应：验证 BOT_TOKEN 和 ALLOWED_USER_IDS
API电报被阻止：set TELEGRAM_PROXY_URL （类似HTTP代理 http://127.0.0.1:7890)或者运行本地Bot API服务器并设置 TELEGRAM_API_BASE
食品法典委员会未产生产出：验证 CODEX_BACKEND, CODEX_COMMAND，以及 CODEX_WORKDIR
SDK后端无法恢复：验证主机仍然可以访问 ~/.codex/sessions 并且保存的线程id属于同一工作目录
Markdown解析错误：减少输出大小/上下文；检查工具输出中的特殊字符
MCP故障：run /mcp tools 首先验证服务器可用性
GitHub API失败：验证 GITHUB_TOKEN 范围(repo)以及帐户权限
重复MCP怀疑：确保编码任务直接发送到Codex，bot MCP仅用于 /mcp
posix_spawnp failed：这通常意味着 node-pty 助手失去执行权限；初创公司现在自动修复它，以及 npm run healthcheck 报告结果

参考

灵感来源：https://github.com/RichardAtCT/claude-code-telegram
Codex SDK参考：https://github.com/coleam00/codex-telegram-coding-assistant
此实现：Codex第一个Node.js堆栈(@openai/codex-sdk, telegraf, node-pty, node-cron，MCP-SDK）

______________________________________________________________________

🦞 OPC生态系统

建造于 @麦丁 --由人工智能代理支持的单人公司基础设施。

项目	它做什么
opc.ren	OPC创始人中心——工具、信号、社区
CodexClaw	通过MCP+子代理路由实现远程Codex访问的电报机器人
很棒的ai api	200+AI API网关和中继的排行榜
克劳德上下文健康	诊断并修复Claude Code会话降级
opc日信号	为OPC创始人提供人工智能驱动的日常决策智能
文档预处理中心	企业文档预处理——MinerU+文档

Codex Claw

快速接入

详细介绍

CodexClaw

这是什么？

像使用技能一样使用它

它做什么

安装

配置最小值

开始技能

Telegram快速使用

快速开始

先决条件

开发命令

建筑

路由和MCP边界

子代理

命令

流媒体和推理可视化

项目范围对话状态

工作区冲突防护

前端调试层

后端选择

事件驱动自动化

配置

CI和发布自动化

安全基线

运营

你应该启用吗 `/sh`?

MCP和技能控制平面

故障排除

参考

🦞 OPC生态系统

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

Codex Claw

快速接入

详细介绍

CodexClaw

这是什么？

像使用技能一样使用它

它做什么

安装

配置最小值

开始技能

Telegram快速使用

快速开始

先决条件

开发命令

建筑

路由和MCP边界

子代理

命令

流媒体和推理可视化

项目范围对话状态

工作区冲突防护

前端调试层

后端选择

事件驱动自动化

配置

CI和发布自动化

安全基线

运营

你应该启用吗 /sh?

MCP和技能控制平面

故障排除

参考

🦞 OPC生态系统

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

你应该启用吗 `/sh`?