Guardrail Middleware (Telegram -> OpenClaw)

專案現況檢查結果（先讀結構）

本 repo 目前為空（只有 .gitkeep），未發現既有 OpenClaw / Telegram Bot 原始碼與設定檔，因此以下「目前架構」為你提供需求的現況推定，OpenClaw API endpoint 需人工確認。

1) OpenClaw 是否已有可 HTTP 呼叫 chat/agent API

• 在此 repo 未找到任何 OpenClaw server code 或 OpenAPI 定義。
• 已先做 OpenClaw adapter（app/openclaw_client.py），以 OPENCLAW_CHAT_ENDPOINT 明確指定 endpoint。
• TODO（必要人工確認）：OpenClaw 實際 API path、auth header、request/response schema、max_tokens 參數名稱。

2) Telegram channel 目前 webhook/polling 流程在哪裡

• 此 repo 未找到 Telegram bot 邏輯與 webhook/polling 實作。
• 目前 middleware 直接提供 POST /telegram/webhook 作為接管入口。

3) 是否能停用 OpenClaw 內建 Telegram channel

• 理論上可行：將 Telegram webhook 轉向本 middleware，並清空/停用 OpenClaw 內建 Telegram channel token。
• 需在 OpenClaw 實際部署環境中執行停用（本 repo 無相關設定檔可改）。

4) 框架、設定檔、啟動方式、環境變數管理

• 框架：FastAPI + Uvicorn。
• 設定：pydantic-settings 讀取 .env。
• 啟動：uvicorn app.main:app --host 0.0.0.0 --port 8000。
• DB：SQLite quota.db（可用 QUOTA_DB_PATH 改路徑）。

---

技術設計（MVP）

1. 目前架構

Telegram Bot -> OpenClaw -> AWS Bedrock

2. 目標架構

Telegram Bot -> Guardrail Middleware -> OpenClaw -> AWS Bedrock

3. middleware 放置目錄

• 以此 repo root 作為 middleware 專案根目錄。
• 核心程式在 app/。

4. middleware 如何接 Telegram webhook

• Endpoint: POST /telegram/webhook
• 解析 update_id, message.chat.id, message.from.id, message.text
• 非文字直接回覆：「目前只支援文字訊息」

5. middleware 如何呼叫 OpenClaw

• 由 app/openclaw_client.py 封裝。
• 使用：OPENCLAW_BASE_URL, OPENCLAW_API_KEY, OPENCLAW_CHAT_ENDPOINT。
• 送出 payload 含 max_tokens（預設 1000）。
• 若 OpenClaw 真實 API 不相容，保留 TODO adapter 待人工映射。

6. SQLite quota.db 放哪裡

• 預設 ./quota.db（與 app 同主機本地磁碟）。
• 建議 Lightsail 用固定路徑，如 /opt/guardrail-middleware/data/quota.db。

7. 新增環境變數

• APP_HOST=0.0.0.0
• APP_PORT=8000
• APP_TIMEZONE=UTC（本專案採 UTC，date_key=YYYY-MM-DD）
• TELEGRAM_BOT_TOKEN=
• TELEGRAM_ALLOWED_USER_IDS=123456,789012
• DAILY_REQUEST_LIMIT=20
• GLOBAL_DAILY_REQUEST_LIMIT=200
• OPENCLAW_BASE_URL=
• OPENCLAW_API_KEY=
• OPENCLAW_CHAT_ENDPOINT=
• OPENCLAW_MAX_TOKENS=1000
• OPENCLAW_TIMEOUT_SECONDS=60
• QUOTA_DB_PATH=./quota.db

8. 如何部署在 Lightsail

1. 把此 repo 放到 Lightsail Ubuntu。
2. 建立 Python venv 並安裝依賴。
3. 設定 .env。
4. 以 systemd 常駐啟動 Uvicorn（同機部署，不新增雲服務）。
5. 將 Telegram webhook 指向 https://YOUR_DOMAIN/telegram/webhook。

9. 回滾到原本架構

1. 刪除 Telegram webhook（或改回 OpenClaw endpoint）。
2. 在 OpenClaw 重新啟用原 Telegram channel token。
3. 停止 middleware systemd service。

---

.env 範例

APP_HOST=0.0.0.0
APP_PORT=8000
APP_TIMEZONE=UTC

TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_ALLOWED_USER_IDS=123456,789012

DAILY_REQUEST_LIMIT=20
GLOBAL_DAILY_REQUEST_LIMIT=200

OPENCLAW_BASE_URL=https://openclaw.internal
OPENCLAW_API_KEY=xxx
OPENCLAW_CHAT_ENDPOINT=/api/chat
OPENCLAW_MAX_TOKENS=1000
OPENCLAW_TIMEOUT_SECONDS=60

QUOTA_DB_PATH=./quota.db

啟動方式

python -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn app.main:app --host 0.0.0.0 --port 8000

Telegram webhook 指令

設定 webhook：

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook?url=https://YOUR_DOMAIN/telegram/webhook"

查看 webhook：

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

刪除 webhook：

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook"

停用 OpenClaw 內建 Telegram channel

• 將 OpenClaw 原本 Telegram channel token 清空或 disable。
• 確保 Telegram webhook 僅指向 middleware。

quota.db 檢查

sqlite3 quota.db ".tables"
sqlite3 quota.db "SELECT date_key, telegram_user_id, request_count FROM daily_user_usage;"
sqlite3 quota.db "SELECT date_key, request_count FROM daily_global_usage;"
sqlite3 quota.db "SELECT id, date_key, telegram_user_id, status, reason FROM usage_logs ORDER BY id DESC LIMIT 20;"

重設每日額度

sqlite3 quota.db "DELETE FROM daily_user_usage WHERE date_key='2026-04-27';"
sqlite3 quota.db "DELETE FROM daily_global_usage WHERE date_key='2026-04-27';"

systemd 範例（Lightsail）

/etc/systemd/system/guardrail-middleware.service

[Unit]
Description=Guardrail Middleware
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/opt/guardrail-middleware
EnvironmentFile=/opt/guardrail-middleware/.env
ExecStart=/opt/guardrail-middleware/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now guardrail-middleware
sudo systemctl status guardrail-middleware