Skip to content

TRM-coding/Codex-in-Telegram

BranchesTags

Repository files navigation

Codex to Telegram

Run your local Codex CLI from Telegram, keep Codex sessions per chat, and receive the final answer back on your phone.

中文 · English

Python Telegram Codex

中文

Codex in Telegram 架构图

项目介绍

Codex to Telegram 是一个把 Telegram Bot 和本地 Codex CLI 连接起来的轻量桥接插件。配置完成后，你可以直接在 Telegram 里给 Codex 发送任务，Codex 会在指定工作目录中执行请求，并把最终回答返回到 Telegram。

它适合把 Codex 放在开发机、服务器或家用主机上长期运行，然后用手机或 Telegram 客户端随时发起代码分析、修改、排查和解释任务。

它可以做什么

能力 说明
通过 Telegram 调用 Codex 发送普通文本消息，或使用 /codex <request> 发起 Codex 请求。
实时状态回显 Bot 会编辑运行中消息，显示 Codex session、正在执行的命令和最近输出。
保持连续会话 每个 Telegram chat 会保存自己的 Codex session，后续消息会自动 resume。
会话管理 使用 /session 查看当前 session，/new 开启新会话，/history 查看历史，/resume 恢复指定会话。
用户访问控制 只有 TELEGRAM_ALLOWED_USER_IDS 中的 Telegram 用户可以运行 Codex。
权限模式切换 使用 /grant 在只读、工作区写入和完整访问模式之间切换。
长任务友好 支持超时配置、并发限制、运行中 /steer、/stop 和 Telegram 长消息自动分段。
适合常驻运行 可通过 systemd 部署成后台服务。

工作原理

Telegram message
       |
       v
Python Telegram bot
       |
       v
codex app-server --listen stdio://
       |
       v
Codex app-server JSON-RPC events
       |
       v
Edited Telegram status message
       |
       v
Final Codex answer
       |
       v
Telegram reply

默认后端会启动一个本地 codex app-server，首次请求会创建一个新的 Codex session。之后同一个 Telegram chat 中的请求会通过 app-server 的 thread/resume 和 turn/start 继续之前的上下文。运行中的任务可以通过 /steer 发送 steering instruction，也可以通过 /stop 中断当前 turn。

图片会保存到 CODEX_WORKDIR/.codex-telegram/uploads/ 并作为本地文件路径传给 Codex。Telegram 以“照片”方式发送时会提供压缩后的最大版本；如果需要 Codex 使用原始二进制图片，请在 Telegram 中以“文件/Document”方式发送图片。

如果你需要旧的非交互执行方式，可以设置 CODEX_BACKEND=exec。该模式仍使用 codex exec，但不支持 /steer。

环境要求

  • Python 3.10 或更高版本
  • 已安装并可在 PATH 中访问的 Codex CLI；默认后端需要 CLI 支持 codex app-server
  • 一个 Telegram Bot Token
  • 允许访问该 Bot 的 Telegram 用户 ID

安装

git clone https://github.com/TRM-coding/Codex-in-Telegram.git
cd Codex-in-Telegram

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置

  1. 在 Telegram 中通过 @BotFather 创建 Bot，并复制 Bot Token。
  2. 先只配置 TELEGRAM_BOT_TOKEN，启动一次机器人。
  3. 给机器人发送 /id，获取你的 Telegram user id。
  4. 把 user id 写入 TELEGRAM_ALLOWED_USER_IDS，重新启动机器人。

最小配置示例：

export TELEGRAM_BOT_TOKEN="123456:your-telegram-bot-token"
export TELEGRAM_ALLOWED_USER_IDS="123456789"
export CODEX_WORKDIR="/path/to/your/project"

启动：

python bot.py

Telegram 命令

命令 说明
/start 查看机器人状态和当前用户授权状态。
/help 显示命令帮助。
/id 显示 Telegram user id 和 chat id。
/codex <request> 向 Codex 发送请求。普通文本消息也会作为 Codex 请求处理。
/steer <instruction> 向当前正在运行的 Codex turn 发送 steering instruction。
/stop 中断当前正在运行的 Codex turn。
/session 查看当前 chat 绑定的 Codex session id。
/new 清除当前 session，下次请求会开启新会话。
/history 查看当前 chat 最近保存的 Codex sessions。
/resume <session_id> 切换回指定 Codex session。
/grant status 查看当前 Codex 权限模式。
/grant workspace 使用 workspace-write sandbox。
/grant read-only 使用只读 sandbox。
/grant full 使用 --dangerously-bypass-approvals-and-sandbox。

/permission、/permit、/allow 和 /xxx 是 /grant 的别名。

配置项

变量 默认值 说明
TELEGRAM_BOT_TOKEN 无 Telegram Bot Token，必填。
TELEGRAM_ALLOWED_USER_IDS 空 允许使用 Codex 的 Telegram user id，多个 ID 用逗号分隔。为空时 Codex 命令会被禁用。
CODEX_BINARY codex Codex CLI 可执行文件名或路径。
CODEX_BACKEND app-server Codex 后端。app-server 支持 /steer 和 /stop；exec 使用旧的 codex exec 路径。
CODEX_WORKDIR 当前目录 Codex 执行任务的工作目录。
CODEX_MODEL 空 传给 Codex CLI 的模型参数。
CODEX_PROFILE 空 传给 Codex CLI 的 profile 参数。
CODEX_SANDBOX workspace-write Codex sandbox 模式。
CODEX_APPROVAL never Codex approval 模式，适合 Telegram 非交互执行。
CODEX_TIMEOUT_SECONDS 900 单次 Codex 请求的最长运行时间。
CODEX_SESSION_DB CODEX_WORKDIR/codex_sessions.sqlite3 保存 Telegram chat 与 Codex session 映射的 SQLite 文件。
CODEX_EXTRA_ARGS 空 CODEX_BACKEND=exec 时附加到 codex exec 的额外参数。
CODEX_SKIP_GIT_REPO_CHECK true 如果 Codex CLI 支持，自动添加 --skip-git-repo-check。
CODEX_DANGEROUSLY_BYPASS false 启动时是否绕过 Codex approvals 和 sandbox。只应在隔离环境中使用。
MAX_CONCURRENT_CODEX_JOBS 1 同时运行的 Codex 任务数量。
LOG_LEVEL INFO 应用日志级别。
HTTPX_LOG_LEVEL WARNING HTTPX 日志级别。

systemd 部署示例

创建 /etc/systemd/system/codex-telegram.service：

[Unit]
Description=Codex Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=your-linux-user
Group=your-linux-group
WorkingDirectory=/opt/codex-to-telegram
EnvironmentFile=/opt/codex-to-telegram/.env
ExecStart=/opt/codex-to-telegram/.venv/bin/python -u /opt/codex-to-telegram/bot.py
Restart=always
RestartSec=5
KillSignal=SIGINT
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable --now codex-telegram.service
sudo systemctl status codex-telegram.service --no-pager
sudo journalctl -u codex-telegram.service -f

安全提示

  • 不要把 TELEGRAM_BOT_TOKEN 提交到 GitHub。
  • 严格限制 TELEGRAM_ALLOWED_USER_IDS，不要把 Bot 暴露给不可信用户。
  • CODEX_WORKDIR 中的文件可能被 Codex 读取或修改，部署前请确认目录范围。
  • 谨慎使用 /grant full 或 CODEX_DANGEROUSLY_BYPASS=1，它会绕过 Codex approvals 和 sandbox。
  • 如果 Bot Token 泄露，请立刻在 BotFather 中重新生成。

English

Codex in Telegram architecture

Overview

Codex to Telegram is a lightweight bridge between a Telegram bot and your local Codex CLI. Once configured, you can send Codex tasks from Telegram, run them inside a chosen working directory, and receive the final Codex answer back in the chat.

It is useful when Codex runs on a development machine, server, or home lab box, while you control it from your phone or any Telegram client.

Features

Feature Description
Run Codex from Telegram Send a plain text message, or use /codex <request> to start a Codex task.
Live status echo The bot edits the in-progress message with the Codex session, running command, and latest output.
Persistent sessions Each Telegram chat keeps its own Codex session and resumes it automatically.
Session management Use /session, /new, /history, and /resume to inspect and switch sessions.
User allowlist Only Telegram users listed in TELEGRAM_ALLOWED_USER_IDS can run Codex.
Runtime permission control Use /grant to switch between read-only, workspace-write, and full-access modes.
Long-task friendly Supports request timeouts, concurrency limits, in-flight /steer, /stop, and Telegram message chunking.
Service ready Can be deployed as a long-running systemd service.

How It Works

Telegram message
       |
       v
Python Telegram bot
       |
       v
codex app-server --listen stdio://
       |
       v
Codex app-server JSON-RPC events
       |
       v
Edited Telegram status message
       |
       v
Final Codex answer
       |
       v
Telegram reply

By default, the bot starts a local codex app-server. The first request creates a new Codex session. Later requests in the same Telegram chat continue the context with app-server thread/resume and turn/start. While a turn is running, /steer sends a steering instruction and /stop interrupts the active turn.

Images are saved under CODEX_WORKDIR/.codex-telegram/uploads/ and passed to Codex as local file paths. Telegram photo messages provide the largest compressed photo variant; send images as files/documents when Codex needs the original binary image.

Set CODEX_BACKEND=exec to use the older codex exec subprocess path. That compatibility mode does not support /steer.

Requirements

  • Python 3.10 or newer
  • Codex CLI installed and available on PATH; the default backend requires codex app-server
  • A Telegram Bot Token
  • The Telegram user ID that should be allowed to use the bot

Installation

git clone https://github.com/TRM-coding/Codex-in-Telegram.git
cd Codex-in-Telegram

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

  1. Create a bot with @BotFather and copy the Bot Token.
  2. Start the bot once with only TELEGRAM_BOT_TOKEN configured.
  3. Send /id to the bot to get your Telegram user ID.
  4. Add that user ID to TELEGRAM_ALLOWED_USER_IDS, then restart the bot.

Minimal example:

export TELEGRAM_BOT_TOKEN="123456:your-telegram-bot-token"
export TELEGRAM_ALLOWED_USER_IDS="123456789"
export CODEX_WORKDIR="/path/to/your/project"

Start the bot:

python bot.py

Telegram Commands

Command Description
/start Show bot status and your authorization status.
/help Show the command reference.
/id Show your Telegram user ID and chat ID.
/codex <request> Send a request to Codex. Plain text messages are also treated as Codex requests.
/steer <instruction> Send a steering instruction to the currently running Codex turn.
/stop Interrupt the currently running Codex turn.
/session Show the current Codex session ID for this chat.
/new Clear the current session. The next request starts a fresh session.
/history List recent Codex sessions saved for this chat.
/resume <session_id> Switch back to a specific Codex session.
/grant status Show the current Codex permission mode.
/grant workspace Use the workspace-write sandbox.
/grant read-only Use the read-only sandbox.
/grant full Use --dangerously-bypass-approvals-and-sandbox.

/permission, /permit, /allow, and /xxx are aliases for /grant.

Environment Variables

Variable Default Description
TELEGRAM_BOT_TOKEN none Telegram Bot Token. Required.
TELEGRAM_ALLOWED_USER_IDS empty Comma-separated Telegram user IDs allowed to run Codex. Codex commands are disabled when empty.
CODEX_BINARY codex Codex CLI binary name or path.
CODEX_BACKEND app-server Codex backend. app-server supports /steer and /stop; exec uses the older codex exec path.
CODEX_WORKDIR current directory Working directory where Codex runs.
CODEX_MODEL empty Model argument passed to Codex CLI.
CODEX_PROFILE empty Profile argument passed to Codex CLI.
CODEX_SANDBOX workspace-write Codex sandbox mode.
CODEX_APPROVAL never Codex approval mode, suitable for non-interactive Telegram execution.
CODEX_TIMEOUT_SECONDS 900 Maximum runtime for one Codex request.
CODEX_SESSION_DB CODEX_WORKDIR/codex_sessions.sqlite3 SQLite file used to map Telegram chats to Codex sessions.
CODEX_EXTRA_ARGS empty Extra arguments appended to codex exec when CODEX_BACKEND=exec.
CODEX_SKIP_GIT_REPO_CHECK true Adds --skip-git-repo-check when supported by the Codex CLI.
CODEX_DANGEROUSLY_BYPASS false Start with approvals and sandbox bypassed. Use only in an isolated environment.
MAX_CONCURRENT_CODEX_JOBS 1 Number of Codex jobs allowed to run at the same time.
LOG_LEVEL INFO Application log level.
HTTPX_LOG_LEVEL WARNING HTTPX log level.

systemd Example

Create /etc/systemd/system/codex-telegram.service:

[Unit]
Description=Codex Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=your-linux-user
Group=your-linux-group
WorkingDirectory=/opt/codex-to-telegram
EnvironmentFile=/opt/codex-to-telegram/.env
ExecStart=/opt/codex-to-telegram/.venv/bin/python -u /opt/codex-to-telegram/bot.py
Restart=always
RestartSec=5
KillSignal=SIGINT
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

Enable the service:

sudo systemctl daemon-reload
sudo systemctl enable --now codex-telegram.service
sudo systemctl status codex-telegram.service --no-pager
sudo journalctl -u codex-telegram.service -f

Security Notes

  • Never commit TELEGRAM_BOT_TOKEN to GitHub.
  • Keep TELEGRAM_ALLOWED_USER_IDS restricted to trusted users.
  • Codex may read or modify files inside CODEX_WORKDIR; choose that directory carefully.
  • Be careful with /grant full and CODEX_DANGEROUSLY_BYPASS=1; they bypass Codex approvals and sandboxing.
  • Regenerate the token in BotFather immediately if it leaks.

Built for people who want to use Codex from wherever Telegram is available.

About

A plugin makes you can program with codex in telegram!

Resources

Readme
Activity

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages