API Key 还明文写在配置文件里？OpenClaw SecretRef 帮你摘出来

翻了一下自己的 openclaw.json，三个 API Key 明文存着。Bedrock 走的 IAM Role 没问题，但 Slack Token 和第三方服务的 Key 全裸着。

万一文件泄了，这些 Key 全完蛋。

OpenClaw 有个 SecretRef 机制——把明文密钥替换成"引用"，运行时从环境变量/文件/外部工具（1Password、Vault）读取真实值。配置文件里再也没有敏感信息。

三种存储方式

source	密钥存在哪	场景
env	环境变量	简单场景
file	JSON 文件	多密钥集中管
exec	外部命令	1Password/Vault

快速上手

1. 审计现有明文

openclaw secrets audit --check

2. 交互式迁移

openclaw secrets configure

它会引导你：配 provider → 选密钥字段 → 预检 → 应用。完成后自动清理旧明文。

3. 具体怎么配

环境变量方式：

原来（明文）：

{ "channels": { "slack": { "botToken": "xoxb-xxxxx" } } }

改成：

{
  "channels": {
    "slack": {
      "botToken": { "source": "env", "provider": "default", "id": "SLACK_BOT_TOKEN" }
    }
  }
}

文件方式：

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

引用：{ "source": "file", "provider": "filemain", "id": "/channels/slack/botToken" }

1Password/Vault：

{
  "secrets": {
    "providers": {
      "vault": {
        "source": "exec",
        "command": "/opt/homebrew/bin/vault",
        "allowSymlinkCommand": true,
        "trustedDirs": ["/opt/homebrew"],
        "args": ["kv", "get", "-field=API_KEY", "secret/openclaw"],
        "passEnv": ["VAULT_ADDR", "VAULT_TOKEN"],
        "jsonOnly": false
      }
    }
  }
}

运行时行为

几个关键设计：

• 启动时解析：密钥在启动阶段全部读入内存，不是每次请求都去取
• 原子热重载：配置变更时重新解析，失败保留上一版（不中断服务）
• 活跃表面过滤：没启用的 channel 的 SecretRef 失败不阻止启动

踩坑

1. Homebrew 命令需要 allowSymlinkCommand: true — op/vault 都是符号链接
2. 环境变量名必须大写 — my_key 被拒，要写 MY_KEY
3. ref 和明文同时存在时 ref 优先 — 会有警告，建议删掉明文

总结

花 10 分钟跑 openclaw secrets configure，把明文 Key 全摘出来。配合亚马逊云科技的 IAM Role（Bedrock 零密钥）+ Secrets Manager，密钥管理不用操心。

---

在亚马逊云科技 EC2 上验证通过。