GitHub - xflyhack/TeleCodex: Control OpenAI Codex on your Mac remotely via Telegram — send a message, get it done. · GitHub
Skip to content

xflyhack/TeleCodex

BranchesTags

Folders and files

Repository files navigation

TeleCodex

English | 中文

English

TeleCodex is a lightweight Telegram bot that lets you run OpenAI Codex CLI tasks remotely from Telegram.

Features

  • Start a Codex task with /codex <prompt>.
  • Run multiple Codex tasks in parallel using background threads.
  • Prefix every task with an ID such as [T0001].
  • Reply all task progress messages to the original Telegram command.
  • Include the Codex session/thread ID in progress messages for later follow-up.
  • Stream Codex JSON events into Telegram progress updates.
  • Send heartbeat messages, long-running warnings, and hard-timeout notifications.

Requirements

  • Python 3.10+
  • requests
  • Node.js / npm
  • Codex CLI installed and authenticated
  • A Telegram bot token from BotFather
  • Your Telegram chat ID

Install Codex CLI if needed:

npm install -g @openai/codex
codex --version

Get a Telegram Bot Token

  1. Open Telegram and search for @BotFather.

  2. Start a chat with BotFather and send:

    /newbot

  3. Follow the prompts:

    • Choose a display name for your bot.
    • Choose a username ending in bot, for example my_codex_bot.

  4. BotFather returns an HTTP API token like:

    1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  5. Save that value as TELEGRAM_BOT_TOKEN in your .env file.

If your token is leaked, go back to BotFather, use /revoke, and generate a new token.

Get Your Telegram Chat ID

Option A: use your bot updates directly:

  1. Send any message, such as /start, to your new bot.

  2. In a terminal, run:

    curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates"

  3. Find message.chat.id in the JSON response.

  4. Save that number as TELEGRAM_ALLOWED_CHAT_ID.

Option B: use a helper bot:

  1. Search Telegram for a chat-id helper bot, for example @userinfobot.
  2. Start it and copy the returned numeric ID.
  3. Save that number as TELEGRAM_ALLOWED_CHAT_ID.

Setup

Clone the repo:

git clone git@github.com:xflyhack/TeleCodex.git
cd TeleCodex

Create a virtual environment:

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

Create your environment file:

cp .env.example .env

Edit .env and replace the placeholders:

TELEGRAM_BOT_TOKEN=your_botfather_token
TELEGRAM_ALLOWED_CHAT_ID=your_telegram_chat_id
TELECODEX_WORK_DIR=~/telegram_bot

Load the environment and run:

set -a
source .env
set +a
.venv/bin/python telegram_codex_bot.py

Configuration

Required variables:

Variable Description
TELEGRAM_BOT_TOKEN Telegram bot token from BotFather. Do not commit this value.
TELEGRAM_ALLOWED_CHAT_ID Only this Telegram chat ID can control the bot.

Optional variables:

Variable Default Description
TELECODEX_WORK_DIR ~/telegram_bot Working directory where Codex commands run.
TELECODEX_HEARTBEAT_INTERVAL 30 Seconds between heartbeat messages.
TELECODEX_WARN_TIMEOUT 180 Seconds before sending a long-running warning.
TELECODEX_HARD_TIMEOUT 300 Seconds before force-killing a Codex task.

Usage

In Telegram:

/start
/help
/pwd
/ls
/codex Run pwd and tell me the current directory

For each /codex command, TeleCodex replies to the original Telegram message and prefixes progress messages with a task ID. After Codex starts, messages also include the Codex session/thread ID.

Example:

[T0001] [`019e31a7-4299-7983-91e2-4447aa75981b`]
💬 Codex reply
Current directory is `/Users/you/project`.

Security Notes

  • Never hard-code or commit your Telegram bot token.
  • .env is ignored by Git.
  • Keep TELEGRAM_ALLOWED_CHAT_ID set so unknown users cannot control your machine.
  • This bot runs Codex with danger-full-access; only run it on a machine and chat account you trust.
  • If a token was ever committed or shared, revoke it in BotFather and generate a new one.

中文

TeleCodex 是一个轻量级 Telegram Bot，可以让你直接在 Telegram 里远程调用 OpenAI Codex CLI 执行任务。

功能特性

  • 使用 /codex <任务描述> 启动 Codex 任务。
  • 支持多个 Codex 任务后台并行执行。
  • 每个任务都有独立任务 ID，例如 [T0001]。
  • 所有任务进度都会回复到原始 Telegram 指令消息，方便区分归属。
  • 进度消息会携带 Codex session/thread ID，方便后续追问或定位。
  • 将 Codex JSON 事件流转换成 Telegram 进度上报。
  • 支持心跳消息、耗时过长提醒和强制超时通知。

环境要求

  • Python 3.10+
  • requests
  • Node.js / npm
  • 已安装并登录 Codex CLI
  • 通过 BotFather 获取的 Telegram Bot Token
  • 你的 Telegram Chat ID

如果还没有安装 Codex CLI：

npm install -g @openai/codex
codex --version

获取 Telegram Bot Token

  1. 打开 Telegram，搜索 @BotFather。

  2. 和 BotFather 开始对话，发送：

    /newbot

  3. 按提示完成创建：

    • 输入 Bot 的显示名称。
    • 输入 Bot 的用户名，用户名必须以 bot 结尾，例如 my_codex_bot。

  4. BotFather 会返回一个 HTTP API Token，格式类似：

    1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  5. 把这个值填写到 .env 文件里的 TELEGRAM_BOT_TOKEN。

如果 Token 泄露，请回到 BotFather 使用 /revoke 撤销旧 Token，并重新生成。

获取 Telegram Chat ID

方式 A：通过你的 Bot 接口获取：

  1. 先给你的 Bot 发送任意消息，例如 /start。

  2. 在终端执行：

    curl "https://api.telegram.org/bot<你的BotToken>/getUpdates"

  3. 在返回的 JSON 中找到 message.chat.id。

  4. 把这个数字填写到 .env 文件里的 TELEGRAM_ALLOWED_CHAT_ID。

方式 B：使用辅助 Bot：

  1. 在 Telegram 搜索 Chat ID 查询工具，例如 @userinfobot。
  2. 启动后复制它返回的数字 ID。
  3. 把这个数字填写到 .env 文件里的 TELEGRAM_ALLOWED_CHAT_ID。

安装配置

克隆仓库：

git clone git@github.com:xflyhack/TeleCodex.git
cd TeleCodex

创建 Python 虚拟环境：

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

创建环境变量文件：

cp .env.example .env

编辑 .env，替换占位符：

TELEGRAM_BOT_TOKEN=你的BotFatherToken
TELEGRAM_ALLOWED_CHAT_ID=你的TelegramChatID
TELECODEX_WORK_DIR=~/telegram_bot

加载环境变量并运行：

set -a
source .env
set +a
.venv/bin/python telegram_codex_bot.py

配置说明

必填变量：

变量 说明
TELEGRAM_BOT_TOKEN BotFather 返回的 Telegram Bot Token，不能提交到 Git。
TELEGRAM_ALLOWED_CHAT_ID 只有这个 Telegram Chat ID 可以控制 Bot。

可选变量：

变量 默认值 说明
TELECODEX_WORK_DIR ~/telegram_bot Codex 命令运行的工作目录。
TELECODEX_HEARTBEAT_INTERVAL 30 心跳消息发送间隔，单位秒。
TELECODEX_WARN_TIMEOUT 180 任务运行多久后发送耗时较长提醒，单位秒。
TELECODEX_HARD_TIMEOUT 300 任务最长运行时间，超过后强制终止，单位秒。

使用方法

在 Telegram 中发送：

/start
/help
/pwd
/ls
/codex 运行 pwd，然后告诉我当前目录

每个 /codex 指令都会作为一个独立任务执行。TeleCodex 会把任务进度回复到原始指令消息，并在每条消息前加任务 ID。Codex 启动后，消息中也会携带 Codex session/thread ID。

示例：

[T0001] [`019e31a7-4299-7983-91e2-4447aa75981b`]
💬 Codex 回复
当前目录是 `/Users/you/project`。

安全提醒

  • 不要把 Telegram Bot Token 写死在代码里，也不要提交到 GitHub。
  • .env 已经被 .gitignore 忽略。
  • 一定要设置 TELEGRAM_ALLOWED_CHAT_ID，避免陌生人控制你的机器。
  • 当前脚本会以 danger-full-access 模式运行 Codex，只建议在你信任的机器和 Telegram 账号下使用。
  • 如果 Token 曾经泄露，请立刻在 BotFather 撤销并重新生成。

License

MIT

About

Control OpenAI Codex on your Mac remotely via Telegram — send a message, get it done.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages