NAS Telegram Codex Bridge

Telegram bridge for a NAS-hosted Codex app-server.

The bot does not interpret normal chat messages. It forwards them to Codex and only keeps connection-management commands.

Commands

/start
/help
/whoami
/repo <path-under-workspace-root>
/ask <prompt>
/new
/status
/settings
/set_model <model|latest|default>
/set_effort <minimal|low|medium|high|xhigh|default>
/set_speed <standard|fast|보통|고속|default>
/fast <on|off|status>
/models
/schedules
/records
/todos
/purchases
/birthdays
/sessions
/sessions archived
/use_session <thread_id>
/archive_session [thread_id]
/unarchive_session <thread_id>

ALLOW_PLAIN_TEXT=true makes regular Telegram messages behave like /ask.

/settings, /models, /schedules, /records, and /sessions return inline buttons, so you can change speed/model/reasoning settings, delete schedules, manage personal records, and switch or archive sessions without copying ids.

Runtime settings

Runtime settings are stored in BOT_STATE_PATH and applied to new turns:

model, for example gpt-5.5
reasoning_effort: minimal, low, medium, high, or xhigh
speed_mode: standard or fast

Changing these settings closes existing persistent WebSocket clients. The next Telegram message reconnects with the updated settings. Fast mode requires a supported model/account; if the local Codex app-server rejects an override, the bridge retries with narrower settings rather than failing the whole turn.

The model picker first tries codex debug models inside the NAS container and builds buttons from the model catalog Codex sees. If that fails, it falls back to a short built-in list.

Scheduling

The bridge registers a local MCP server named telegram_bridge in $CODEX_HOME/config.toml. Codex can call these tools when the user asks for scheduled Telegram notifications:

telegram_create_schedule
telegram_list_schedules
telegram_delete_schedule

Personal assistant records

Codex can persist personal assistant records to the same NAS-backed state file. Use natural language in Telegram, for example:

이건 업무 이력으로 저장해줘. 2025-09-15부터 2026-04-15까지 전국통합데이터 개방확대 사업에 참여했어.
이건 할 일로 기억해줘. 다음 주까지 신세계 TV쇼핑 채팅 연동 QA 정리.
구매 후보로 저장해줘. 모니터암 가격 8만원 이하가 되면 사고 싶어.
어머니 생일은 5월 12일이야. 기억해줘.

Codex uses these MCP tools:

telegram_save_personal_record
telegram_list_personal_records
telegram_update_personal_record
telegram_delete_personal_record

Record categories are work_log, todo, purchase, birthday, contact, note, and preference. Telegram commands /records, /todos, /purchases, and /birthdays show records with management buttons.

The bridge scheduler runs inside the Telegram bot process. When a schedule is due, it calls Codex app-server and sends the result back to the stored Telegram chat id.

Deployment

Copy .env.example to .env.
Fill TELEGRAM_BOT_TOKEN.
Use /whoami to find your Telegram user id and set ALLOWED_TELEGRAM_USER_IDS.
Run docker compose up -d --build, or use deploy/deploy.ps1 for the NAS.

Notes

Codex state and auth live under the mounted codex-home volume.
The app-server listens on ws://127.0.0.1:4500 inside the container.
Normal chat messages use a persistent app-server WebSocket per Telegram chat.
Idle persistent WebSockets are closed after PERSISTENT_WS_IDLE_SECONDS.
Session commands call app-server thread APIs.

3.6 KiB Raw Blame History