OpenClaw IV. 认证与安全（5）Secret 管理与密钥轮换

本篇目标：把 OpenClaw 项目里所有“能代表身份/能导致越权/能被滥用”的敏感信息（secrets）怎么存、怎么用、怎么轮换、怎么审计，讲成一套可落地的工程规范。

你会学到：

• OpenClaw 常见 secret 分类（LLM keys、channel tokens、webhook signing secret、cookie/refresh token…）
• 存储位置选择：env / 文件 / OS keychain / KMS / secret manager
• 最小权限与“只在需要时解密”
• 轮换策略：计划轮换、紧急轮换、双密钥平滑切换
• 审计与泄漏响应：如何发现、如何止血、如何复盘

---

1. 为什么 Secret 管理是 OpenClaw 的“系统性风险点”

OpenClaw 不是单一应用，它往往同时握着：

• LLM Provider 的 API Key（可产生直接费用）
• 多个聊天平台的 bot token（可代表你发言、读消息、管理群）
• webhook 验签密钥（决定你是否会被伪造事件攻击）
• 自建 Gateway 的访问 token（可操控你的工具执行面）

因此 secret 管理的目标不是“把 key 藏起来”这么简单，而是：

1. 降低泄漏概率（减少明文落盘/落日志/落截图）
2. 降低泄漏影响（最小权限、分账号分环境、可快速吊销）
3. 提升可恢复性（轮换可自动化、支持双 key 平滑迁移）
4. 提升可追责性（谁在何时用过哪个密钥做了什么）

---

2. 先做资产盘点：OpenClaw 项目里有哪些 Secret

建议把 secret 当成“资产”统一登记（哪怕只是在一个私有表里），至少包含：名称、用途、环境、所有者、轮换周期、撤销方式。

2.1 Provider secrets（花钱 + 能力开关）

• OpenAI / Anthropic / Gemini / DeepSeek… API keys
• 自建模型网关的访问 key

风险：

• 直接费用损失（最常见）
• 被用于生成违规内容导致封禁

2.2 Channel credentials（身份 + 组织权限）

• Telegram bot token
• Slack bot token / app signing secret
• Feishu app id/secret + tenant access token（间接）
• Discord bot token

风险：

• 冒充发言
• 读取群消息/成员信息
• 管理员权限滥用（踢人、改名、发公告）

2.3 Webhook / callback validation secrets（入口真实性）

• Slack signing secret
• Stripe/GitHub webhook secret（如果你接入了）

风险：

• 伪造 inbound event -> 触发工具调用（高危）

2.4 Session/State secrets（长期访问能力）

• refresh token / cookie（尤其是 browser automation 场景）
• OAuth client secret + token cache

风险：

• 长期可用，吊销难
• 往往“权限很大且被遗忘”

2.5 内部基础设施 secrets

• Gateway 的 auth token / mTLS cert
• 数据库密码
• 日志/监控上报 token

风险：

• 被用来横向移动、接管运行面

---

3. 存储策略：从“能跑”到“能上线”

这里给一条实用阶梯：

Level 0：本地开发（可接受，但要自律）

• .env（不进 git）
• env vars（shell 注入）
• macOS Keychain / Windows Credential Manager（更推荐）

最低要求：

• .env 必须在 .gitignore
• 不在任何文档/截图/issue 里粘贴 token

Level 1：单机/小团队部署（推荐起点）

• OS keychain 或者 pass/gopass
• 统一的 secrets.json（加密后落盘）也可，但要有明确的解密边界

目标：

• secret 不以明文形式存在 repo / 共享网盘 / CI 日志

Level 2：多机/生产部署（标准做法）

• 云厂商 KMS + Secret Manager（AWS Secrets Manager / GCP Secret Manager / Azure Key Vault）
• 自建 Vault（HashiCorp Vault）

目标：

• secret 读取有访问控制（IAM / policy）
• 支持版本化与轮换
• 支持审计（谁读了 secret）

---

4. 使用策略：只在需要时解密 + 只给需要的人/进程

4.1 最小权限（Least Privilege）

多账号/多租户场景强烈建议：

• 按 accountId 分开存 token：secret/<tenant>/<accountId>/...
• 按环境分开：prod/staging/dev 绝不共享
• 按能力拆分：能发消息的 token ≠ 能读成员目录的 token

4.2 只在需要时加载（Just-in-time)

常见反模式：

• 启动时把所有账号 token 全读进内存
• 任何 session 都能拿到所有 token

推荐：

• router 在确定 accountId 之后，再加载该账号相关 secrets
• 工具层调用时，以 accountId 作为 key 去取 secret

好处：

• 减少“无关 secret 暴露面”
• 更容易做审计：每次取 secret 都是一次可记录事件

4.3 日志与可观测性：脱敏是底线

规则：

• secret 永远不进日志
• 工具参数里可能含 token 的字段必须统一脱敏（例如 Authorization header）

实操建议：

• 对所有日志做一层 sanitizer（正则 + key 列表）
• 在崩溃 dump / error stack 中也要处理（很多库会把 headers 打出来）

---

5. 轮换（Rotation）：计划轮换 + 紧急轮换

轮换的核心不是“换一下 key”，而是 让系统可以无痛地换。

5.1 轮换的三种触发

1. 计划轮换：按周期（例如 30/90 天）
2. 权限变更：scope/角色变化时顺带重发 token
3. 紧急轮换：怀疑泄漏、机器丢失、repo 误提交

5.2 双密钥平滑切换（推荐）

对 webhook signing secret、内部 gateway token 等，尽量支持：

• active + next 两把 key 并存
• 验证时接受两把（active/next）
• 发起方逐步切换到 next
• 切换完成后撤销 active

这样避免：

• 一次轮换导致“所有回调立刻失效”

5.3 面向外部平台的 token 轮换注意点

• Telegram/Discord 这类 bot token：通常是“换了就立刻失效”，要准备停机窗口
• Slack/Feishu：可能是 OAuth 流程/重新安装 app

建议：

• 先在 staging 演练轮换
• 轮换脚本要能：更新 secret 存储 -> 重启/热加载 -> 回归测试

5.4 热加载 vs 重启

• 热加载：体验更好，但实现更复杂（要保证线程安全 + 旧连接更新）
• 重启：简单可靠，但要配合进程管理（systemd/pm2/k8s）

工程建议：

• 起步阶段优先选“可控重启”
• 真正需要 24/7 的再做热加载

---

6. 审计：你至少要能回答这三个问题

1. 这次工具调用用的是哪个 accountId 的凭据？
2. 这个凭据是什么时候被创建/轮换的？由谁操作？
3. 这个凭据最近被哪些动作使用过？有没有异常调用？

落地字段（建议）：

• secretId / secretVersion
• accountId / tenantId
• usedBy（toolName / connectorName）
• timestamp
• caller（sessionId / actor）
• result（success/fail）

注意：审计记录里不能存 secret 本身，只存标识符。

---

7. 泄漏响应（Incident Response）：先止血，再复盘

7.1 发现迹象

• 费用异常飙升（LLM keys 最典型）
• 平台提示 token 使用异常 / 登录异常
• webhook 收到大量伪造请求（验签失败/频率异常）

7.2 止血清单（按优先级）

1. 撤销/轮换 key（先让攻击者失效）
2. 缩小权限（如果平台支持减少 scope）
3. 封禁入口（临时关 webhook / 加 WAF 规则）
4. 检查日志与审计（定位影响范围）
5. 清理代码与历史（如果误提交到 git，考虑 rewrite history）

7.3 复盘与补强

• 为什么会泄漏：repo、CI、日志、截图、共享屏幕？
• 是否需要更短轮换周期
• 是否需要把 secret 从 env 迁移到 secret manager

---

8. 常见坑（真实世界里很常见）

• 把 .env 传到群里让同事“帮我跑一下”
• 在报错截图里露出 Authorization: Bearer ...
• 复用同一把 signing secret 给多个环境（staging/prod）
• 多账号共享同一 token（导致审计不可追）
• 轮换后忘了更新回调验签端（导致 webhook 全挂）

---

9. 小结

把 secret 管好，本质上是在做三件事：

• 隔离：按环境/租户/accountId 分开
• 最小权限：scope 够用就行
• 可轮换：支持双 key、可自动化、可审计

下一篇我们会把这些原则落到 OpenClaw 的 Policy 与 工具调用 上：

• 哪些工具需要更严格的审批
• 如何把“账号/secret 的使用”纳入统一审计链路