2b0da9f508
Use available approval decisions from the app-server schema, preserve structured policy decisions in callbacks, and keep approval rendering aligned with normal tool-call output. Also simplify thread commands, clear stale active turns more carefully, and update command/help docs.
51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
# 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`, `HOST_CODEX_RUN_DIR`, `HOST_UPLOAD_DIR`, `HOST_CODEX_HOME`, and `HOST_PLAYGROUND_DIR`.
|
|
2. Start the host Codex app-server:
|
|
|
|
```sh
|
|
scripts/start-codex-app-server start
|
|
```
|
|
|
|
The script supports `start`, `stop`, `status`, `check-updates [-y]`, and the alias `check-upgrade [-y]`. `start` launches Codex detached, writes `run/codex-app-server.pid`, logs to `run/codex-app-server.log`, and is idempotent if the socket is already live. `check-updates` compares the local `codex` binary with the latest OpenAI Codex GitHub release. With `-y`, it downloads and validates the matching platform archive before stopping a running app-server. If the app-server is running, the final stop/replace/start step is handed to a detached worker so the upgrade can complete even when invoked from Codex itself. If the upgraded server fails to start, the worker restores the previous binary and starts it again.
|
|
|
|
3. Add at least one Telegram user and workspace:
|
|
|
|
```sh
|
|
scripts/allow-user 123456789 username
|
|
scripts/add-workspace "$PWD" "Workspace name" --default
|
|
```
|
|
|
|
4. Build the bot binary when source changes:
|
|
|
|
```sh
|
|
scripts/build-bot
|
|
```
|
|
|
|
5. Start or restart the bot without rebuilding:
|
|
|
|
```sh
|
|
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`, `/thread`, `/rename`, `/fork`, `/archive`, `/status`, `/cancel`, `/workspaces`, `/workspace`, `/model`, `/sandbox`, `/pic`, `/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. `/pic PROMPT` starts a dedicated Codex image-generation turn and sends generated images back as Telegram photos. 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.
|
|
- `HOST_PLAYGROUND_DIR` should point to the shared playground/workspace root mounted at the same absolute path, so assistant photo directives can reference workspace-local image files that the bot container can read.
|
|
- Use long polling for the MVP; webhooks are not required.
|