梦行志OpenClaw API Key 安全管理：从明文到零泄露的完整迁移指南
告别配置泄露风险，手把手教你把敏感密钥搬进 .env 文件
OpenClaw API Key 安全管理：从明文到零泄露的完整迁移指南
你有没有过这样的经历？把 OpenClaw 的配置文件分享给别人调试，结果对方一眼扫到了一堆 API Key；或者不小心把 .gitignore 配错了，openclaw.json 被推到了公开仓库——那一瞬间的心跳加速，大概每个开发者都经历过。
我的配置文件里躺着 Tavily、NVIDIA、OpenRouter、DashScope、智谱、LMStudio、LongCat 等等十几个服务的密钥，还有 Gateway Token。它们全是以明文形式写在 openclaw.json 的 env.vars 里。这就像把银行密码写在钱包里一样危险。
今天就来聊聊我是怎么一步步把这些敏感信息全部迁移到 .env 文件中的，实现配置文件零明文密钥。
为什么明文存储 API Key 是个大问题
OpenClaw 的 openclaw.json 是一个集中配置文件，里面包含了模型 Provider 配置、Gateway 设置、Skills 路径等大量信息。当 API Key 以明文形式存放在 env.vars 中时，存在三个主要风险：
Git 意外提交：配置文件可能被无意推送到了版本控制仓库，尤其是公共仓库，密钥会立刻暴露给所有人。
分享即泄露：调试问题时分享配置文件，等于把几十个服务的密钥全部给对方。
权限边界模糊：任何能读取配置文件的人，都能获取所有 API Key，没有最小权限隔离。
解决思路很直接：把密钥从配置文件中抽离出来，放到一个专门的、不受版本控制的环境变量文件中。
OpenClaw 的环境变量加载机制
在动手迁移之前，理解 OpenClaw 的环境变量加载顺序至关重要。它按照以下优先级从低到高读取：
openclaw.json中的env.vars（最低优先级）.env文件：当前工作目录的.env，以及~/.openclaw/.env（全局兜底）- 父进程环境变量（最高优先级）
这里有一个关键点需要注意：.env 文件不会覆盖已有的环境变量。如果系统环境变量中已经设置了某个 Key，.env 中的同名 Key 会被忽略。这意味着你在排查问题时，如果发现 .env 里的值没生效，很可能就是被更高优先级的变量覆盖了。
迁移步骤详解
第一步：清点现有密钥
先看看 openclaw.json 里到底有哪些 Key：
cat ~/.openclaw/openclaw.json | python3 -c "
import sys, json
d = json.load(sys.stdin)
vars = d.get('env', {}).get('vars', {})
for k in vars:
print(k)"输出通常会列出所有变量名，比如 NVIDIA_API_KEY、DASHSCOPE_API_KEY、OPENCLAW_GATEWAY_TOKEN 等。
第二步：提取密钥值
接下来需要拿到每个 Key 的实际值，准备写入 .env 文件：
cat ~/.openclaw/openclaw.json | python3 -c "
import sys, json
d = json.load(sys.stdin)
vars = d.get('env', {}).get('vars', {})
for k, v in vars.items():
print(f'{k}={v}')"这一步的输出就是你要写入 .env 文件的全部内容。建议复制到一个临时文件中备份，确认无误后再从 openclaw.json 中删除。
第三步：创建 .env 文件
用你喜欢的编辑器创建 ~/.openclaw/.env：
nano ~/.openclaw/.env按以下格式写入，每行一个 KEY=VALUE：
# ===== 搜索引擎 =====
TAVILY_API_KEY=tvly-dev-你的Tavily密钥
# ===== 模型 Provider =====
GGML_N_GPU_LAYERS=0
NVIDIA_API_KEY=nvapi-你的NVIDIA密钥
LLAMA8081_API_KEY=你的本地模型密钥
OPENROUTER_API_KEY=sk-or-v1-你的OpenRouter密钥
DASHSCOPE_API_KEY=sk-你的百炼密钥
ZAI_API_KEY=你的智谱密钥
LMSTUDIO_API_KEY=你的LMStudio密钥
LONGCAT_API_KEY=你的LongCat密钥
# ===== Gateway 认证 =====
OPENCLAW_GATEWAY_TOKEN=你的Gateway令牌⚠️ 重要提醒：变量名必须与 openclaw.json 中 Provider 配置的 apiKey.id 字段完全一致。比如有时候你可能会看到 BIGMODEL_API_KEY，但实际上智谱的 apiKey.id 是 ZAI_API_KEY，两者不匹配会导致模型无法加载。
第四步：从配置文件中删除 env.vars
确认 .env 文件写入正确后，就可以从 openclaw.json 中删除明文密钥了：
python3 -c "
import json
path = '~/.openclaw/openclaw.json'
with open(path, 'r') as f:
config = json.load(f)
if 'env' in config and 'vars' in config['env']:
del config['env']['vars']
print('已删除 env.vars')
if 'env' in config and not config['env']:
del config['env']
print('已删除空的 env 节点')
with open(path, 'w') as f:
json.dump(config, f, indent=2, ensure_ascii=False)
print('保存完成')
"这段脚本会删除 env.vars 节点，如果 env 对象变为空还会一并删除 env 节点本身，保持配置文件整洁。
第五步：重启 Gateway 并验证
openclaw gateway restart重启后最简单有效的验证方式是给 AI 助手发一条消息——如果能正常回复，说明所有 Key 都已从 .env 正确加载。你也可以检查日志确认没有报错：
openclaw gateway status
迁移后的安全架构
迁移完成后，openclaw.json 中不再包含 env.vars 节点。Provider 的 apiKey 字段改用 SecretRef 格式引用环境变量：
{
"models": {
"providers": {
"longcat": {
"apiKey": { "source": "env", "provider": "default", "id": "LONGCAT_API_KEY" }
}
}
}
}这种架构的优势非常明显：
- 配置文件零敏感信息：
openclaw.json可以安全地提交到 Git，分享给他人也不会泄露密钥 - 环境变量集中管理：所有密钥统一在
.env文件中，便于审计和轮换 - 最小权限隔离：可以通过文件权限控制谁能读取
.env
安全加固建议
迁移只是第一步，以下措施能让你的密钥管理更加安全：
限制文件权限：.env 文件应该只对当前用户可读：
chmod 600 ~/.openclaw/.env加入 .gitignore：确保 .env 永远不会被误提交：
~/.openclaw/.env定期轮换密钥：尤其是那些在公共环境或高风险服务中使用的 Key，建议每季度更换一次。
生产环境考虑外部密钥管理：对于多用户或团队协作场景，可以考虑使用 secrets.providers 配合 HashiCorp Vault、AWS Secrets Manager 等外部密钥管理服务。
常见问题
Q：迁移后模型无法连接怎么办？
最常见的原因是 .env 中的变量名与 openclaw.json 中 apiKey.id 不一致。仔细核对每个变量名，注意大小写敏感。
Q：如何添加新的 Provider？
三步走：1）在 openclaw.json 中添加 Provider 配置，apiKey 使用 SecretRef 格式；2）在 ~/.openclaw/.env 中添加对应的 KEY=VALUE；3）重启 Gateway。
Q：Gateway Token 丢了怎么办？
OPENCLAW_GATEWAY_TOKEN 用于保护 Web 控制台和 API 接口。如果丢失，可以通过 openclaw gateway restart 重新生成，或在 openclaw.json 的 gateway.auth.token 中设置新的 SecretRef。
这次迁移花了我不到半小时，但从此以后分享配置文件再也不用提心吊胆了。安全这件事，越早做越简单。如果你的 OpenClaw 还在用明文存 Key，现在就动手吧。
–全文完–
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
转载请注明来自https://oklife.me。
