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，从输入到输出，全程在你眼皮底下运行。