OpenClaw v2026.3.23 安全配置复盘：从多处明文到集中受控存储《OpenClaw 安全部署 SOP（v2026.3.23）V2》

下面是整理后的 《OpenClaw 安全部署 SOP（v2026.3.23）V2》 。这一版把前面踩过的坑、尤其是 auth-profiles.json / 多 agent / keyRef 写法的经验，正式纳入 SOP。

OpenClaw 安全部署 SOP（v2026.3.23）V2

1. 目标

本 SOP 的目标是把 OpenClaw 的敏感信息管理收敛到最小暴露面、最少明文、最好审计的状态：

真实 secret 尽量只保留在 ~/.openclaw/.env
openclaw.json 使用 SecretRef
auth-profiles.json 使用 keyRef / tokenRef
models.json 仅保留 marker，不保留真实密钥
多 agent 环境逐个校验，不假设配置自动继承
使用 audit / status / doctor 做最终验收

2. 适用范围

适用于以下场景：

已安装 OpenClaw v2026.3.23
单机部署或长期运行的 gateway / daemon
使用 OpenAI / Moonshot / Kimi 等 API key 或 token 模式
存在多个 agent，例如 main、xiaoshuai 等

3. 设计原则

3.1 单点收敛真实 secret

所有真实 API key / token 尽量只集中在：

text 复制代码

~/.openclaw/.env

不要把真实 secret 分散在：

~/.zshrc
~/.zshenv
~/.bashrc
openclaw.json
auth-profiles.json
models.json

3.2 不同文件使用不同的官方机制

这是本 SOP 最重要的原则之一：

文件	正确方式	说明
`openclaw.json`	SecretRef 对象	全局配置引用 secret
`auth-profiles.json`	`keyRef` / `tokenRef`	同级字段，不是替换 `key` / `token`
`models.json`	marker 字符串	例如 `KIMI_API_KEY`，不是明文

3.3 权限控制是底线

建议最少做到：

bash 复制代码

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/.env
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json
chmod 600 ~/.openclaw/agents/*/agent/models.json

3.4 多 agent 独立检查

不要假设：

main 正常，其他 agent 也正常
全局配置改好了，agent 配置就会自动没问题
新建 agent 后会自动拥有可用的认证 profile

每个 agent 都要单独检查其 auth-profiles.json 和 models.json。

4. 标准部署步骤

步骤 1：创建安全目录与权限

bash 复制代码

mkdir -p ~/.openclaw
chmod 700 ~/.openclaw
touch ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

步骤 2：将真实 secret 收敛到 `~/.openclaw/.env`

示例：

bash 复制代码

OPENCLAW_GATEWAY_TOKEN=your-gateway-token
OPENAI_API_KEY=sk-...
MOONSHOT_API_KEY=sk-...
KIMI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

要求：

所有真实 secret 统一收敛到 .env
shell 启动文件不再保存敏感信息
后续所有配置文件只保留引用，不保留真实值

步骤 3：清理 shell 配置中的敏感信息

从以下文件中删除真实 API key / token：

~/.zshrc
~/.zshenv
~/.zshrc.local
~/.bashrc
~/.profile

必要时清理 shell history，避免历史命令中保留敏感值。

步骤 4：配置 `openclaw.json`

错误示例：直接写明文

json 复制代码

{
  "gateway": {
    "auth": {
      "token": "real-token"
    }
  }
}

正确示例：使用 SecretRef

json 复制代码

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

模型 provider 的 apiKey 也按同样思路改为 SecretRef。

步骤 5：配置 `auth-profiles.json`

这是最容易出错的地方。

5.1 `api_key` 类型 profile 的正确写法

错误写法：把 `key` 改成对象

json 复制代码

{
  "profiles": {
    "kimi:default": {
      "type": "api_key",
      "provider": "kimi",
      "key": {
        "source": "env",
        "provider": "default",
        "id": "KIMI_API_KEY"
      }
    }
  }
}

这种写法可能导致：

text 复制代码

cred.key?.trim is not a function

正确写法：使用同级 `keyRef`

json 复制代码

{
  "version": 1,
  "profiles": {
    "kimi:default": {
      "type": "api_key",
      "provider": "kimi",
      "keyRef": {
        "source": "env",
        "provider": "default",
        "id": "KIMI_API_KEY"
      }
    }
  },
  "lastGood": {},
  "usageStats": {}
}

5.2 `token` 类型 profile 的正确写法

对于 token 类型，使用同级 tokenRef，不要把 token 直接写成对象。

5.3 严格要求

不要把 key 直接对象化
不要把 token 直接对象化
不要同时保留 key 和 keyRef
不要同时保留 token 和 tokenRef
profiles 不能为空对象，空的 profiles: {} 可能导致 agent 认证失败

步骤 6：检查并修正 `models.json`

models.json 的目标状态：

不保留真实 secret
使用 marker，例如：

json 复制代码

{
  "providers": {
    "kimi": {
      "apiKey": "KIMI_API_KEY"
    },
    "moonshot": {
      "apiKey": "MOONSHOT_API_KEY"
    }
  }
}

注意：

这里的 "KIMI_API_KEY" 是环境变量名，不是真实 key
如果看到 sk-... 这类真实值，说明还没有收敛完成

步骤 7：多 agent 环境专项检查

假设存在多个 agent，例如：

main
xiaoshuai

每个 agent 都要检查：

bash 复制代码

cat ~/.openclaw/agents/main/agent/auth-profiles.json
cat ~/.openclaw/agents/main/agent/models.json
cat ~/.openclaw/agents/xiaoshuai/agent/auth-profiles.json
cat ~/.openclaw/agents/xiaoshuai/agent/models.json

重点确认：

auth-profiles.json 不为空
存在有效 profile
api_key profile 使用 keyRef
models.json 使用 marker
权限为 600

步骤 8：执行验收检查

bash 复制代码

openclaw secrets audit --check
openclaw models status --agent main
openclaw models status --agent xiaoshuai
openclaw doctor
openclaw security audit --fix

建议理解为：

secrets audit --check：看是否还有非预期明文残留
models status --agent ...：逐个 agent 看 auth 是否能正确解析
doctor：查阻塞性问题
security audit --fix：修正常见权限与安全默认值

5. 故障排查 SOP

场景 A：报错 `cred.key?.trim is not a function`

含义

通常表示 agent 在解析 auth-profiles.json 时，某个 api_key profile 的字段形态不符合预期。

最常见原因

把 key 写成了对象，而不是使用 keyRef
auth-profiles.json 为空或 profile 缺失
多 agent 环境中，某个 agent 没有独立配置认证文件

标准排查步骤

第一步：定位哪个 agent 出错

bash 复制代码

openclaw logs --follow

第二步：查看该 agent 的 `auth-profiles.json`

bash 复制代码

cat ~/.openclaw/agents/{agent-name}/agent/auth-profiles.json

第三步：检查 `.env` 是否存在对应变量

bash 复制代码

grep KIMI_API_KEY ~/.openclaw/.env

第四步：检查该 agent 的 `models.json`

bash 复制代码

cat ~/.openclaw/agents/{agent-name}/agent/models.json

第五步：修复后重启并验证

bash 复制代码

openclaw gateway restart
openclaw agent --message "测试" --session-id test

场景 B：某个 agent 无响应，但 main 正常

优先检查：

该 agent 是否有自己的 auth-profiles.json
profiles 是否为空
models.json 是否仍是旧格式
是否误以为 main 的认证会自动继承给其他 agent

6. 验收标准

满足以下条件即可视为达标：

6.1 存储层

真实 secret 收敛在 ~/.openclaw/.env
~/.openclaw/ 权限为 700
敏感文件权限为 600

6.2 配置层

openclaw.json 不再保存业务明文 secret
auth-profiles.json 使用 keyRef / tokenRef
models.json 只保留 marker，不保留真实 secret

6.3 运行层

每个 agent 的 models status 都正常
doctor 无关键阻塞
gateway 重启后能正常响应消息

6.4 审计层

secrets audit --check 不再报告配置文件中的非预期明文
.env 若被识别为 plaintext，属于"集中受控存储"的预期现象，不等于失败

7. 新建 Agent 标准动作

每次创建新 agent 后，必须做以下检查：

确认该 agent 目录存在
确认其 auth-profiles.json 不为空
确认 profile 使用 keyRef / tokenRef
确认 models.json 使用 marker
运行：

bash 复制代码

openclaw models status --agent {agent-name}

不要默认新 agent 自动继承完整认证能力。

8. 常见错误清单

错误 1：把 key 写成对象

错误：

json 复制代码

"key": { ... }

正确：

json 复制代码

"keyRef": { ... }

错误 2：认为 `main` 正常就代表全部正常

多 agent 环境里，这个判断经常是错的。

错误 3：`profiles` 为空

错误：

json 复制代码

{"version":1,"profiles":{}}

这可能直接导致 agent 无法认证。

错误 4：`models.json` 仍保存真实 key

如果里面还是 sk-... 这类真实值，说明收敛没完成。

错误 5：只改配置，不做日志和状态验证

安全配置完成后，必须至少执行：

bash 复制代码

openclaw secrets audit --check
openclaw models status --agent main
openclaw doctor

多 agent 时要逐个 agent 验证。

9. 经验总结

这次部署和排障最重要的经验有四条：

经验一：先收敛明文，再做引用化

先把真实 secret 收拢进 .env，再改配置引用，效率最高。

经验二：不同文件用不同机制

openclaw.json → SecretRef
auth-profiles.json → keyRef / tokenRef
models.json → marker

经验三：多 agent 必须逐个检查

一个 agent 修好，不代表其他 agent 也修好了。

经验四：日志是最快定位入口

看到类似：

text 复制代码

cred.key?.trim is not a function

第一反应就应该去检查该 agent 的 auth-profiles.json。

10. 一句话结论

OpenClaw v2026.3.23 的安全最佳实践，不是让所有地方都"完全没有明文"，而是把真实 secret 收敛到 ~/.openclaw/.env 这一单点，把 openclaw.json、auth-profiles.json、models.json 分别改成官方支持的 SecretRef / keyRef / marker 形式，并对每个 agent 逐个做 audit、status 和运行验证。

**。

OpenClaw v2026.3.23 安全配置复盘：从多处明文到集中受控存储《OpenClaw 安全部署 SOP（v2026.3.23）V2》

OpenClaw 安全部署 SOP（v2026.3.23）V2

1. 目标

2. 适用范围

3. 设计原则

3.1 单点收敛真实 secret

3.2 不同文件使用不同的官方机制

3.3 权限控制是底线

3.4 多 agent 独立检查

4. 标准部署步骤

步骤 1：创建安全目录与权限

步骤 2：将真实 secret 收敛到 ~/.openclaw/.env

步骤 3：清理 shell 配置中的敏感信息

步骤 4：配置 openclaw.json

错误示例：直接写明文

正确示例：使用 SecretRef

步骤 5：配置 auth-profiles.json

5.1 api_key 类型 profile 的正确写法

错误写法：把 key 改成对象

正确写法：使用同级 keyRef

5.2 token 类型 profile 的正确写法

5.3 严格要求

步骤 6：检查并修正 models.json

步骤 7：多 agent 环境专项检查

步骤 8：执行验收检查

5. 故障排查 SOP

场景 A：报错 cred.key?.trim is not a function

含义

最常见原因

标准排查步骤

第一步：定位哪个 agent 出错

第二步：查看该 agent 的 auth-profiles.json

第三步：检查 .env 是否存在对应变量

第四步：检查该 agent 的 models.json

第五步：修复后重启并验证

场景 B：某个 agent 无响应，但 main 正常

6. 验收标准

6.1 存储层

6.2 配置层

6.3 运行层

6.4 审计层

7. 新建 Agent 标准动作

8. 常见错误清单

错误 1：把 key 写成对象

错误 2：认为 main 正常就代表全部正常

错误 3：profiles 为空

错误 4：models.json 仍保存真实 key

错误 5：只改配置，不做日志和状态验证

9. 经验总结

经验一：先收敛明文，再做引用化

经验二：不同文件用不同机制

经验三：多 agent 必须逐个检查

经验四：日志是最快定位入口

10. 一句话结论

步骤 2：将真实 secret 收敛到 `~/.openclaw/.env`

步骤 4：配置 `openclaw.json`

步骤 5：配置 `auth-profiles.json`

5.1 `api_key` 类型 profile 的正确写法

错误写法：把 `key` 改成对象

正确写法：使用同级 `keyRef`

5.2 `token` 类型 profile 的正确写法

步骤 6：检查并修正 `models.json`

场景 A：报错 `cred.key?.trim is not a function`

第二步：查看该 agent 的 `auth-profiles.json`

第三步：检查 `.env` 是否存在对应变量

第四步：检查该 agent 的 `models.json`

错误 2：认为 `main` 正常就代表全部正常

错误 3：`profiles` 为空

错误 4：`models.json` 仍保存真实 key