news 2026/4/4 12:44:36

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
ClawdBot安全加固教程：JWT鉴权+IP白名单+速率限制配置

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星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/4 2:33:08

开源远程桌面控制：企业级跨设备协同解决方案

开源远程桌面控制：企业级跨设备协同解决方案 【免费下载链接】billd-desk 基于Vue3 WebRTC Electron Nodejs搭建的远程桌面 项目地址: https://gitcode.com/gh_mirrors/bi/billd-desk 在数字化转型加速的今天，企业面临着多终端设备管理、跨地域…

作者头像 李华
网站建设 2026/3/29 0:50:04

ClawdBotGPU算力优化：vLLM量化部署Qwen3-4B提升吞吐量300%教程

ClawdBotGPU算力优化：vLLM量化部署Qwen3-4B提升吞吐量300%教程 ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手，本应用使用 vLLM 提供后端模型能力。它不是云端黑盒，而是一套可完全掌控、可深度定制的本地智能中枢——从对话理解、知…

作者头像 李华
网站建设 2026/4/3 23:47:55

提升文本编辑效率：notepad--的实用技巧与场景应用

提升文本编辑效率：notepad--的实用技巧与场景应用 【免费下载链接】notepad-- 一个支持windows/linux/mac的文本编辑器，目标是做中国人自己的编辑器，来自中国。 项目地址: https://gitcode.com/GitHub_Trending/no/notepad-- 你是否曾…

作者头像 李华
网站建设 2026/4/1 18:59:17

带上U盘去客户现场：GLM-4.6V-Flash-WEB演示神器诞生

带上U盘去客户现场：GLM-4.6V-Flash-WEB演示神器诞生 在客户会议室里，投影仪刚接好，笔记本却提示“驱动缺失”；工厂质检台前，系统崩溃无法联网，但客户急着要看AI识别效果；高校实验室里&#xff…

作者头像 李华