OpenClaw Docs精讀版：5個(gè)必須親手配對(duì)的網(wǎng)關(guān)核心項(xiàng)（新手實(shí)操手冊(cè)）

docker-compose up -d 啟動(dòng)成功，但發(fā)消息沒反應(yīng)？Telegram機(jī)器人收得到消息，Pi 卻不回復(fù)？這不是模型問題——是網(wǎng)關(guān)配置沒對(duì)上。

OpenClaw 的核心設(shè)計(jì)是完全本地可控：不依賴云服務(wù)、不上傳對(duì)話、不綁定廠商賬號(hào)。但“零依賴”不會(huì)自動(dòng)生效，得你親手?jǐn)Q緊這5顆螺絲。

下面每項(xiàng)都來自真實(shí)調(diào)試現(xiàn)場（附日志+報(bào)錯(cuò)對(duì)照），照著做，10分鐘內(nèi)讓 Pi 通過你的本地網(wǎng)關(guān)真正開口說話。

1. Webhook 安全 Token：不是密碼，是“門禁暗號(hào)”

問題：Telegram Bot 設(shè)置了 Webhook，但 OpenClaw 日志里反復(fù)出現(xiàn) 401 Unauthorized
原因：OpenClaw 拒絕所有未經(jīng)簽名的請(qǐng)求。Token 是你和 Telegram/WhatsApp 約定的臨時(shí)暗號(hào)，每次請(qǐng)求都攜帶它，網(wǎng)關(guān)校驗(yàn)失敗直接拒收。

配置位置：寫在 config.yaml 中（不是環(huán)境變量！）

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

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

驗(yàn)證方式：重啟后看日志

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

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

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

問題：測試時(shí)連發(fā)3條，第4條卡住，日志出現(xiàn) rate_limit_exceeded
原因：OpenClaw 默認(rèn)按用戶ID限流（不是IP），避免單個(gè) Telegram 用戶拖垮整個(gè) Pi Agent。你發(fā)太快，網(wǎng)關(guān)先攔下，等1秒再放行。

配置（config.yaml）：

rate_limit:
  per_user: 5rps    # 每秒最多5條，夠調(diào)試用
  burst: 10         # 突發(fā)允許10條（防雙擊）

驗(yàn)證方式：用 curl 模擬連發(fā)

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. 端到端消息加密：本地解密，全程不碰明文

問題：想把聊天記錄存進(jìn)本地 SQLite，但發(fā)現(xiàn)數(shù)據(jù)庫里全是亂碼
原因：OpenClaw 默認(rèn)啟用 AES-256-GCM 加密（密鑰存在內(nèi)存），所有進(jìn)出網(wǎng)關(guān)的消息體自動(dòng)加解密。你看到的日志是解密后的，數(shù)據(jù)庫存的是密文——這是設(shè)計(jì)，不是 bug。

配置確認(rèn)（默認(rèn)開啟，無需修改）：

encryption:
  enabled: true   # 必須為 true（關(guān)閉=放棄安全）
  key: "auto"     # 自動(dòng)生成并內(nèi)存駐留，不落盤

驗(yàn)證方式：查日志第一行

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

4. Agent 路由規(guī)則：讓 Pi 接管特定關(guān)鍵詞

問題：發(fā) /code 沒反應(yīng)，但發(fā) /help 有回音
原因：OpenClaw 不自動(dòng)轉(zhuǎn)發(fā)所有消息給 Pi。必須顯式聲明：“帶 /code 的消息 → 走 Pi Agent”，否則走默認(rèn) echo 回復(fù)。

配置（config.yaml）：

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

驗(yàn)證方式：發(fā) /code print('hello') → 日志出現(xiàn)

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

5. 多平臺(tái)協(xié)議適配：iMessage 和 Discord 用同一套配置

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

配置（config.yaml）：

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

驗(yàn)證方式：Discord 收到 400 時(shí)，立刻查日志末尾：

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

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

所有操作均在單臺(tái)樹莓派4B（4GB內(nèi)存）實(shí)測通過。不需要GPU，不聯(lián)網(wǎng)調(diào)用外部API——你的AI，從輸入到輸出，全程在你眼皮底下運(yùn)行。