Gateway Secrets Management

SecretRef 让支持的凭证不需要以明文存储在配置中。明文仍然有效，SecretRef 是可选的。

运行时模型

• 解析是急切的（激活时，不是请求时）
• 启动时快速失败（有效活跃的 SecretRef 无法解析时）
• 重载使用原子交换：完全成功，或保留上次已知良好快照
• 运行时请求仅从活跃内存快照读取

SecretRef 类型

// 环境变量
{ "$env": "ANTHROPIC_API_KEY" }
 
// 文件
{ "$file": "/run/secrets/anthropic-key" }
 
// 执行命令
{ "$exec": "op read op://vault/anthropic/api-key" }

配置示例

{
  models: {
    providers: {
      anthropic: {
        apiKey: { "$env": "ANTHROPIC_API_KEY" },
      },
    },
  },
  gateway: {
    auth: {
      token: { "$env": "OPENCLAW_GATEWAY_TOKEN" },
    },
  },
}

活跃面过滤

SecretRef 仅在有效活跃面上验证：

• 启用的面：未解析的 ref 阻止启动/重载
• 非活跃面：未解析的 ref 不阻止启动（发出非致命诊断）

密钥操作

openclaw secrets configure    # 交互式配置 SecretRef
openclaw secrets apply        # 应用 SecretRef 到配置
openclaw secrets audit        # 审计凭证覆盖
openclaw secrets reload       # 重载密钥快照

相关

• concepts/reference — SecretRef 凭证面完整列表
• concepts/gateway-runbook — Gateway 运维