OpenClaw API Key 配置教程,三种方式给你安排明白

事情是这样的。

今天，我在shell里跑了这个命令：

openclaw secrets audit

本来想看看 Key 管理得怎么样。结果很意外。

🔍 发现 13 处明文 API Key。

13 处。agent.sqlite 里躺着 2 个，models.json 里躺着 5 个，.env6个。

但其实大部分是误报。

所以我就研究了一下 OpenClaw 的密钥管理到底怎么玩。然后发现这事看着复杂，其实就三种写法。我给它起了个名字叫密钥三形态。

第一形态：明文裸奔

最原始的做法。打开 openclaw.json，找到 models.providers，直接往里填：

{"sensenova":{"apiKey":"你的key","baseUrl":"https://api.sensenova.cn/v1"}}

简单直接，能用。

缺点也明显，所有人都能看到。分享文件、push 到 GitHub、或者被隔壁同事扫一眼，Key 就没了。

第二形态：${} 环境变量引用

当你意识到明文不对，可能会去翻 OpenClaw 文档。然后看到这句话：

支持 ${VAR_NAME} 格式引用环境变量

试试：

{"sensenova":{"apiKey":"${SENS…_KEY}"}}

然后在 .env 文件里写上：

SENSENOVA_API_KEY=你的key

搞定，Key 从配置文件里消失了，只剩一个变量名。

这个 .env 文件放 ~/.openclaw/.env，OpenClaw 启动时自动加载。比明文强一万倍，而且不用学任何新概念，改个字符串就行。

不过 models.json 的写法不太一样。它不支持 ${} 格式，直接用裸变量名：

{"sensenova":{"apiKey":"SENSENOVA_API_KEY"}}

这个文件是自动生成的，一般不需要你手动编辑，文件在C:\Users\Lenovo.openclaw\agents\main\agent。

两种写法效果一样，都是去 .env 里找变量。OpenClaw 自己会解析。

有个小坑，openclaw secrets audit 会误报 models.json 里的裸变量名为 REF_UNRESOLVED。别慌，其实能用。audit 工具的小 bug，不影响功能。

第三形态：SecretRef 对象

第二形态已经很好了，但 OpenClaw 还提供了一种更「正统」的方式，叫 SecretRef 对象。

长这样：

{"sensenova":{"apiKey":{"source":"env","provider":"default","id":"SENSENOVA_API_KEY"}}}

意思很明确，这个 Key 来自环境变量，用默认 provider 去读，变量名叫 SENSENOVA_API_KEY。

你可能会问，跟 ${} 有什么区别？

从功能上讲，没有区别。最终都是去 .env 里读变量。区别在于三点：语义更明确，一看就知道是引用不是字符串内容；官方推荐做法；可以搭配 secrets configure 交互式配置。

我研究半天，结果发现跟 ${} 就是同一回事。

gateway.auth.token 也能用 SecretRef 对象

{"gateway":{"auth":{"mode":"token","token":{"source":"env","provider":"default","id":"GATEWAY_AUTH_TOKEN"}}}}

飞书的appSecret也能用 SecretRef 对象。

"channels":{"feishu":{"enabled":true,"appId":"*******","appSecret":{"source":"env","provider":"default","id":"FEISHU_APP_SECRET"},

三种形态摆在一起看，其实很简单：

明文裸奔，写起来最快，但最不安全。适合本地测试，跑完就删。

${} 环境变量引用，安全性和 SecretRef 一样，写起来简单。

SecretRef 对象，官方推荐，但跟 ${} 没有本质区别。日常使用推荐这个。

我自己现在全部用的SecretRef 格式。

实操：从裸奔到保险柜

如果你也想清理一下 Key，步骤很简单。

第一步，扫雷。

openclaw secrets audit

看看你的配置文件里有多少明文 Key。

第二步，建保险柜。

在 ~/.openclaw/.env 里写好所有 Key：

SENSENOVA_API_KEY=***SILICONFLOW_API_KEY=***AGNES_API_KEY=***BAISHAN_API_KEY=***NVIDIA_API_KEY=***

这个 .env 文件 OpenClaw 启动时自动加载，不需要手动 。

第三步，改配置。

打开配置文件，把 apiKey 全部改成引用格式。这一步推荐手动编辑，别让 AI 帮你改。我上次被 AI 误删了一段配置，网关重启后直接挂掉，修了半天。

第四步，验证。

重启 OpenClaw，跑 openclaw doctor。没报错就正常。再跑一次 openclaw secrets audit，确认明文 Key 数量为 0。

说真的，API Key 就跟家门钥匙一样。你觉得自己藏得很好，但万一丢了呢？花 10 分钟做一次 Key 安全迁移，换来的是以后再也不担心配置泄露。secrets audit 一跑，哪里还有明文一目了然。

以上，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～谢谢你看我的文章，我们，下次再见。

文章内容基于OpenClaw版本2026.6.8