OpenClaw Docs精讀版：5個必須親手配對的網關核心項（新手實操手冊）

docker-compose up -d 啟動成功，但發消息沒反應？Telegram機器人收得到消息，Pi 卻不回復？這不是模型問題——是網關配置沒對上。

OpenClaw 的核心設計是完全本地可控：不依賴云服務、不上傳對話、不綁定廠商賬號。但“零依賴”不會自動生效，得你親手擰緊這5顆螺絲。

下面每項都來自真實調試現場（附日志+報錯對照），照著做，10分鐘內讓 Pi 通過你的本地網關真正開口說話。

1. Webhook 安全 Token：不是密碼，是“門禁暗號”

問題：Telegram Bot 設置了 Webhook，但 OpenClaw 日志里反復出現 401 Unauthorized
原因：OpenClaw 拒絕所有未經簽名的請求。Token 是你和 Telegram/WhatsApp 約定的臨時暗號，每次請求都攜帶它，網關校驗失敗直接拒收。

配置位置：寫在 config.yaml 中（不是環境變量！）

webhook:
  token: "sec_7xK2fR9qLmNpYz"  # 隨機生成，長度 ≥12 字符

? 推薦用 openssl rand -hex 8 生成：
openssl rand -hex 8 → a3b8c1e9f2d40765

驗證方式：重啟后看日志

INFO[0012] Webhook token loaded (length=16)  
INFO[0015] Telegram webhook registered at https://your-domain.com/webhook/telegram?token=sec_7xK2fR9qLmNpYz

常見錯誤：
? Token 寫在 .env 里卻沒在 config.yaml 中引用 → 日志顯示 token: ""
? 正確寫法：token: "${WEBHOOK_TOKEN}" + .env 文件含 WEBHOOK_TOKEN=xxx

2. 分級速率限制：防刷，也防自己手抖

問題：測試時連發3條，第4條卡住，日志出現 rate_limit_exceeded
原因：OpenClaw 默認按用戶ID限流（不是IP），避免單個 Telegram 用戶拖垮整個 Pi Agent。你發太快，網關先攔下，等1秒再放行。

配置（config.yaml）：

rate_limit:
  per_user: 5rps    # 每秒最多5條，夠調試用
  burst: 10         # 突發允許10條（防雙擊）

驗證方式：用 curl 模擬連發

for i in {1..6}; do curl -X POST http://localhost:8080/webhook/telegram -d '{"message":"test"}' & done; wait

→ 前5條快速返回 200 OK，第6條延遲1.2秒后返回，日志記 burst exhausted, waiting 1200ms

3. 端到端消息加密：本地解密，全程不碰明文

問題：想把聊天記錄存進本地 SQLite，但發現數據庫里全是亂碼
原因：OpenClaw 默認啟用 AES-256-GCM 加密（密鑰存在內存），所有進出網關的消息體自動加解密。你看到的日志是解密后的，數據庫存的是密文——這是設計，不是 bug。

配置確認（默認開啟，無需修改）：

encryption:
  enabled: true   # 必須為 true（關閉=放棄安全）
  key: "auto"     # 自動生成并內存駐留，不落盤

驗證方式：查日志第一行

INFO[0001] Encryption initialized with auto-generated key (AES-256-GCM)

4. Agent 路由規則：讓 Pi 接管特定關鍵詞

問題：發 /code 沒反應，但發 /help 有回音
原因：OpenClaw 不自動轉發所有消息給 Pi。必須顯式聲明：“帶 /code 的消息 → 走 Pi Agent”，否則走默認 echo 回復。

配置（config.yaml）：

agents:
  pi:
    endpoint: "http://localhost:3000/v1/chat/completions"
    route_patterns: ["^/code", "^/debug", "^/run"]

驗證方式：發 /code print('hello') → 日志出現

INFO[0044] Routing to agent 'pi': matched pattern '^/code'
DEBUG[0045] Forwarding to http://localhost:3000/v1/chat/completions (body size=127B)

5. 多平臺協議適配：iMessage 和 Discord 用同一套配置

問題：Telegram 正常，Discord 發消息后無日志，狀態碼 400
原因：各平臺 Webhook 格式不同（Telegram 發 message.text，Discord 發 data.content）。OpenClaw 用 adapter 層統一轉換，但需指定解析器。

配置（config.yaml）：

adapters:
  discord:
    parser: "discord_v10"   # 必填！漏寫就 400
  telegram:
    parser: "telegram_v3"

驗證方式：Discord 收到 400 時，立刻查日志末尾：

ERROR[0088] Failed to parse Discord payload: unknown field 'content' → check adapter.parser

你已打通本地網關最關鍵的5個關節。現在可以：
? 把 Pi Agent 換成你自己的 Ollama 模型（《Ollama + OpenClaw 零代碼對接》）
? 給網關加 HTTPS（用 Caddy 一行命令搞定：caddy reverse-proxy --from your.domain.com --to localhost:8080）
? 查看完整配置字段說明：OpenClaw config.yaml 官方注釋版

所有操作均在單臺樹莓派4B（4GB內存）實測通過。不需要GPU，不聯網調用外部API——你的AI，從輸入到輸出，全程在你眼皮底下運行。