codex-telegram-bot/README.md

Codex Telegram Bot

Docker Compose runs only the Go Telegram bot. Codex runs on the host through codex app-server and is reached through a bind-mounted Unix socket.

Setup

1. Copy .env.example to .env and set TELEGRAM_BOT_TOKEN, HOST_CODEX_SOCKET, and HOST_UPLOAD_DIR.

2. Start the host Codex app-server:

   scripts/start-codex-app-server
   

   The script starts Codex detached, writes run/codex-app-server.pid, logs to run/codex-app-server.log, and is idempotent if the socket is already live.

3. Add at least one Telegram user and workspace:

   scripts/allow-user 123456789 username
   scripts/add-workspace /absolute/path/to/workspace "Workspace name" --default
   

4. Build the bot binary when source changes:

   scripts/build-bot
   

5. Start or restart the bot without rebuilding:

   docker compose up -d
   

   For normal restarts, use docker compose restart bot. The container runs ./bin/codex-telegram-bot mounted read-only into Alpine; Compose does not compile Go code.

Commands

The bot accepts one-to-one chats from allowlisted Telegram user IDs only. It rejects group, supergroup, and channel updates in code.

Supported commands: /start, /help, /new, /threads, /resume, /fork, /archive, /status, /cancel, /workspaces, /workspace, /model, /sandbox, /diff. /model lists available Codex models as inline buttons, then shows reasoning-effort buttons for the selected model.

Plain text continues the active Codex thread and creates one if needed. Telegram images are staged under HOST_UPLOAD_DIR and sent as localImage inputs. Other uploaded documents are staged and passed to Codex as host-visible file paths.

Notes

• HOST_UPLOAD_DIR must be the same absolute path inside the bot container and on the host so host Codex can read staged files.
• HOST_CODEX_SOCKET must point to the host app-server socket. HOST_CODEX_RUN_DIR is mounted into the bot container at the same absolute path so socket recreation is visible without rebuilding.
• Use long polling for the MVP; webhooks are not required.