164 lines
5.9 KiB
Markdown
164 lines
5.9 KiB
Markdown
# 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>
|
|
/work <prompt>
|
|
/usage
|
|
/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` forwards regular Telegram messages to Codex. Set
|
|
`WORK_TELEGRAM_CHAT_IDS` to one or more group chat ids to split the bot into
|
|
profiles: listed chats run as `work` chats with full-access repository turns,
|
|
and every other chat runs as a personal `assistant` chat for schedules,
|
|
reminders, saved records, briefings, and lightweight Gitea/status lookup. In
|
|
Telegram groups, disable bot privacy with BotFather if you want the bot to
|
|
receive normal non-command messages.
|
|
|
|
In `work` chats, normal messages are routed to the Codex work session by
|
|
default. The bridge only handles narrow operational intents directly, such as
|
|
usage checks, cancellation, or conversational status questions like "지금 뭐해?".
|
|
Messages sent while a work turn is still running are queued and forwarded as
|
|
follow-up instructions after the current turn completes.
|
|
|
|
On Synology/NAS Docker deployments, keep `CODEX_WRITE_SANDBOX` set to
|
|
`danger-full-access`. The stricter `workspace-write` sandbox may fail with
|
|
bubblewrap namespace errors inside the container. Personal assistant chats use
|
|
`CODEX_ASSISTANT_SANDBOX`, which defaults to `read-only`.
|
|
|
|
If no `/repo` is set, the bridge tries to auto-select a workspace folder when a
|
|
Telegram prompt mentions an exact folder name such as `card_game` or
|
|
`nas_connection`. Use `/repo <name>` when you want to pin the workspace
|
|
explicitly.
|
|
|
|
`/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.
|
|
`/usage` asks the local Codex app-server for account, plan, rate-limit, and
|
|
credit information when the installed Codex version exposes it.
|
|
|
|
## 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.
|
|
|
|
## Gitea integration
|
|
|
|
Set these optional values in `.env` to let Codex manage Gitea repositories,
|
|
commits, issues, pull requests, and HTTPS git authentication from Telegram:
|
|
|
|
```env
|
|
GITEA_BASE_URL=https://gitea.example.com
|
|
GITEA_USERNAME=your-gitea-user
|
|
GITEA_EMAIL=you@example.com
|
|
GITEA_TOKEN=your-personal-access-token
|
|
GITEA_DEFAULT_OWNER=your-gitea-user-or-org
|
|
GITEA_DEFAULT_REPO=your-default-repo
|
|
GITEA_GIT_AUTH_ENABLED=true
|
|
```
|
|
|
|
Codex receives Gitea MCP tools for repository, commit, issue, branch, and
|
|
pull-request metadata. The container also configures `GIT_ASKPASS` so HTTPS `git clone`,
|
|
`fetch`, and `push` can use the token without embedding it in command lines.
|
|
|
|
Example Telegram workflow:
|
|
|
|
```text
|
|
/repo nas_connection
|
|
/work 이슈 #3을 확인하고 코드 수정 후 테스트해. 변경사항을 codex/gitea-tools 브랜치로 커밋하고 push한 뒤 PR을 열어줘.
|
|
```
|
|
|
|
## 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 full-access Codex turns with a persistent app-server
|
|
WebSocket per Telegram chat when available.
|
|
- Idle persistent WebSockets are closed after `PERSISTENT_WS_IDLE_SECONDS`.
|
|
- Session commands call app-server thread APIs.
|