openclaw secrets¶

管理 SecretRefs 并保持活动运行时快照健康。

推荐的操作流程：

openclaw secrets audit --check
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

如果你的计划包含 exec SecretRefs/提供商，请在 dry-run 和写入模式的 apply 命令中都传入 --allow-exec。如果最后的 audit --check 仍报告明文发现，请更新剩余的被报告目标路径并重新运行审计。

CI/门禁的退出码：

• audit --check 在发现问题时返回 1。
• 未解析的引用返回 2（无论是否使用 --check）。
• 存储验证和披露策略失败返回 2。
• 当名称缺失时，store get 返回 3。

相关：Secrets 管理 · 1Password 插件 · SecretRef 凭据表面 · 安全

共享 Secret 存储¶

openclaw secrets store 直接写入本地共享状态数据库。该存储是 Gateway 全局且团队范围的，--scope team 是唯一接受的值。--scope me 会以 2 退出，并提示 Identity scope is not supported yet; use --scope team.

条目也来自 Control UI 中的 Settings -> Secrets，以及代理的 secrets 工具。该工具会要求你在掩码提示中输入凭据。它存储凭据时，值不会到达模型。

openclaw secrets store list
openclaw secrets store set <NAME>
openclaw secrets store get <NAME>
openclaw secrets store rm <NAME>...
openclaw secrets store import [--from <file>]

命名和值规则：

• 名称必须匹配 ^[A-Z][A-Z0-9_]{0,127}$。
• 值限制为 64 KiB（65,536 个 UTF-8 字节）。无论值来自 stdin、--value 还是 --value-file，超大的值都会以 2 退出。
• secret 条目不能为空，因为空的凭据以后无法诊断。get 拒绝 secret 类型，列表会掩蔽它们。env 条目可以为空。
• 已知的脱敏占位符（如 __OPENCLAW_REDACTED__）不能作为值存储。CLI 的 set 和 import 会跳过对现有可用条目的已脱敏输入，并给出明确的未更改消息；没有可用现有条目的占位符将以 2 退出。
• --kind secret|env 覆盖自动类型检测。否则，以常见凭据后缀结尾的名称（如 _API_KEY、_TOKEN、_PASSWORD、_PRIVATE_KEY 或 _SECRET）将成为 secret，其他名称将成为 env。

安全地设置值¶

仅当解析后的类型为 env 时才接受 --value：

openclaw secrets store set LOG_LEVEL --kind env --value debug

对于 secret 值，--value 会被拒绝并返回退出码 2，因为命令行参数可能通过 shell 历史和进程列表泄露。请改用以下三种安全输入之一：

• 当 stdin 不是 TTY 时，通过管道传入 stdin。
• 传入 --value-file <path>。--value-file - 表示 stdin。
• 以交互方式运行，并在无回显提示中输入值。

示例：

op read 'op://Engineering/OpenAI/apiKey' | \
  openclaw secrets store set OPENAI_API_KEY --kind secret

openclaw secrets store set TLS_PRIVATE_KEY \
  --kind secret \
  --value-file ./client-key.pem

set 是幂等的，并会更新现有名称。添加 --dry-run 可在不写入的情况下验证和预览操作。成功的写入会提醒你在配置引用的值生效之前运行 openclaw secrets reload。

audit 会将之前存储或解析的占位符报告为 PLACEHOLDER_VALUE，并将其计为未解析的凭据（退出码 2）。对于损坏的、由存储支持的 Gateway 令牌，请运行 openclaw doctor --fix，重启 Gateway，然后重新连接或重新配对设备。参见 Gateway 令牌恢复。

Secret 出站替换在每个 secret 至少有一个精确允许的主机之前会失败关闭。使用可重复的 --allow-host 标志绑定或替换主机。此仅策略形式不会要求或替换现有 secret 值：

openclaw secrets store set OPENAI_API_KEY --allow-host api.openai.com
openclaw secrets store set SERVICE_TOKEN \
  --allow-host api.example.com \
  --allow-host uploads.example.com
openclaw secrets store set SERVICE_TOKEN --clear-allowed-hosts

主机名会被规范化为小写 ASCII/punycode。方案、路径、端口和通配符会被拒绝。store list 显示允许的主机，因为它们是策略元数据，而非 secret 材料。

读取值¶

openclaw secrets store list --json
openclaw secrets store list --plain
openclaw secrets store get LOG_LEVEL

密钥值永远不会出现在人类可读输出、--json 或 --plain 输出中。store get 按设计将 secret 条目视为只写而拒绝读取，并返回退出码 2。当名称不存在时，返回退出码 3。环境类（environment-kind）值是可读的。

团队范围的 env 条目可到达由 OpenClaw 自身 exec 工具运行的 Gateway 托管命令，包括 OpenClaw Code Mode 对 openclaw:core:exec 的调用以及 Codex gateway_exec。每次调用时显式设置的 env 优先于 store 值。沙箱、远程 node、ACP 和 Codex 原生 shell 执行不会收到这些值。secret 条目默认不会进入子进程。当 secrets.egressProxy.enabled: true 时，Gateway 托管的 exec 仅接收经过身份验证的哨兵值，Gateway 会在 HTTPS 出口处将其替换。参见 Secret 出口代理。

删除值¶

openclaw secrets store rm OLD_TOKEN
openclaw secrets store rm OLD_TOKEN LEGACY_PASSWORD --yes
openclaw secrets store rm OLD_TOKEN --dry-run

删除操作是幂等的，因此不存在的名称会静默成功。未提供 --yes 时，CLI 会要求确认。被删除的行会进行软删除，并在 30 天后清除。

导入 dotenv 文件¶

从普通文件或标准输入导入 dotenv 格式的赋值：

openclaw secrets store import --from .env
openclaw secrets store import --from .env --dry-run
openclaw secrets store import --from .env --yes
op read 'op://Engineering/service-account/dotenv' | openclaw secrets store import --yes

导入器支持带引号的值以及多行带引号的值（如 PEM 密钥）。使用 --yes 跳过确认，使用 --dry-run 在不写入的情况下检查导入内容。类型检测遵循与 store set 相同的基于名称的规则。

store CLI 命令不接受 --url 或 --token，也不会通过 Gateway 路由。Control UI 改用管理员范围的 secrets.store.* RPC 方法。当活动配置引用了已更改的名称时，这些方法会自动刷新运行时。

重新加载运行时快照¶

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

使用 gateway RPC 方法 secrets.reload。健康的属主会独立刷新。符合条件的失败属主仅在其引用标识、提供者定义和完整的非密钥属主契约未变时才会变为过期状态。新的或已更改的失败会变为冷状态。这种降级激活会成功并报告 warningCount。严格或未映射的失败会返回错误，并保留先前活动的快照。

选项：--url <url>、--token <token>、--timeout <ms>、--json。

审计¶

扫描 OpenClaw 状态以查找：

• 明文密钥存储
• 未解析的引用
• 优先级漂移（auth 配置文件存储中的凭据遮蔽 openclaw.json 引用）
• store 残留（团队 store 值在 openclaw.json 中被明文重复）
• 生成的 agents/*/agent/models.json 残留（provider apiKey 值和敏感的 provider 标头）
• 遗留残留（遗留 auth 存储条目、OAuth 提醒）

.env 扫描覆盖有效状态目录以及包含活动配置的目录。当两个路径指向同一文件时，该文件只扫描一次。

敏感的 provider 标头检测基于名称启发式规则：它会标记名称与常见认证/凭据片段匹配的标头（authorization、x-api-key、token、secret、password、credential）。

Doctor 和 secrets 审计共享对 openclaw.json 的明文分类。已知的非密钥 provider API-key 标记（如 ollama-local）、SecretRef 以及非敏感的 provider 标头不会产生明文警告。真正的明文密钥仍然会产生警告。

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

报告结构：

• status：clean | findings | unresolved
• resolution：refsChecked、skippedExecRefs、resolvabilityComplete
• summary：plaintextCount、unresolvedRefCount、shadowedRefCount、storeResidueCount、legacyResidueCount
• 发现代码：PLAINTEXT_FOUND、REF_UNRESOLVED、REF_SHADOWED、STORE_PLAINTEXT_RESIDUE、LEGACY_RESIDUE

配置（交互式助手）¶

以交互方式构建 provider 和 SecretRef 更改，运行预检，并可按需应用：

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

流程：先进行 provider 设置（添加/编辑/删除 secrets.providers 别名），然后进行凭据映射（选择字段，分配 {source, provider, id} 引用），最后进行预检和可选的应用。

对于 env 和 store 引用，当 provider 匹配该源的有效默认值时，无需 provider 条目：secrets.defaults.env 或 secrets.defaults.store，未设置时回退到 default。其他别名以及所有 file/exec 引用都需要匹配的 secrets.providers 条目。

标志：

• --providers-only：仅配置 secrets.providers，跳过凭据映射
• --skip-provider-setup：跳过 provider 设置，将凭据映射到现有 provider
• --agent <id>：将 auth 配置文件的目标发现和写入范围限定到单个 agent 存储
• --allow-exec：允许在预检/应用期间执行 exec SecretRef 检查（可能执行 provider 命令）

--providers-only 和 --skip-provider-setup 不能同时使用。

说明：

• 需要交互式 TTY。
• 目标为 openclaw.json 中包含密钥的字段，以及所选代理的 auth profile 存储。规范支持范围是 SecretRef 凭据表面。
• 支持在 picker 流程中直接创建新的 auth profile 映射。
• 在应用前运行预检解析。
• 生成的计划会启用 scrubEnv 和 scrubAuthProfilesForProviderTargets。scrubLegacyAuthJson 保持禁用，因为 Doctor 负责旧版 auth.json 迁移。对于已清除的明文值，应用是单向的。
• --plan-out 会拒绝创建 UTF-8 序列化形式超过 16 MiB（16,777,216 字节）的计划，与 apply --from 输入限制一致。
• 未使用 --apply 时，CLI 在预检后仍会提示 Apply this plan now?。
• 使用 --apply（且未使用 --yes）时，CLI 会额外提示不可逆迁移确认。
• --json 会打印计划 + 预检报告，但仍需要交互式 TTY。

Exec provider 安全性¶

包管理器通常会暴露符号链接命令路径。请解析真实二进制文件路径（例如使用 realpath "$(command -v vault)"），并配置该绝对、非符号链接路径。使用 trustedDirs 将可执行文件限制在已批准的目录中。在 Gateway 主机上运行 openclaw config validate，以在不执行 provider 的情况下检查手动 exec 命令路径。在 Windows 上，当 ACL 验证不可用时，provider 路径会失败关闭，且没有 provider 级别的绕过。

应用已保存的计划¶

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

--dry-run 在不写入文件的情况下验证预检。在 dry-run 中，默认跳过 Exec SecretRef 检查。写入模式会拒绝包含 exec SecretRefs/providers 的计划，除非使用 --allow-exec。使用 --allow-exec 可在任一模式中启用 exec provider 检查/执行。

--from 必须指向一个常规文件，且大小不超过 16 MiB（16,777,216 字节）。字节限制适用于完整序列化文件，包括空白字符。

apply 可能更新的内容：

• openclaw.json（SecretRef 目标 + provider 新增/更新/删除）
• auth profile 存储（provider 目标清除）
• 旧版 auth.json 残留
• 有效状态和 active-config 目录中的 .env 文件，针对值已迁移的已知密钥键

计划契约详情（允许的目标路径、验证规则、失败语义）：Secrets Apply 计划契约。

为什么没有回滚备份¶

secrets apply 有意不写入包含旧明文值的回滚备份。安全性来自严格预检加上近似原子应用，并在失败时尽力进行内存恢复。

相关¶

• CLI 参考
• 密钥管理
• Vault SecretRefs
• 1Password 插件