A Telegram bot that gives you remote access to @openai/codex through a Node.js runtime with two Codex backends: the Codex SDK and the legacy CLI/PTy path.
It is strictly inspired by RichardAtCT/claude-code-telegram, but this project is implemented for CodeX SDK/CLI + MCP + Subagent routing.
Telegram bot for Claude Code and Codex CLI with MCP routing, multi-agent orchestration, cron jobs, and access controls.
Yıldızlar
35
Araçlar
—
Çalışma süresi
—
What Is This?
This bot connects Telegram to Codex and routes tasks to the right execution surface:
Coding tasks -> Codex SDK threads or Codex CLI/PTy sessions
/gh confirm -> confirm the pending GitHub write action and execute it
plain-text write requests such as create repo ..., commit, or push are intercepted and converted into guidance; they no longer execute GitHub writes directly
/gh run tests -> launch test job
/gh test status <jobId> -> read test status/output tail
Telegram adaptation notes:
Plain text messages behave like a normal Codex conversation turn
/exec runs a one-off Codex task and does not overwrite the saved project conversation slot
/auto runs a one-off Codex task with approvalPolicy=never on the SDK backend, or codex exec --full-auto on the CLI backend
/new is implemented by the bot and resets the current chat session
/new only clears the current project's saved Codex conversation slot
/status is implemented by the bot and reports local runtime state
/status also surfaces the internal superpowers workflow system and the last detected workflow phase for the current chat/project session
/repo is implemented by the bot and switches the per-chat working directory inside WORKSPACE_ROOT
/skill is implemented by the bot and keeps per-chat skill switches in runtime state
/skill only lists toggleable bot skills; superpowers is shown as an internal workflow, not a toggleable skill
/dev is implemented by the bot and manages one frontend server per repo workdir, shared across chats
/dev start prefers package.json script dev and falls back to start
/sh is implemented by the bot, never invokes a shell interpreter, and only accepts configured command prefixes
/sh is read-only by default; dangerous prefixes can be configured and require --confirm when writable mode is enabled
/plan translates to a planning-only prompt instead of passing a raw /plan slash command to Codex
If another chat already has an active Codex run in the same workdir, the bot blocks the new request and requires /continue for a one-shot override
The default system language is English; use /language zh or /language zh-HK for localized bot responses
/verbose off keeps Telegram output quiet by hiding fallback, startup, and session-exit notices for the current chat
Streaming and Reasoning Visualization
Codex output is streamed with throttled editMessageText updates.
Throttle: controlled by STREAM_THROTTLE_MS (default 1200)
Long output: auto-chunked to Telegram-safe message sizes
MarkdownV2: escaped to avoid parse failures
Reasoning tags: <think>...</think> extracted and rendered as:
spoiler (||...||, default)
quote block (if REASONING_RENDER_MODE=quote)
On CODEX_BACKEND=sdk, Telegram streams structured Codex SDK events and persists thread IDs per project
On CODEX_BACKEND=cli, the bot prefers PTY sessions; if node-pty cannot spawn on the current host, it falls back to codex exec
In CLI exec fallback mode, Telegram output is cleaned to hide the Codex banner, raw tool trace, mcp startup, and duplicate tokens used footer
On macOS, startup auto-repairs node-pty helper execute permissions before the first PTY session
Project-Scoped Conversation State
Conversation state is now tracked per chat + project, not just per chat.
When you switch with /repo <name>, the bot keeps that project's last Codex session id in runtime state
When you switch back to the same project later, the next plain-text task resumes that project's Codex thread/session
/new clears only the current project's saved conversation slot; other projects in the same Telegram chat are untouched
/exec, /auto, and /plan stay one-off by design and do not replace the saved project conversation
On the SDK backend, project restore uses resumeThread(threadId)
On the CLI backend, project restore uses PTY resume or codex exec resume
Workspace Contention Guard
The bot now blocks a second Codex run when another bot-managed chat already has an active Codex task in the same workdir.
the warning is strong by default because simultaneous writes in the same workdir are easy to corrupt
/continue replays the most recently blocked request once for the current chat
switching projects clears the pending blocked request
this guard only sees bot-managed chats in this process; if you also use Codex directly in a terminal, use a separate git worktree to avoid conflicts
Frontend Debugging Layer
The bot includes a minimal repo-scoped frontend runtime layer:
/dev start starts the current repo's frontend command
/dev stop stops it
/dev status shows whether it is running
/dev logs returns the recent output tail
/dev url returns the first detected local URL from logs
Selection rules:
prefer package.json script dev
if dev is missing, fall back to start
keep only one active frontend server per repo workdir
do not expose arbitrary shell execution through /dev
Backend Selection
Choose the execution backend with CODEX_BACKEND:
sdk - preferred for new installs; avoids PTY fragility and uses persistent Codex SDK threads
cli - legacy backend; uses PTY when available and falls back to codex exec
If CODEX_SDK_SANDBOX_MODE is unset, the bot now defaults SDK threads to Full Access: danger-full-access with approvalPolicy=never. Set it explicitly to workspace-write or read-only only if you want a more restricted mode.
GITHUB_TOKEN=ghp_xxx
GITHUB_DEFAULT_WORKDIR=.
GITHUB_DEFAULT_BRANCH=main
E2E_TEST_COMMAND=npx playwright test --reporter=line
CI And Release Automation
GitHub Actions now includes:
CI workflow on push and pull request
Telegram Smoke manual workflow for live bot-token validation when repository secrets are configured
Release workflow on v* tags, which reruns validation and publishes a GitHub Release
Repository secrets for live smoke checks:
TELEGRAM_BOT_TOKEN
TELEGRAM_EXPECTED_USERNAME (optional)
TELEGRAM_SMOKE_CHAT_ID (optional)
Keep live verification output out of git history and release notes. Bot usernames, thread IDs, and chat IDs are environment-specific operator data and should be configured by each user locally or through GitHub secrets.
Recommended local release gate:
BOT_TOKEN=dummy-token ALLOWED_USER_IDS=1 npm run release:check
npm run healthcheck:live
npm run telegram:smoke
v1.0.0 should only be tagged after the full release gate, Telegram smoke checks, and repository metadata sync are complete. The detailed checklist and topic sync command live in release.md.
Skills are chat-level routing switches: each chat can enable or disable github and mcp independently
Codex's own MCP remains separate and is not managed through these bot commands
Runtime state is persisted to STATE_FILE, so /mcp enable|disable, /skill on|off, /language, /verbose, and per-project Codex conversation slots survive bot restarts
Troubleshooting
Bot not responding: verify BOT_TOKEN and ALLOWED_USER_IDS
Telegram API blocked: set TELEGRAM_PROXY_URL (HTTP proxy like http://127.0.0.1:7890) or run a local Bot API server and set TELEGRAM_API_BASE
Codex not producing output: verify CODEX_BACKEND, CODEX_COMMAND, and CODEX_WORKDIR
SDK backend cannot resume: verify the host still has access to ~/.codex/sessions and that the saved thread id belongs to the same working directory
Markdown parse errors: reduce output size/context; check special characters in tool output
MCP failures: run /mcp tools <server> first to validate server availability
GitHub API failures: verify GITHUB_TOKEN scope (repo) and account permissions
Duplicate MCP suspicion: ensure coding tasks are routed directly to Codex, and bot MCP is used only for /mcp
posix_spawnp failed: this usually means the node-pty helper lost execute permissions; startup now auto-repairs it, and npm run healthcheck reports the result
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Sorular
CodexClaw nasıl kurulur?
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
CodexClaw için API anahtarı gerekiyor mu?
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
CodexClaw hangi aktarımı kullanıyor?
CodexClaw yerel olarak stdio üzerinden çalışır.
CodexClaw en son ne zaman kontrol edildi?
Son kontrol: 2026-10-28. Telegram bot for Claude Code and Codex CLI with MCP routing, multi-agent orchestration, cron jobs, and access controls.