密钥管理与安全凭据配置

告别明文密码

OpenClaw 内置了完整的密钥管理系统（Secrets Management），让你不再需要在配置文件中写明文 API Key。系统支持渐进式迁移——现有的明文配置继续有效，你可以按自己的节奏逐步切换到安全模式。

三种密钥来源

1. 环境变量（推荐入门）

最简单的方式，从系统环境变量读取密钥：

{
  secrets: {
    providers: {
      default: { source: "env" }
    }
  }
}

引用格式：{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

2. 本地文件

从 JSON 文件中读取，支持 JSON Pointer 语法定位具体字段：

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

3. 外部工具（1Password / Vault / sops）

调用外部命令获取密钥，适合企业级部署：

{
  secrets: {
    providers: {
      vault: {
        source: "exec",
        command: "/usr/local/bin/vault",
        args: ["kv", "get", "-field=KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR"]
      }
    }
  }
}

审计和迁移

# 审计：找出所有明文凭据
openclaw secrets audit --check

# 交互式配置密钥提供商
openclaw secrets configure

# 应用迁移计划（支持 dry-run）
openclaw secrets apply --dry-run

注意事项

密钥在启动/重载时一次性解析到内存，而非每次请求时读取
如果密钥解析失败，网关会拒绝启动（fail-fast），防止带着错误凭据运行
重载时采用原子替换策略：要么全部成功，要么保留上一次有效的快照