ClawdBot安全加固教程：JWT鉴权+IP白名单+速率限制配置

ClawdBot 是一个面向个人用户的本地化 AI 助手，设计初衷是“在你自己的设备上运行、完全可控、无需依赖云服务”。它不追求大而全的平台能力，而是聚焦于轻量、可审计、易部署——你可以把它理解为一个装在自己笔记本或树莓派上的「AI控制台」，后端由 vLLM 提供高性能模型推理能力，前端提供直观的 Web 控制界面，支持模型切换、会话管理、插件扩展等核心功能。

但正因为它是直接暴露在局域网甚至公网的服务（尤其当你通过 SSH 端口转发或反向代理对外提供访问时），默认配置下的 ClawdBot 不具备生产级安全防护能力。它的 API 网关默认开放、无身份校验、无访问控制、无调用节流——这意味着：只要知道地址和端口，任何人就能调用你的模型、读取历史会话、甚至执行未授权操作。

这显然不符合“个人可控”的初心。真正的可控，不是“我能装”，而是“只有我能用”。

本教程不讲原理堆砌，不套用抽象概念，只聚焦三件事：
怎么让每次请求都必须带上有效 JWT 才能进门；
怎么只允许你家路由器分配的那几个 IP 连接；
怎么防止有人写个脚本疯狂刷接口拖垮你的 vLLM 服务。
所有配置均基于 ClawdBot 当前稳定版（2026.1.24-3）实测可用，无需修改源码，全部通过标准配置文件与环境变量完成。

---

1. 安全加固前的认知准备：ClawdBot 的请求入口在哪？

ClawdBot 的服务架构非常清晰：前端 UI（Gradio）负责展示，后端 Gateway（clawdbot gateway）负责统一接收 HTTP/WS 请求并分发给模型服务。而真正需要加固的，正是这个 Gateway 层。

关键事实：ClawdBot 默认启动的 gateway 进程监听 http://127.0.0.1:18780（HTTP）和 ws://127.0.0.1:18780（WebSocket），它不自带鉴权中间件，也不做 IP 过滤或限流。所有安全策略必须在此之上叠加。

你可能已经通过 clawdbot dashboard 获取了带 token 的 Web 地址（如 http://localhost:7860/?token=xxx），但请注意：那个 token 仅用于 Gradio 前端登录，它对后端 Gateway 完全无效。Gateway 仍处于“裸奔”状态。

所以，加固的第一步，不是改前端，而是明确：我们要保护的是 :18780 这个端口。

1.1 查看当前 Gateway 状态

在终端中执行：

clawdbot gateway status

你会看到类似输出：

🦞 Clawdbot 2026.1.24-3 (885167d) — I speak fluent JSON, but I still sigh when you forget the comma.

Status: running
Bind: 127.0.0.1:18780
Mode: local
Health: OK (vLLM connected)

确认 Bind 地址确实是 127.0.0.1:18780。如果你曾手动修改过绑定地址（比如改成 0.0.0.0:18780），请立即改回 127.0.0.1——这是第一道防线：拒绝外部直连，只允许本机进程通信。

小贴士：ClawdBot 的设计哲学是“前端代理后端”。Web UI 和 CLI 命令都通过 127.0.0.1:18780 与 Gateway 通信。因此，只要 Gateway 绑定在 127.0.0.1，你就无需担心公网扫描；后续所有加固，都是为“你主动暴露出去的代理层”（如 Nginx、Caddy 或 SSH 端口转发）服务的。

---

2. 第一层防护：启用 JWT 鉴权（强制身份核验）

JWT（JSON Web Token）是目前最轻量、最易集成的 API 认证方式。ClawdBot 原生支持，只需两步：生成密钥 + 启用验证。

2.1 生成安全密钥并写入环境变量

不要用 123456 或 password。打开终端，运行：

openssl rand -hex 32

你会得到一串 64 位随机字符串，例如：
a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef

将它保存为环境变量。推荐写入 ~/.clawdbot/.env（如果不存在则创建）：

echo "CLAWDBOT_JWT_SECRET=a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef" >> ~/.clawdbot/.env

注意：.env 文件权限必须设为 600（仅所有者可读写）：

chmod 600 ~/.clawdbot/.env

2.2 在配置文件中启用 JWT 验证

编辑 ~/.clawdbot/clawdbot.json（即 /app/clawdbot.json），在顶层添加 security 字段：

{
  "security": {
    "jwt": {
      "enabled": true,
      "header": "Authorization",
      "prefix": "Bearer "
    }
  },
  "agents": { ... },
  "models": { ... }
}

重要说明：

• header: 指定从哪个 HTTP Header 读取 token，默认 Authorization；
• prefix: 指定 token 前缀，默认 Bearer （注意末尾空格）；
• 此配置不会影响现有 CLI 命令（clawdbot models list 等仍可直接运行），因为 CLI 走的是本地 Unix socket，不经过 HTTP；
• 所有外部 HTTP/WS 请求（包括你用 curl 测试、前端 JS 调用、Postman 调试）现在都必须携带合法 JWT，否则返回 401 Unauthorized。

2.3 生成一个可用的 JWT 并测试

安装 jwt-cli（macOS/Linux）：

npm install -g jwt-cli
# 或使用 Python（需先 pip install pyjwt）
pip install pyjwt[crypto]

生成 token（有效期设为 7 天）：

jwt encode --secret a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef \
  --expires-in 7d \
  --iss clawdbot \
  --sub admin \
  --aud gateway

你会得到一长串 token，形如：
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjbGF3ZGJvdCIsInN1YiI6ImFkbWluIiwiYXVkIjoiZ2F0ZXdheSIsImV4cCI6MTcyMjQwMDAwMH0.xxxxx

现在用 curl 测试：

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjbGF3ZGJvdCIsInN1YiI6ImFkbWluIiwiYXVkIjoiZ2F0ZXdheSIsImV4cCI6MTcyMjQwMDAwMH0.xxxxx" \
  http://127.0.0.1:18780/v1/models

应返回模型列表（HTTP 200）；
❌ 若去掉 -H 参数，返回 401 Unauthorized。

小结：JWT 鉴权已生效。你不再需要记住多个密码，只需安全保管好 CLAWDBOT_JWT_SECRET，所有合法 token 都可随时签发、随时废止（通过更换密钥实现）。

---

3. 第二层防护：配置 IP 白名单（最小权限访问）

即使有了 JWT，你也应限制“谁能发起请求”。ClawdBot 支持基于 CIDR 的 IP 白名单，粒度精确到子网。

3.1 确定你的可信 IP 范围

• 如果你只在本机使用（如通过 localhost:7860 访问 UI），白名单只需：127.0.0.1/32；
• 如果你在家庭网络中多设备访问（手机、平板、另一台电脑），查一下路由器分配的局域网段，常见为：
  • 192.168.1.0/24（覆盖 192.168.1.1 ~ 192.168.1.254）
  • 10.0.0.0/24 或 172.16.0.0/12（根据你的路由器设置）；
• 如果你通过 SSH 端口转发（如 ssh -L 7860:127.0.0.1:7860 user@server），那么服务器的内网 IP（如 10.0.2.2）也要加入。

快速查看本机局域网 IP：
macOS/Linux：ipconfig getifaddr en0 或 hostname -I
Windows：ipconfig | findstr "IPv4"

3.2 在配置中启用 IP 白名单

继续编辑 ~/.clawdbot/clawdbot.json，在 security 下添加 ipWhitelist：

{
  "security": {
    "jwt": {
      "enabled": true,
      "header": "Authorization",
      "prefix": "Bearer "
    },
    "ipWhitelist": ["127.0.0.1/32", "192.168.1.0/24"]
  },
  "agents": { ... },
  "models": { ... }
}

支持多个 CIDR，用数组表示；
/32 表示单 IP，/24 表示 C 类子网；
❌ 不支持域名、不支持通配符（如 192.168.*.*）；
白名单检查在 JWT 验证之前执行——这意味着：非法 IP 连接连 token 校验环节都进不去，直接 403 Forbidden。

3.3 验证白名单是否生效

找一台不在白名单内的设备（如手机用蜂窝网络），尝试访问：

curl -v http://YOUR_SERVER_IP:18780/v1/models

你应该看到响应头中包含：
HTTP/1.1 403 Forbidden
且响应体为：{"error":"Forbidden: IP not in whitelist"}

白名单工作正常。

小结：IP 白名单 + JWT 形成双重校验——先看“你是谁（IP）”，再看“你有没有钥匙（token）”。两者缺一不可。

---

4. 第三层防护：启用速率限制（防暴力探测与滥用）

没有限流的 API，就像没锁的门——即使有钥匙，也挡不住有人连续敲门一万次。ClawdBot 内置基于内存的令牌桶（Token Bucket）限流器，开箱即用。

4.1 理解限流参数：key、limit、window

ClawdBot 的限流按“请求路径前缀”分组，每个组独立计数。常用配置项：

参数	含义	示例
key	限流分组依据	"path:/v1/chat/completions" 表示所有 /v1/chat/completions 请求归为一组
limit	窗口期内最大请求数	10
window	时间窗口（秒）	60 → 即每分钟最多 10 次

推荐组合：

• 对 /v1/chat/completions：limit: 30, window: 60（防脚本刷对话）
• 对 /v1/models：limit: 5, window: 60（防频繁探针）
• 对根路径 /：limit: 100, window: 300（宽松，供前端健康检查）

4.2 配置速率限制规则

在 clawdbot.json 的 security 下添加 rateLimiting：

{
  "security": {
    "jwt": { ... },
    "ipWhitelist": [ ... ],
    "rateLimiting": {
      "enabled": true,
      "rules": [
        {
          "key": "path:/v1/chat/completions",
          "limit": 30,
          "window": 60
        },
        {
          "key": "path:/v1/models",
          "limit": 5,
          "window": 60
        },
        {
          "key": "path:/",
          "limit": 100,
          "window": 300
        }
      ]
    }
  }
}

注意：rateLimiting 是对象，rules 是数组；每条 rule 必须包含 key、limit、window 三个字段。

4.3 测试限流效果

用 curl 连续快速请求（模拟攻击）：

for i in {1..40}; do curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:18780/v1/chat/completions; sleep 0.1; done

你会看到前 30 次返回 200 或 400（请求体错误），第 31 次起返回 429 Too Many Requests，响应头中包含：

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1722400000

限流器已就位。

小结：速率限制不是为了“卡住用户”，而是为系统留出喘息空间。它让 ClawdBot 在遭遇误操作或恶意探测时，依然保持核心服务（模型推理）的稳定性。

---

5. 综合加固后的完整配置示例

以下是整合 JWT、IP 白名单、速率限制后的 clawdbot.json 安全相关片段（仅展示 security 部分，其余保持不变）：

{
  "security": {
    "jwt": {
      "enabled": true,
      "header": "Authorization",
      "prefix": "Bearer "
    },
    "ipWhitelist": ["127.0.0.1/32", "192.168.1.0/24"],
    "rateLimiting": {
      "enabled": true,
      "rules": [
        {
          "key": "path:/v1/chat/completions",
          "limit": 30,
          "window": 60
        },
        {
          "key": "path:/v1/models",
          "limit": 5,
          "window": 60
        },
        {
          "key": "path:/",
          "limit": 100,
          "window": 300
        }
      ]
    }
  },
  "agents": { ... },
  "models": { ... }
}

重启 ClawdBot 生效（若正在运行）：

clawdbot gateway stop
clawdbot gateway start

提示：ClawdBot 的配置是热加载的，但 security 相关变更需重启 gateway 进程才能生效。

---

6. 加固后验证清单（5 分钟自查）

完成配置后，请按顺序执行以下 5 项验证，确保无遗漏：

1. JWT 缺失测试：
   curl http://127.0.0.1:18780/v1/models → 应返回 401 Unauthorized

2. JWT 无效测试：
   curl -H "Authorization: Bearer invalid.token.here" http://127.0.0.1:18780/v1/models → 应返回 401

3. IP 白名单测试：
   从非白名单 IP（如手机蜂窝网络）访问 → 应返回 403 Forbidden

4. 速率限制测试：
   用正确 token 连续请求 /v1/chat/completions 超过 30 次/分钟 → 第 31 次起应返回 429

5. 功能回归测试：
   用浏览器打开 http://localhost:7860/?token=xxx → 前端 UI 应完全正常，所有按钮、下拉、提交均可用（因为前端已自动注入 token）

全部通过？恭喜，你的 ClawdBot 已具备基础生产级防护能力。

---

7. 进阶建议：让安全更进一步

以上三重防护已覆盖 95% 的个人使用场景。若你有更高要求，可考虑以下延伸方案（非必需，按需选用）：

7.1 使用反向代理（Nginx/Caddy）做前置网关

• 将 127.0.0.1:18780 完全屏蔽，只暴露 443 端口；
• 在 Nginx 中终止 TLS、添加 Basic Auth、集成 WAF 规则；
• 利用 Nginx 的 limit_req 模块做第二层限流（更精细）；
• 日志集中收集，便于审计。

7.2 启用 HTTPS（强制加密传输）

ClawdBot 本身不内置 HTTPS，但可通过 clawdbot dashboard 启动时指定证书：

clawdbot dashboard --ssl-key-file /path/to/key.pem --ssl-cert-file /path/to/cert.pem

或更推荐：用 Caddy 一键反代并自动申请 Let's Encrypt 证书。

7.3 定期轮换 JWT 密钥

将 CLAWDBOT_JWT_SECRET 写入密码管理器，每 3 个月手动更新一次，并通知所有合法使用者重新生成 token。密钥轮换是成本最低、收益最高的安全实践。

最后提醒：安全不是一劳永逸的配置，而是一种持续的习惯。ClawdBot 的价值，在于它把控制权交还给你——而这份控制权，值得用一点点配置去守护。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。