OpenClaw 密钥管理指南

OpenClaw 支持增量式的密钥引用，这样凭证就无需以明文形式存储在配置文件中。明文配置仍然可用，密钥引用是可选功能。

目标与运行时模型

密钥会被解析为内存中的运行时快照。解析会在激活阶段立即执行，而非在请求路径中延迟处理。如果任何引用的凭证无法解析，启动流程会快速失败。重载采用原子交换：要么完全成功，要么保留上一次的可用状态。运行时请求会从激活后的内存快照中读取数据。这避免了密钥提供商的中断影响到核心请求路径。

入职引用预检

当入职流程以交互模式运行，且你选择了密钥引用存储时，OpenClaw 会在保存前执行快速预检：

环境变量引用：校验环境变量名称，并确认入职期间可见非空值。
提供商引用（文件或执行）：校验选中的提供商，解析提供的 ID，并检查值类型。

如果校验失败，入职流程会展示错误并允许你重试。

密钥引用契约

所有场景都使用统一的对象格式：

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

source: "env"（环境变量源）

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

校验规则：

provider 必须匹配正则 ^[a-z][a-z0-9_-]{0,63}$
id 必须匹配正则 ^[A-Z][A-Z0-9_]{0,127}$

source: "file"（文件源）

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

校验规则：

provider 必须匹配正则 ^[a-z][a-z0-9_-]{0,63}$
id 必须是绝对 JSON 指针（/... 格式）
分段中的 RFC6901 转义：~ 转义为 ~0，/ 转义为 ~1

source: "exec"（执行源）

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

校验规则：

provider 必须匹配正则 ^[a-z][a-z0-9_-]{0,63}$
id 必须匹配正则 ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$

提供商配置

在 secrets.providers 下定义提供商：

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // 或 "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

环境变量提供商

可通过 allowlist 配置可选的白名单。缺失 / 空的环境变量会导致解析失败。

文件提供商

从指定路径读取本地文件。

mode: "json" 期望 JSON 对象负载，并将 id 解析为 JSON 指针。
mode: "singleValue" 期望引用 id 为 "value"，并直接返回文件内容。路径必须通过所有权与权限检查。

执行提供商

运行配置的绝对二进制路径，不使用 Shell。默认情况下，命令必须指向常规文件（而非符号链接）。设置 allowSymlinkCommand: true 可允许符号链接命令路径（例如 Homebrew 垫片），OpenClaw 会校验解析后的目标路径。仅在受信任的包管理器路径需要时启用 allowSymlinkCommand，并配合 trustedDirs 使用（例如 ["/opt/homebrew"]）。当设置了 trustedDirs，检查会应用到解析后的目标路径。支持超时、无输出超时、输出字节限制、环境变量白名单，以及受信任目录。

请求负载（标准输入）：

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

响应负载（标准输出）：

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "sk-..." } }

可选的单 ID 错误：

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

执行集成示例

1Password CLI

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // Homebrew 符号链接二进制文件需要此项
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

HashiCorp Vault CLI

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // Homebrew 符号链接二进制文件需要此项
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

sops

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // Homebrew 符号链接二进制文件需要此项
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

支持的字段范围（v1）

~/.openclaw/openclaw.json
- models.providers.<provider>.apiKey
- skills.entries.<skillKey>.apiKey
- channels.googlechat.serviceAccount
- channels.googlechat.serviceAccountRef
- channels.googlechat.accounts.<accountId>.serviceAccount
- channels.googlechat.accounts.<accountId>.serviceAccountRef
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
- profiles.<profileId>.keyRef（针对 type: "api_key"）
- profiles.<profileId>.tokenRef（针对 type: "token"）

OAuth 凭证存储变更暂不在此范围内。

必要行为与优先级

无引用的字段：保持不变。
带引用的字段：激活阶段必须完成解析。
如果明文与引用同时存在，运行时会优先使用引用，忽略明文。

警告码： SECRETS_REF_OVERRIDES_PLAINTEXT

激活触发时机

密钥激活会在以下场景触发：

启动（预检 + 最终激活）
配置重载热应用路径
配置重载重启检查路径
通过 secrets.reload 手动重载

激活契约：

成功时原子交换快照。
启动失败会终止网关启动。
运行时重载失败会保留上一次的可用状态。

降级与恢复的操作信号

当健康状态下的重载激活失败时，OpenClaw 会进入密钥降级状态。一次性系统事件与日志码：

SECRETS_RELOADER_DEGRADED
SECRETS_RELOADER_RECOVERED

行为：

降级状态：运行时保留上一次的可用快照。
恢复状态：成功激活后触发一次。
已降级状态下的重复失败仅记录警告，不会重复发送事件。
启动快速失败不会触发降级事件，因为此时尚无运行时快照。

审计与配置工作流

使用以下默认的操作流程：

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

迁移完整性：当技能使用 API 密钥时，需要包含 skills.entries.<skillKey>.apiKey 目标。如果部分迁移后，audit --check 仍然报告明文发现，请迁移剩余的报告路径，然后重新运行审计。

secrets audit（密钥审计）

审计结果包括：

静态存储的明文值（openclaw.json、auth-profiles.json、.env）
无法解析的引用
优先级覆盖（认证配置覆盖配置引用）
遗留残留（auth.json、OAuth 范围外提醒）

secrets configure（密钥配置）

交互式助手，可：

首先配置 secrets.providers（环境变量 / 文件 / 执行，添加 / 编辑 / 删除）
允许你选择 openclaw.json 中包含密钥的字段
收集密钥引用的详细信息（source、provider、id）
运行预检解析
可立即应用配置

实用模式：

openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup

配置应用的默认行为：

为目标提供商，从 auth-profiles.json 中清理匹配的静态凭证
从 auth.json 中清理遗留的静态 api_key 条目
从 <config-dir>/.env 中清理匹配的已知密钥行

secrets apply（密钥应用）

应用已保存的计划：

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

如需了解严格的目标 / 路径契约细节与确切的拒绝规则，请查看： Secrets Apply Plan Contract

单向安全策略

OpenClaw 不会主动创建包含迁移前明文密钥值的回滚备份。安全模型：

写入前必须完成预检
运行时激活在提交前完成校验
应用更新使用原子文件替换，失败时尽力恢复内存状态

auth.json 兼容性说明

对于静态凭证，OpenClaw 运行时不再依赖明文的 auth.json。运行时的凭证来源是解析后的内存快照。遗留的 auth.json 静态 api_key 条目在发现时会被清理。 OAuth 相关的遗留兼容行为保持独立。

OpenClaw 密钥管理指南

目标与运行时模型

入职引用预检

密钥引用契约

source: "env"（环境变量源）

source: "file"（文件源）

source: "exec"（执行源）

提供商配置

环境变量提供商

文件提供商

执行提供商

执行集成示例

1Password CLI

HashiCorp Vault CLI

sops

支持的字段范围（v1）

必要行为与优先级

激活触发时机

降级与恢复的操作信号

审计与配置工作流

secrets audit（密钥审计）

secrets configure（密钥配置）

secrets apply（密钥应用）

单向安全策略

auth.json 兼容性说明

推荐文章

推荐教程

推荐课程