密钥管理
Gateway 提供安全的密钥管理（Secrets Management）功能，用于加密存储 API Key、Token 等敏感凭证，避免在配置文件中暴露明文。
为什么需要密钥管理
明文风险
将 API Key 直接写在配置文件中存在严重安全风险：
- 配置文件可能被意外提交到 Git 仓库
- 其他用户可能读取到配置文件
- 备份文件可能泄露密钥
存储机制
Gateway 使用操作系统原生的安全存储（Secure Storage）来保存密钥：
| 平台 | 存储后端 | 说明 |
|---|---|---|
| macOS | Keychain | 系统密钥链 |
| Linux | Secret Service / 加密文件 | DBus Secret Service 或 AES 加密文件 |
| Windows | Credential Manager | Windows 凭据管理器 |
回退机制
当操作系统原生安全存储不可用时，Gateway 回退使用 AES-256 加密文件存储，密钥派生自用户密码。
CLI 密钥命令
设置密钥
bash
# 设置 API Key
openclaw secrets set OPENAI_API_KEY "sk-proj-xxxxx"
# 设置 Anthropic API Key
openclaw secrets set ANTHROPIC_API_KEY "sk-ant-xxxxx"
# 交互式输入（不在命令行历史中暴露）
openclaw secrets set OPENAI_API_KEY --prompt
Enter value for OPENAI_API_KEY: ****安全输入
使用 --prompt 标志可以交互式输入密钥值，避免密钥出现在 Shell 历史记录中。
查看密钥
bash
# 列出所有已存储的密钥名称（不显示值）
openclaw secrets list输出：
text
Stored Secrets:
OPENAI_API_KEY set 2025-01-10
ANTHROPIC_API_KEY set 2025-01-12
BRIDGE_TOKEN set 2025-01-15bash
# 获取密钥值（脱敏显示）
openclaw secrets get OPENAI_API_KEY
# sk-proj-****xxxx
# 显示完整值（需确认）
openclaw secrets get OPENAI_API_KEY --reveal删除密钥
bash
# 删除单个密钥
openclaw secrets delete OPENAI_API_KEY
# 删除所有密钥（危险操作）
openclaw secrets delete --all不可恢复
删除密钥后无法恢复。请确保你有其他地方保存了原始密钥值。
在配置中引用密钥
使用 ${SECRET_NAME} 语法在配置文件中引用已存储的密钥：
json5
{
"channels": [
{
"name": "openai",
"provider": "openai",
"apiKey": "${OPENAI_API_KEY}" // 引用 Secrets 中的值
},
{
"name": "anthropic",
"provider": "anthropic",
"apiKey": "${ANTHROPIC_API_KEY}" // 引用 Secrets 中的值
}
]
}Gateway 启动时会自动解析 ${...} 引用，从安全存储中读取实际值。
环境变量注入
密钥也可通过环境变量注入，优先级高于安全存储：
bash
# 环境变量优先于 Secrets 存储
export OPENAI_API_KEY="sk-proj-xxxxx"
openclaw gateway解析优先级：
text
环境变量 > Secrets 存储 > 配置文件明文值容器部署
Docker 等容器环境推荐使用环境变量注入密钥，与容器编排工具（Kubernetes Secrets、Docker Secrets）配合使用。
密钥轮换
手动轮换
bash
# 更新密钥值
openclaw secrets set OPENAI_API_KEY "sk-proj-new-key"
# Gateway 自动使用新密钥（热加载模式下无需重启）轮换检查
bash
# 检查密钥最后更新时间
openclaw secrets list --verbosetext
Stored Secrets:
OPENAI_API_KEY set 2025-01-10 (85 days ago) ⚠️ Consider rotating
ANTHROPIC_API_KEY set 2025-03-01 (5 days ago) ✓ Recent导出与迁移
安全警告
导出操作会以明文形式输出所有密钥值。仅在安全环境中操作，完成后立即清理导出文件。
bash
# 导出密钥（加密格式）
openclaw secrets export --encrypted > secrets.enc
# 在新机器上导入
openclaw secrets import secrets.enc
# 导出后安全删除
shred -u secrets.enc # Linux
# 或
rm -P secrets.enc # macOS最佳实践
永远不要在配置文件中写明文密钥
- 使用
${SECRET_NAME}引用
- 使用
使用
--prompt设置密钥- 避免密钥出现在命令行历史
定期轮换密钥
- 建议每 90 天更换一次
最小范围原则
- 每个 Channel 使用独立的 API Key
审计访问
- 定期检查
openclaw secrets list
- 定期检查
备份密钥
- 在密码管理器中保存密钥副本