openclaw-nerve 安全完全指南:scrypt 密码、HMAC-SHA256 会话、CSP 策略与 local-first 威胁模型

原创2026-10-25 17:15:561,621 阅读
文章标签:AI AgentAI 应用人工智能交互助手前端后端语音

openclaw-nerve 安全完全指南:scrypt 密码、HMAC-SHA256 会话、CSP 策略与 local-first 威胁模型

openclaw-nerve(Nerve)是 OpenClaw AI Agent 的实时 Web 控制台,提供语音对话、自动化 Kanban 看板、文件与 workspace 控制等能力。它内置了一套完整的安全机制:scrypt 密码哈希、HMAC-SHA256 签名的无状态会话、严格的 CSP 安全策略,以及清晰的 local-first 威胁模型。本指南带你一次看懂 Nerve 的安全设计,放心部署你的 Agent 驾驶舱。🛡️

openclaw-nerve 安全指南配图:Nerve 控制台界面展示语音对话与自动化 Kanban 看板

local-first 威胁模型:Nerve 为谁而设计?

Nerve 的安全模型基于一个朴素假设:服务器运行在受信任的机器上,访问者是它的主人。官方安全文档 docs/SECURITY.md 明确说明,它不是为多租户或裸奔公网设计的。

这个定位决定了它的防线分布:

威胁 缓解措施
CSRF 跨站请求伪造 CORS 白名单 + SameSite=Strict Cookie
XSS 跨站脚本 CSP script-src 'self' + 客户端 DOMPurify 净化
点击劫持 X-Frame-Options + frame-ancestors 禁止嵌入 iframe
网络嗅探 可选 HTTPS + HSTS(强制 HTTPS 一年)
资源耗尽 全 API 按 IP 限流 + 全局请求体大小限制
目录穿越 / 符号链接逃逸 绝对路径前缀白名单 + realpath 二次校验

还有一个很「硬核」的细节:如果你把 HOST=0.0.0.0 却忘了开启认证,Nerve 会直接拒绝启动,除非显式设置 NERVE_ALLOW_INSECURE=true。相关校验逻辑见 server/lib/config.ts。

scrypt 密码哈希:你的密码如何被安全存储

Nerve 的认证由环境变量 NERVE_AUTH 一键开启。执行 npm run setup 时,设置向导会引导你设置密码,并在本地完成哈希——见 scripts/setup.ts:

  • 使用 Node.js 原生 node:crypto 的 scrypt 算法(无需任何外部依赖)
  • 随机生成 32 字节盐值,派生 64 字节密钥
  • 以 salt:derivedKey(十六进制)格式存入 .env 的 NERVE_PASSWORD_HASH
  • 明文密码从不落盘、从不写日志

验证密码时同样走 scrypt 重算 + timing-safe 比较,防止时序攻击,核心实现在 server/lib/session.ts。

💡 零配置兜底:如果还没设独立密码,可以暂时用现有的 GATEWAY_TOKEN 当密码登录(同样使用 timing-safe 比较),方便从本机平滑升级到网络访问。逻辑在 server/routes/auth.ts。

HMAC-SHA256 会话:无状态、可篡改即失效

登录成功后(POST /api/auth/login,见 server/routes/auth.ts),Nerve 颁发一个签名的无状态会话令牌,格式为 载荷.签名:

base64url(JSON: {exp, iat}) . base64url(HMAC-SHA256 签名)
  • 载荷里只有过期时间和签发时间两个字段,签名由 NERVE_SESSION_SECRET 计算
  • 服务端不存任何会话表,验签 + 查过期即可完成校验(server/lib/session.ts)
  • 任何对载荷的篡改都会导致验签失败,天然防伪造

会话 Cookie 的属性设计同样严谨:

属性 值 作用
HttpOnly true JS 无法读取,防 XSS 窃取
SameSite Strict 跨站请求不携带,防 CSRF
Secure 自动 HTTPS 环境下仅加密传输
签名 HMAC-SHA256 篡改即失效
名称 nerve_session_{端口} 多实例互不冲突

会话有效期默认 30 天,配置项集中在 server/lib/config.ts。认证中间件会拦截所有 /api/* 路由与 WebSocket 升级请求(server/middleware/auth.ts),只有登录、登出、状态查询等白名单路由免检。

⚠️ 如果忘记配置 NERVE_SESSION_SECRET,Nerve 会自动生成一个临时密钥并给出警告——此时重启后旧会话全部失效。生产部署建议显式配置固定密钥。

CSP 内容安全策略:每响应的 X 光检查

Nerve 通过 server/middleware/security-headers.ts 给每个响应都加上全套安全头:

响应头 值 目的
Content-Security-Policy 见下方说明 纵深防御 XSS
X-Frame-Options SAMEORIGIN 防点击劫持
X-Content-Type-Options nosniff 防 MIME 嗅探
Strict-Transport-Security max-age=31536000; includeSubDomains 生产环境强制 HTTPS
Referrer-Policy strict-origin-when-cross-origin 控制 Referer 泄露
Cache-Control no-store 敏感响应不落浏览器缓存

CSP 指令(security-headers.ts)的核心思想是默认拒绝:

  • script-src 'self':只允许同源脚本,从根上封杀注入的 JS(唯一例外是 TradingView 官方图表组件域名,用于内联 tv 图表)
  • connect-src:仅允许 localhost 的 WebSocket/HTTP,可通过 CSP_CONNECT_EXTRA 扩展——输入会先做净化,剔除分号与换行、只接受 http(s)/ws(s) 协议,防止指令注入
  • frame-ancestors:禁止被恶意页面 iframe 嵌套
  • form-action 'self':表单只能提交给同源

客户端也不含糊:所有 Agent 消息、Markdown 渲染前都会过 DOMPurify 严格白名单净化,代码中不使用 eval()。

网络访问的额外防线:CORS、限流与 WebSocket 代理

当你通过 Tailscale 等组网远程访问时,以下几层防线同时生效:

1. CORS 白名单 — 默认只放行本机 origin,额外来源必须通过 ALLOWED_ORIGINS 配置,且会经 URL 归一化,格式错误和 "null" 来源直接丢弃(server/lib/origin-utils.ts)。

2. 滑动窗口限流 — 所有 /api/* 按「真实 TCP 客户端 IP + 路径」独立限流(server/middleware/rate-limit.ts):

预设 限额 窗口 应用对象
TTS 10 次 60 秒 POST /api/tts
转写 30 次 60 秒 POST /api/transcribe
通用 60 次 60 秒 其余 /api/*

客户端身份取自真实 TCP 套接字地址,无法通过伪造 X-Forwarded-For 绕过;存储条目上限 1 万条,防止内存放大攻击。

3. WebSocket 代理托管 — 这是 Nerve 最优雅的设计之一:浏览器永远直连 Nerve,由 server/lib/ws-proxy.ts 转发到本机 Gateway。敏感的 GATEWAY_TOKEN 从不发送到浏览器,只在对可信客户端(本机回环或已认证会话)发起连接时由服务端注入。代理目标主机默认限定为 localhost / 127.0.0.1 / ::1,防止被利用连接任意外部地址。

网络部署安全建议清单 ✅

场景 建议
仅本机使用 默认配置即可:绑定 127.0.0.1 + CORS 白名单 + 令牌隔离
暴露到局域网/VPN 运行 npm run setup 开启认证并设置密码
生产远程访问 反代 + HTTPS,ALLOWED_ORIGINS / WS_ALLOWED_HOSTS / CSP_CONNECT_EXTRA 同步配置新来源
组网访问 叠加 Tailscale / WireGuard,获得网络层隔离

另外,设置向导会原子写入 .env 并执行 chmod 600,密钥文件权限收紧到属主可读;写入前还会自动备份旧配置。

写在最后

Nerve 的安全哲学可以概括为一句话:默认保守、纵深防御、密钥不出服务端。scrypt 让密码库泄露也不怕,HMAC 签名让会话无法伪造,CSP 与 DOMPurify 双管齐下封堵 XSS,而 local-first 的威胁模型则诚实地告诉你它适合什么、不适合什么。更多细节可查阅官方安全文档 docs/SECURITY.md,以及认证与会话核心实现 server/lib/session.ts 与中间件 server/middleware/ 目录。把驾驶舱交给 Nerve,安心享受与 Agent 协作的乐趣吧。

登录后查看全文
openclaw-nerve