Secret
真正的钥匙本身，比如 API key、密码、token。
Gateway 导读
SecretRef 不是全局开关，只在你配了的地方生效
OpenClaw 的 SecretRef 是逐凭证选用的，明文依然可用。最该先看“Active-surface filtering”部分，它决定了哪些 SecretRef 会在启动时被强制解析——只有激活的凭证面才会阻塞启动。最容易搞错的是：一个 SecretRef 配置了但不一定生效，比如被环境变量覆盖、或所属功能被禁用时，它会被标记为 inactive 并忽略，不会报错。
先讲这一页到底在解决什么
SecretRef 不是全局开关，只在你配了的地方生效
OpenClaw 的 SecretRef 是逐凭证选用的，明文依然可用。最该先看“Active-surface filtering”部分，它决定了哪些 SecretRef 会在启动时被强制解析——只有激活的凭证面才会阻塞启动。最容易搞错的是：一个 SecretRef 配置了但不一定生效，比如被环境变量覆盖、或所属功能被禁用时，它会被标记为 inactive 并忽略，不会报错。
第一眼
🧰 这页有三层东西：钥匙本身、取件单、取件机器
把这三层分清，SecretRef 这套就不容易晕了。
SecretRef
像一张取件单，只写“去哪个柜子、从哪层架子、按哪个编号拿”。
Provider
像钥匙柜或取件机器，决定钥匙到底从环境变量、文件还是外部命令里来。
一句话
账本里尽量写取件方法，不要写钥匙原文。
为什么要这样
🧱 把钥匙和配置分开，像“家里的总账本”和“保险柜”分开放
官方这套设计不是为了显得高级，而是为了让配置能公开管理、秘密能单独保护。
配置文件
像房子的总账本，适合记录结构、门牌、路线和规则。
秘密来源
像保险柜、小抽屉或保管员，不该跟总账本混在同一页。
运行时再解析
像值班时才拿出钥匙开门，用完就别一直摊在桌上。
🎈 记一句
配置要能看，钥匙要能藏。这两件事最好分开做。
命令翻译
🛠 openclaw secrets apply --from ... --dry-run 到底在干嘛？
这些命令一长串，看成现场动作就会顺很多。
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run像先拿施工总单在保险柜旁边演练一遍，确认每把钥匙都会被放进正确抽屉，但先不真的动手。
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json演练没问题后，再真正按这张计划单把钥匙柜和取件单都布置好。
--allow-exec如果计划里有“靠命令去取钥匙”的机器，这个开关像说“好，我允许你真的把那台机器也试跑一遍”。
不支持的 target path
像施工单上写了保险柜里根本不存在的格子，系统就会拒绝你乱塞。
Provider 三兄弟
🌿 环境变量、📄 文件、⚙️ exec，这三类取钥匙机器性格不一样
官方里最容易变冷的地方，就是 provider 分类。换成柜子比喻就清楚多了。
env
像一排墙上的小挂钩，开机时就挂在那里，伸手就能取。
file
像钥匙本被放进一个文件抽屉，需要按路径去翻。
exec
像按下按钮，叫一台外部取件机临时去拿钥匙。最灵活，也最要小心护栏。
为什么要护栏
因为 exec 不只是“取东西”，它真的会跑命令，所以官方对 trusted dir、json only 这些安全栏杆写得特别细。
最后总结
🎈 把这页压成一句最短的话
Secrets 讲的就是“钥匙别乱摊、账本别乱写”：把真正钥匙放进安全来源里，让配置里只写取件单，实在要用取件机器时再小心地给它护栏。
如果你想继续看“钥匙柜出问题时怎么查”，上一页的 /gateway/troubleshooting 会很搭。