03. 配置和模型：openclaw.json、状态目录和 auth profiles

这篇解决什么问题

OpenClaw 的很多问题，看起来像 Agent 问题，实际是配置问题。

例如：Gateway 能启动但平台消息没响应、模型调用失败、channel 收不到消息、agent session 找不到历史、cron 触发了但没有投递。

这类问题先看配置和状态目录。

默认状态目录

默认状态目录是：

~/.openclaw

官方 runtime workflow 文档也写到：如果设置了 OPENCLAW_STATE_DIR，就使用该目录。

你会在这里看到：

openclaw.json
credentials/
agents/<agentId>/sessions/
agents/<agentId>/agent/auth-profiles.json
sessions/            # 可能存在 legacy path
workspace/
cron/
logs/

不同版本和迁移历史下，目录可能会有差异。排障时不要只看一个路径。

主配置文件

常见主配置是：

~/.openclaw/openclaw.json

它会涉及 Gateway、channels、agents、sandbox、tools、skills、model/provider、safety policy。

源码里配置相关逻辑主要在：

src/config/

这个目录很大，因为 OpenClaw 要兼容很多 channel、provider、旧配置迁移和安全策略。

模型和 auth profiles

OpenClaw 支持多 provider。README 里提到模型配置和 CLI 在 Models 页面，auth profile rotation 和 fallbacks 在 Model failover 页面。

本地状态里，官方 workflow 文档提到：

agents/<agentId>/agent/auth-profiles.json

用于模型 auth profiles，例如 API keys + OAuth。

这意味着模型凭证不一定都在主配置里。排查 401、provider 不可用时，要同时看 config 和 auth profile。

Channels 配置

OpenClaw 支持很多 channel。每个 channel 都有自己的 token、allowlist、pairing、webhook 或长连接方式。

相关源码主要在：

src/channels/
extensions/<channel>/
src/config/types.<channel>.ts

不要把 channel 问题都归到 Gateway。Gateway 是控制平面，具体平台接入还有 channel adapter 和 extension。

DM pairing 和 allowlist

README 明确提醒：OpenClaw 连接真实消息平台，inbound DMs 要当成不可信输入。

陌生人发消息时，可能只收到 pairing code，不会进入 Agent。

这不是 bug，是安全默认值。

配置排查顺序

1. OPENCLAW_STATE_DIR 是否设置
2. ~/.openclaw/openclaw.json 是否是当前实例读取的文件
3. Gateway 是否运行
4. channel 是否启用并有凭证
5. allowlist / dmPolicy 是否允许当前发送者
6. agentId / session 是否路由正确
7. 模型 auth profile 是否可用
8. 工具/sandbox 是否被策略限制

下一篇看什么

下一篇看项目结构。