Monotony0315/telegram-codex-control
GitHub: Monotony0315/telegram-codex-control
通过 Telegram Bot 安全地远程控制 Codex CLI 进行软件开发，具备策略管控、审计日志和多种传输模式。
Stars: 1 | Forks: 0
# Telegram Codex 控制
Telegram Codex CLI 远程控制工具，具备基于策略的访问控制、polling/webhook 传输模式以及安全的发布工具链。
关键词：`telegram bot`、`codex cli`、`remote development`、`developer automation`、`webhook`、`sbom`、`signed release`。
## 功能特性
- 指令集：
- `/status`
- `/chat`（`/chat reset`，启用交互模式时，纯文本路由至此）
- `/run `（需确认）
- `/autopilot `（需确认）
- `/codex `（需确认）
- `/files [relative_dir]`
- `/search [relative_dir_or_file]`
- `/read [max_lines]`
- `/download `
- `/report `（需确认；运行针对 `reports/` 的报告撰写 `/run` 提示词）
- `/skills [filter]`
- `/skill `（需确认）
- `/prompts [filter]`
- `/prompt `（需确认）
- `/confirm `
- `/cancel`
- `/logs`
- `/help`
- 传输模式：
- `polling`（默认）
- `webhook`（Telegram `setWebhook` + 本地 HTTP 接收器）
- 安全性：
- 严格的用户/聊天白名单
- 可选的指令策略（`COMMAND_POLICY_PATH`）
- Telegram 文档上传接入工作区（通过 `/upload` 策略门控）
- 仅参数子进程执行（`create_subprocess_exec`，无 shell）
- 日志和出站消息中的 token/secret 脱敏
- 运维：
- SQLite 状态存储 + JSONL 审计
- 当主 Codex 指令因 DNS/网络限制失败时，可选自动回退至 `CODEX_COMMAND_FALLBACK`
- 可选的 Rust `CODEX_LIVE_CORE_COMMAND` 辅助工具，用于标准化 `/chat` 事件流
- macOS `launchd` 和 Linux `systemd --user` 服务脚本
- 包含 SBOM + 制品签名/校验和的发布流水线
## 快速开始
```
cd /path/to/telegram-codex-control
./scripts/bootstrap.sh
```
更新 `.env`：
```
TELEGRAM_BOT_TOKEN=123456:replace-me
ALLOWED_USER_ID=123456789
ALLOWED_CHAT_ID=123456789
WORKSPACE_ROOT=$HOME/Projects
UPLOAD_DIR=.data/uploads
CODEX_COMMAND=/absolute/path/to/codex
# 可选：CODEX_LIVE_CORE_COMMAND=/absolute/path/to/tgcc-live-core
TELEGRAM_INTERACTIVE_MODE=true
TELEGRAM_TRANSPORT=polling
# COMMAND_POLICY_PATH=./command-policy.example.json
```
本地运行：
```
set -a; source .env; set +a
PYTHONPATH=src .venv/bin/python -m telegram_codex_control.main
```
手动构建或刷新可选的 Rust live-core 辅助工具：
```
./scripts/build-live-core.sh
```
## Webhook 模式
设置：
```
TELEGRAM_TRANSPORT=webhook
TELEGRAM_WEBHOOK_PUBLIC_URL=https://your-public-host.example.com
TELEGRAM_WEBHOOK_LISTEN_HOST=127.0.0.1
TELEGRAM_WEBHOOK_LISTEN_PORT=8080
TELEGRAM_WEBHOOK_PATH=/telegram/webhook
TELEGRAM_WEBHOOK_SECRET_TOKEN=replace-me
```
注意：
- `TELEGRAM_WEBHOOK_PUBLIC_URL` 必须是 HTTPS 且可被 Telegram 访问。
- `TELEGRAM_WEBHOOK_SECRET_TOKEN` 在 webhook 模式下是必需的。
- 将 `PUBLIC_URL + WEBHOOK_PATH` 路由到本服务。
- 在 polling 模式下，为了兼容性会自动移除 webhook 注册。
## 指令策略
将 `COMMAND_POLICY_PATH` 设置为 JSON 文件路径。
使用 `command-policy.example.json` 作为模板。
示例：
```
{
"default": { "allow": ["/status", "/chat", "/files", "/search", "/read", "/download", "/report", "/logs", "/help"] },
"rules": [
{ "user_id": 123, "chat_id": 456, "allow": ["*"], "deny": [] },
{
"user_id": 111,
"chat_id": -100222,
"allow": ["/status", "/files", "/read", "/logs"],
"deny": ["/run", "/autopilot", "/codex", "/chat", "/search", "/download", "/report", "/upload"]
}
]
}
```
## 后台服务（自启动）
安装/启动：
```
./scripts/install-service.sh
```
状态：
```
./scripts/status-service.sh
```
卸载：
```
./scripts/uninstall-service.sh
```
## 异地模式（无需 launchctl/ps）
注意：
- 运行 `install-service` 模式或异地模式，两者不可同时运行。
启动：
```
./scripts/offsite-start.sh
```
状态：
```
./scripts/offsite-status.sh
```
停止：
```
./scripts/offsite-stop.sh
```
启用 login-shell 自启动（默认配置文件：`~/.zprofile`）：
```
./scripts/install-offsite-login-autostart.sh
```
禁用 login-shell 自启动：
```
./scripts/uninstall-offsite-login-autostart.sh
```
用于测试/特殊情况的可选配置文件覆盖：
```
OFFSITE_LOGIN_PROFILE_PATH=~/.zshrc ./scripts/install-offsite-login-autostart.sh
```
可选 `.env` 调优：
```
OFFSITE_STALE_TIMEOUT_SECONDS=900
OFFSITE_CHECK_INTERVAL_SECONDS=15
```
## 安全发布
构建 + SBOM + 签名/校验和：
```
./scripts/release-secure.sh
```
可选签名设置：
- OpenSSL 密钥：
- `RELEASE_PRIVATE_KEY_PATH=/path/to/private.pem`
- GPG 密钥：
- `RELEASE_GPG_KEY_ID=`
- 强制签名：
- `REQUIRE_ARTIFACT_SIGNATURES=1`
对于 GitHub 标签发布，工作流需要 `RELEASE_PRIVATE_KEY_PEM` 密钥并强制签名。
## 环境变量
- `TELEGRAM_BOT_TOKEN`（必填）
- `ALLOWED_USER_ID`（必填，整数）
- `ALLOWED_CHAT_ID`（必填，整数）
- `WORKSPACE_ROOT`（默认：若 `~/Projects` 存在则使用，否则为 `~`）
- `UPLOAD_DIR`（默认：`.data/uploads`，必须解析到 `WORKSPACE_ROOT` 下）
- `DB_PATH`（默认：`.data/state.db`）
- `AUDIT_LOG_PATH`（默认：`.data/audit.jsonl`）
- `CODEX_COMMAND`（默认：`codex`）
- `CODEX_COMMAND_FALLBACK`（可选；若设置，当 DNS 受限的作业/聊天轮次失败时，daemon 会使用此指令重试）
- `CODEX_LIVE_CORE_COMMAND`（可选；若设置，`/chat` 在回退到直接 Python 子进程路径之前，使用 Rust 辅助工具进行标准化实时事件流处理）
- `TELEGRAM_INTERACTIVE_MODE`（默认：`true`；启用时，纯文本作为 `/chat ` 处理）
- `COMMAND_POLICY_PATH`（可选）
- `TELEGRAM_TRANSPORT`（`polling` 或 `webhook`，默认 `polling`）
- `TELEGRAM_WEBHOOK_PUBLIC_URL`（webhook 模式必填）
- `TELEGRAM_WEBHOOK_LISTEN_HOST`（默认 `127.0.0.1`）
- `TELEGRAM_WEBHOOK_LISTEN_PORT`（默认 `8080`）
- `TELEGRAM_WEBHOOK_PATH`（默认 `/telegram/webhook`）
- `TELEGRAM_WEBHOOK_SECRET_TOKEN`（可选）
- `POLL_TIMEOUT_SECONDS`（默认 `30`）
- `POLL_RETRY_BASE_SECONDS`（默认 `1.0`）
- `POLL_RETRY_MAX_SECONDS`（默认 `30.0`）
- `JOB_TIMEOUT_SECONDS`（默认 `7200`）
- `CHAT_TURN_TIMEOUT_SECONDS`（默认 `1800`，交互式 `/chat` 轮次的绝对超时上限）
- `CHAT_TURN_PROGRESS_TIMEOUT_SECONDS`（默认 `300`，`/chat` 状态检查的静默期阈值；每次检查都会将延续窗口延长至绝对超时上限）
- `CHAT_TURN_RETRY_COUNT`（默认 `1`，交互式 `/chat` 超时的重试次数）
- `CHAT_TURN_RESET_SESSION_ON_TIMEOUT`（默认 `true`，使用新会话重试超时的 `/chat`）
- `SUBPROCESS_ENV_ALLOWLIST`（可选，传入 Codex 子进程的 CSV 环境变量名）
- `SUBPROCESS_ENV_PREFIX_ALLOWLIST`（可选，传入 Codex 子进程的 CSV 环境变量名前缀）
- `SUBPROCESS_HOME`（可选，子进程 `HOME` 的绝对/相对路径覆盖；默认继承启动器的 `HOME`）
- `CONFIRMATION_TTL_SECONDS`（默认 `300`）
- `MESSAGE_CHUNK_SIZE`（默认 `3500`）
- `MAX_DOWNLOAD_FILE_SIZE_BYTES`（默认 `5242880`）
- `MAX_UPLOAD_FILE_SIZE_BYTES`（默认 `5242880`）
- `TELEGRAM_API_BASE`（默认 `https://api.telegram.org`）
## 受限网络环境
当主 Codex 进程因 DNS 类错误失败（例如 `Could not resolve host`、`Errno 8`）时，您可以通过设置以下内容保持 Telegram 执行正常工作：
```
CODEX_COMMAND_FALLBACK=/absolute/path/to/network-enabled-codex-wrapper
```
行为：
- `/run`、`/autopilot`、`/codex`：自动使用 `CODEX_COMMAND_FALLBACK` 重试一次
- `/chat`：自动使用回退指令重试
- 如果 `CODEX_LIVE_CORE_COMMAND` 指向已构建的辅助工具，`/chat` 首先通过该辅助工具流式传输标准化事件
- 如果主指令和回退均失败，bot 会报告失败，但本地工作区指令仍可用（`/files`、`/search`、`/read`、`/download`）
## 测试
```
pytest -q
```
## 文档
- 部署指南：`docs/DEPLOYMENT.md`
- 安全检查清单：`docs/SECURITY.md`
- SEO 检查清单：`docs/SEO.md`
- 变更日志：`CHANGELOG.md`
标签：ChatOps, Codex CLI, JSONL, Launchd, Python, SBOM, SQLite, Streamlit, Systemd, Telegram 机器人, Webhook, 代码助手, 力导向图, 可视化界面, 命令行接口, 子进程执行, 开发者自动化, 文件传输, 无后门, 硬件无关, 签名发布, 访问控制, 轮询, 远程开发, 逆向工具