Secrets 密钥管理详解

为什么需要 Secrets 管理

OpenClaw 需要访问多个外部服务的 API Key（模型供应商、频道平台等）。直接将这些密钥写在配置文件中存在安全风险——配置文件可能被误提交到 Git 仓库、被日志记录或被未授权用户读取。OpenClaw 的 Secrets 系统提供了安全的密钥存储方案。

Secrets 工作原理

OpenClaw 的 Secrets 系统将密钥加密存储在本地，运行时解密注入到配置中。配置文件中使用 {{SECRET_NAME}} 语法引用密钥，Gateway 启动时会自动替换为实际值。

存储位置：

~/.openclaw/secrets.enc

该文件使用主密钥加密，主密钥存储在系统密钥链中（macOS Keychain / Linux Secret Service / Windows Credential Manager）。

基本操作

添加密钥

openclaw secrets set OPENAI_API_KEY "sk-your-key-here"
openclaw secrets set TELEGRAM_BOT_TOKEN "123456:ABC-DEF"
openclaw secrets set ANTHROPIC_API_KEY "sk-ant-your-key"

查看已存储的密钥

# 列出所有密钥名称（不显示值）
openclaw secrets list

输出：

Stored secrets:
  OPENAI_API_KEY      (set 2026-03-01)
  TELEGRAM_BOT_TOKEN  (set 2026-03-01)
  ANTHROPIC_API_KEY   (set 2026-03-02)

查看密钥值

# 查看特定密钥的值（会有确认提示）
openclaw secrets get OPENAI_API_KEY

删除密钥

openclaw secrets delete OLD_API_KEY

更新密钥

# 直接 set 会覆盖旧值
openclaw secrets set OPENAI_API_KEY "sk-new-key-here"

在配置中引用

在 OpenClaw 配置文件中使用双花括号引用密钥：

{
  "providers": {
    "openai": {
      "apiKey": "{{OPENAI_API_KEY}}"
    },
    "anthropic": {
      "apiKey": "{{ANTHROPIC_API_KEY}}"
    }
  },
  "channels": {
    "telegram": {
      "token": "{{TELEGRAM_BOT_TOKEN}}"
    }
  }
}

Gateway 启动时，所有 {{SECRET_NAME}} 会被替换为对应的密钥值。

从环境变量导入

如果你已有环境变量中的密钥，可以批量导入：

# 导入单个环境变量
openclaw secrets import-env OPENAI_API_KEY

# 批量导入匹配模式的环境变量
openclaw secrets import-env --pattern "OPENCLAW_*"

从 .env 文件导入

openclaw secrets import-file .env

.env 文件格式：

OPENAI_API_KEY=sk-your-key
TELEGRAM_BOT_TOKEN=123456:ABC
ANTHROPIC_API_KEY=sk-ant-key

密钥轮换

定期轮换密钥是安全最佳实践：

# 1. 在供应商处生成新 Key
# 2. 更新 OpenClaw 中的密钥
openclaw secrets set OPENAI_API_KEY "sk-new-rotated-key"

# 3. 重启 Gateway 使新密钥生效
openclaw restart

# 4. 在供应商处撤销旧 Key

备份与恢复

导出密钥（加密）

openclaw secrets export --output secrets-backup.enc

恢复密钥

openclaw secrets import --input secrets-backup.enc

注意：导出文件仍然是加密的，需要相同的主密钥才能解密。

多环境管理

为不同环境使用不同的密钥集：

# 开发环境
OPENCLAW_ENV=development openclaw secrets set OPENAI_API_KEY "sk-dev-key"

# 生产环境
OPENCLAW_ENV=production openclaw secrets set OPENAI_API_KEY "sk-prod-key"

安全建议

不要在日志中输出密钥：OpenClaw 默认会屏蔽日志中的密钥值
限制文件权限：确保 ~/.openclaw/ 目录权限为 700
定期轮换：建议每 90 天轮换一次 API Key
最小权限：API Key 只授予必要的权限
不要提交到 Git：.openclaw/ 目录应加入 .gitignore

# 设置目录权限
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/secrets.enc

故障排查

密钥无法解密：

# 重新初始化密钥存储
openclaw secrets init --reset
# 然后重新设置所有密钥

启动时报密钥未找到：

# 检查密钥是否存在
openclaw secrets list | grep MISSING_KEY

总结

Secrets 管理是 OpenClaw 安全运维的基础。使用 Secrets 系统而非明文存储密钥，可以有效防止密钥泄露。养成使用 openclaw secrets 命令管理所有敏感信息的习惯，是保护你的 AI 助手安全的第一步。