openclaw secrets¶
管理 SecretRefs,并让活动的运行时快照保持健康。
| 命令 | 作用 |
|---|---|
reload |
Gateway RPC(secrets.reload):重新解析 refs,并以原子方式发布所有者感知的运行时快照(不进行配置写入);符合条件的所有者故障可能会以冷或过期警告的形式发布 |
store |
在本地共享状态 SQLite 数据库中管理团队作用域的 secret 和环境值 |
audit |
对配置/认证/生成模型存储及遗留残留进行只读扫描,检查明文、未解析的 refs 和优先级漂移(除非使用 --allow-exec,否则跳过 exec refs) |
configure |
用于提供者设置、目标映射和预检的交互式规划器(需要 TTY) |
apply |
执行已保存的计划(--dry-run 仅验证,默认跳过 exec 检查;写入模式拒绝包含 exec 的计划,除非使用 --allow-exec),然后清除目标明文残留 |
推荐的操作循环:
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。- 未解析的 refs 返回
2(无论是否使用--check)。 - 存储验证和披露策略失败返回
2。 store get在名称缺失时返回3。
相关:Secrets 管理 · 1Password 插件 · SecretRef 凭据面 · 安全
共享 Secret 存储¶
openclaw secrets store 将写入操作路由到拥有本地状态目录的 Gateway。当 Gateway 停止时,它会取得独占的离线所有权,直到写入和清理操作完成。如果正在运行的 Gateway 版本较旧或无法访问,该命令会拒绝执行且不会回退到本地;请先更新或停止该 Gateway 再重试。该存储是 Gateway 级别且团队作用域的,--scope team 是唯一接受的值。--scope me 会以退出码 2 退出,并提示 Identity scope is not supported yet; use --scope team.
条目还来自控制 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显式更改条目的类型。否则,set和import在保存时会保留条目当前的类型,包括在输入或确认期间所做的保护更改。只有新名称会使用自动检测:以常见凭据后缀结尾的名称(如_API_KEY、_TOKEN、_PASSWORD、_PRIVATE_KEY或_SECRET)会成为secret,其他名称会成为env。
传递给 --value-file 或 --from 的文件路径必须指向常规文件。命名管道和设备路径会被拒绝;流式输入请使用 stdin。
安全设置值¶
仅当解析出的类型是 env 时才接受 --value:
对于 secret 值,--value 会以退出码 2 被拒绝,因为命令行参数可能通过 shell 历史和进程列表泄露。如果在值保存之前,另一个写入者将条目更改为 secret,也会被拒绝。显式指定 --kind env 仍然会重新分类该条目。请改用以下三种安全输入之一:
- 当 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 可在不写入的情况下验证并预览操作。在线写入会刷新 Gateway 中受影响的配置引用。如果保存后刷新失败,错误信息会报告已保存的更改,并引导你执行 openclaw secrets reload;它不会在本地重放该写入。
audit 会将先前存储或解析的占位符报告为 PLACEHOLDER_VALUE,并将其计为未解析的凭据(退出码 2)。对于 store 中损坏的 Gateway token,请运行 openclaw doctor --fix,重启 Gateway,然后重新连接或重新配对设备。参见 Gateway token 恢复。
在每一个机密至少拥有一个精确允许的主机之前,机密出口替换会一直拒绝执行(fail closed)。使用可重复的 --allow-host 标志来绑定或替换主机。这种仅含策略的形式不会要求提供,也不会替换现有的机密值:
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。schemes(协议方案)、路径、端口和通配符都会被拒绝。store list 会显示允许的主机,因为它们是策略元数据,而非机密内容。
读取值¶
openclaw secrets store list --json
openclaw secrets store list --plain
openclaw secrets store get LOG_LEVEL
机密值永远不会出现在人类可读、--json 或 --plain 输出中。store get 会拒绝 secret 条目,因为这类条目按设计是只写的,并退出 2。当名称不存在时,它退出 3。env 类型的值是可读的。
团队作用域的 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 只会收到经过认证的哨兵值(sentinels),并由 Gateway 在 HTTPS 出口处替换它们。参见 机密出口代理。
Warning
存储条目不会传递给在外部代理框架(agent harness)内运行的命令。Codex app-server 及其沙箱 exec-server,以及 Claude Code 等 ACP 子进程,都会构建自己的子环境,永远不会经过 OpenClaw 的 exec 准备流程。在符合条件的 Codex 回合中,请改用 gateway_exec 进入由 OpenClaw 管理的 Gateway 环境路径。
移除值¶
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 文件¶
从普通文件或 stdin 导入 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 一样,导入会保留现有条目的类型(kind),并且仅对新名称应用基于名称的规则。传入 --kind secret|env 可显式重新分类所有导入条目。
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。健康的所有者会独立刷新。符合条件的失败所有者仅当其引用身份、provider 定义以及完整的非机密所有者契约均保持不变时,才会变为过期(stale)状态。新的或发生变化的失败会变为 cold(冷)状态。这种降级激活会成功,并报告 warningCount。严格或未映射的失败会返回错误,并保留之前活动的快照。
选项:--url <url>、--token <token>、--timeout <ms>、--json。
审计¶
扫描 OpenClaw 状态以查找:
- 明文机密存储
- 未解析的引用
- 优先级漂移(auth profile 中存储的凭据遮蔽
openclaw.json引用) - 存储残留(团队存储值在
openclaw.json中以明文重复出现) - 生成的
agents/*/agent/models.json残留(providerapiKey值和敏感 provider 请求头) - 遗留残留(遗留 auth store 条目、OAuth 提醒)
.env 扫描覆盖有效状态目录以及包含活动配置的目录。当两个路径指向同一文件时,该文件只会被扫描一次。
敏感 provider 请求头检测基于名称启发式:它会标记名称与常见认证/凭据片段匹配的请求头(authorization、x-api-key、token、secret、password、credential)。
Doctor 和 secrets audit 共用 openclaw.json 的明文分类。已知的非机密 provider API-key 标记(如 ollama-local)、SecretRefs 以及非敏感 provider 请求头不会产生明文警告。真正的明文密钥仍然会产生警告。
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec
报告结构:
status:clean | findings | unresolvedresolution:refsChecked,skippedExecRefs,resolvabilityCompletesummary: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 与该来源的有效默认值匹配时,不需要提供商条目:secrets.defaults.env 或 secrets.defaults.store,未设置时回退到 default。其他别名以及所有 file/exec 引用都需要一个匹配的 secrets.providers 条目。
标志:
--providers-only:仅配置secrets.providers,跳过凭据映射--skip-provider-setup:跳过提供商设置,将凭据映射到现有提供商--agent <id>:将身份验证配置目标发现和写入限定到一个 agent 存储--allow-exec:允许在预检/apply 期间执行 exec SecretRef 检查(可能会执行提供商命令)
--providers-only 和 --skip-provider-setup 不能组合使用。
说明:
- 需要交互式 TTY。
- 目标为
openclaw.json中包含 secret 的字段,以及所选 agent 的身份验证配置存储。规范支持范围是 SecretRef 凭据范围。 - 支持在选择器流程中直接创建新的身份验证配置映射。
- 在 apply 之前运行预检解析。
- 生成的计划启用
scrubEnv和scrubAuthProfilesForProviderTargets。scrubLegacyAuthJson保持禁用,因为 Doctor 负责旧版auth.json迁移。对于已清除的明文值,apply 是单向的。 --plan-out拒绝创建 UTF-8 序列化形式超过 16 MiB(16,777,216 字节)的计划,与apply --from输入限制一致。- 未使用
--apply时,CLI 在预检后仍会提示Apply this plan now?。 - 使用
--apply(且未使用--yes)时,CLI 会额外提示不可逆迁移确认。 --json会打印计划 + 预检报告,但仍需要交互式 TTY。
Exec 提供商安全¶
包管理器通常会公开符号链接命令路径。解析真实二进制路径(例如使用 realpath "$(command -v vault)"),并配置该绝对、非符号链接路径。使用 trustedDirs 将可执行文件限制到已批准的目录。在 Gateway 主机上运行 openclaw config validate,以在不执行提供商的情况下检查手动 exec 命令路径。在 Windows 上,当 ACL 验证不可用时,提供商路径会失败关闭,且没有提供商级别的绕过。
应用已保存的计划¶
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/提供商的计划,除非使用 --allow-exec。使用 --allow-exec 可在任一模式中启用 exec 提供商检查/执行。
--from 必须指向一个不超过 16 MiB(16,777,216 字节)的常规文件。字节限制适用于完整的序列化文件,包括空白字符。
apply 可能会更新:
openclaw.json(SecretRef 目标 + 提供商 upserts/deletes)- 身份验证配置存储(提供商目标清除)
- 旧版
auth.json残留 - 有效状态和 active-config 目录中的
.env文件,针对值已迁移的已知 secret 键
计划契约详情(允许的目标路径、验证规则、失败语义):Secrets 应用计划契约。
为什么没有回滚备份¶
secrets apply 有意不写入包含旧明文值的回滚备份。安全性来自严格预检加上近似原子的 apply,并在失败时尽力进行内存恢复。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw