openclaw-nerve 安全完全指南:scrypt 密码、HMAC-SHA256 会话、CSP 策略与 local-first 威胁模型
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 驾驶舱。🛡️
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 协作的乐趣吧。
