# 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

```text
/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:

```text
이건 업무 이력으로 저장해줘. 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

1. Copy `.env.example` to `.env`.
2. Fill `TELEGRAM_BOT_TOKEN`.
3. Use `/whoami` to find your Telegram user id and set
   `ALLOWED_TELEGRAM_USER_IDS`.
4. 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.