OpenClaw SecretRef 密钥管理机制深入解析

概述

在部署 OpenClaw 的过程中，一个容易被忽视的安全问题是配置文件中的明文密钥。openclaw.json 中可能包含 Slack Bot Token、第三方 API Key 等敏感凭证。一旦文件泄露（Git 误提交、服务器入侵、备份泄露），这些密钥将直接暴露。

OpenClaw 提供了 SecretRef 机制来解决这个问题：将明文值替换为引用对象，运行时从指定来源读取真实值。

SecretRef 设计

引用格式

source: "env" | "file" | "exec"
provider: "provider_name"
id: "identifier"

三种来源

1. env — 环境变量

{ "source": "env", "provider": "default", "id": "SLACK_BOT_TOKEN" }

变量名格式要求：^[A-Z][A-Z0-9_]{0,127}$

2. file — JSON 文件

{
  "secrets": {
    "providers": {
      "filemain": {
        "source": "file",
        "path": "~/.openclaw/secrets.json",
        "mode": "json"
      }
    }
  }
}

引用使用 JSON Pointer：{ "source": "file", "provider": "filemain", "id": "/providers/openai/apiKey" }

文件会进行权限检查。

3. exec — 外部命令

支持 1Password CLI、HashiCorp Vault、sops 等工具。命令必须是绝对路径，默认不允许符号链接（Homebrew 需要 allowSymlinkCommand: true）。

通信协议：通过 stdin 传入请求 JSON，从 stdout 读取响应 JSON。

运行时模型

1. 启动时解析：密钥在激活阶段解析到内存快照。不在请求路径上调用外部服务
2. 原子热重载：重载时完整重新解析。成功则原子替换，失败保留 last-known-good
3. 活跃表面过滤：仅验证已启用功能的 SecretRef。未启用的 channel/功能的 ref 失败不阻止启动
4. 降级信号：运行时重载失败发 SECRETS_RELOADER_DEGRADED，恢复发 SECRETS_RELOADER_RECOVERED

操作流程

# 审计
openclaw secrets audit --check

# 交互式配置
openclaw secrets configure

# 应用已保存的配置计划
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

configure 完成后会自动清理 auth-profiles.json、auth.json、.env 中对应的明文值。

结合亚马逊云科技的实践

• Bedrock：使用 IAM Role（Instance Profile），零密钥管理
• 其他 API Key：存入 Secrets Manager，通过 exec provider 调用 AWS CLI 读取
• 自动轮转：Secrets Manager 支持定时自动轮转，配合 openclaw secrets reload 刷新运行时快照

注意事项

1. Homebrew 安装的命令需要 allowSymlinkCommand: true + trustedDirs
2. env source 变量名必须大写字母开头
3. SecretRef 和明文同时存在时 SecretRef 优先（会产生 SECRETS_REF_OVERRIDES_PLAINTEXT 警告）
4. Windows 环境下文件 ACL 验证不可用时默认 fail-closed，需要 allowInsecurePath: true

---

以上内容基于 OpenClaw 官方文档和实际部署经验整理，在亚马逊云科技 EC2 上验证。