1. 第一次打开 ~/.openclaw 时我到底在看什么
如果你刚把 OpenClaw 跑起来，兴冲冲地cd ~/.openclaw，大概率会愣住：一堆目录、几个 json、还有 workspace 里那些 md 文件，名字看着都认识，但谁管谁、改了会不会炸，完全没底。这篇就把 OpenClaw 本地文件目录从 workspace 到 openclaw.json 逐层拆开，讲清楚每个文件是干什么的、数据从哪读、改完怎么验证 AI 助手真的加载了。适合刚接触 OpenClaw、想弄明白数据存放与读取逻辑的开发者。
先说结论：OpenClaw 是本地优先的设计，你的对话历史、记忆、配置、凭证全部落在本地文件系统里，没有数据库，纯文本存储。这意味着你可以直接cat、grep、git diff你的 AI 助手状态。理解目录结构不是为了背文件清单，而是为了三件事：出问题时知道去哪看日志、想改行为时知道改哪个文件、迁移或备份时知道该打包什么。
我按"根目录 → workspace → agents → 关键文件 → 验证"的顺序走一遍，每一步都给可复制的命令和目录树，你可以边看边对照自己的机器。
先看整体骨架，这是~/.openclaw/的典型结构（旧版本可能在~/openclaw）：
~/.openclaw/ ├── openclaw.json # 主配置，系统的心脏 ├── openclaw.json.bak # 配置自动备份 ├── update-check.json # 版本更新检查记录 ├── exec-approvals.json # 危险操作审批记录 ├── agents/ # 每个 Agent 的独立目录 ├── credentials/ # API Key、OAuth 令牌 ├── extensions/ # 通道插件、功能扩展 ├── skills/ # 从 ClawHub 安装的技能 ├── workspace/ # Agent 唯一可操作的工作区 ├── logs/ # 运行日志 ├── browser/ # 浏览器自动化数据 ├── canvas/ # 可视化工作区状态 ├── cron/ # 定时任务 ├── devices/ # 已连接设备 ├── identity/ # 身份认证数据 └── completions/ # 自动补全缓存这里有个容易踩的坑：workspace/和agents/是两个不同层级的东西。workspace/是 Agent 干活的地方，放记忆、规则、技能；agents/是每个 Agent 的运行时状态，放会话历史、模型配置。很多人第一次改配置改错了地方，就是因为把这两个混了。
用一条命令先确认你的实际路径，避免照着旧教程找错目录：
echo $OPENCLAW_HOME ls -la ~/.openclaw/如果OPENCLAW_HOME有输出，说明你用了环境变量覆盖，后面所有路径都要以它为准。没有输出就默认~/.openclaw/。这一步别跳过，我见过太多人对着不存在的路径折腾半天。
2. workspace 目录逐文件拆解与 openclaw.json 配置读取逻辑
workspace/是 OpenClaw 的"大脑中枢"，Agent 在这里"生活"。它下面的文件大多是 Markdown，因为设计上就是让人可读可编辑的。先看目录树：
workspace/ ├── AGENTS.md # 行为准则与工作规范（必填） ├── SOUL.md # 核心人格与价值观（必填） ├── IDENTITY.md # 身份定义（必填） ├── USER.md # 用户信息与偏好（必填） ├── TOOLS.md # 本地工具与环境配置 ├── MEMORY.md # 长期记忆精华 ├── BOOTSTRAP.md # 首次启动引导 ├── HEARTBEAT.md # 周期性任务清单 ├── skills/ # 技能文件目录 └── memory/ # 每日记忆日志 ├── 2025-01-15.md └── 2025-01-16.md四个必填文件的分工要记牢：AGENTS.md是"员工手册"，定义每个会话里的行为规范和安全边界；SOUL.md塑造人格和响应风格；IDENTITY.md写明名称、角色、能力范围；USER.md记录你的偏好，让助手能个性化服务。这四个文件在每次会话启动时都会被读取并注入上下文，所以改完立刻生效，不用重启。
记忆系统是双引擎，这点值得单独讲。MEMORY.md类比长期记忆，是经过筛选提炼的精华，只在主会话（一对一私聊）时加载，群聊或共享会话里不会暴露。memory/YYYY-MM-DD.md是每日原始流水账，采用 Append-only 模式，系统每次会话自动加载"今天+昨天"的内容。这个设计的好处是：原始日志不会丢，精华记忆可控。
你可以这样验证记忆加载逻辑：
# 看今天和昨天的记忆文件是否存在 ls -la ~/.openclaw/workspace/memory/ | tail -5 # 手动追加一条测试记忆 echo "- 测试：用户偏好用中文回复" >> ~/.openclaw/workspace/memory/$(date +%F).md追加后开一个新会话问助手"我的语言偏好是什么"，如果它答得出来，说明 memory 加载链路是通的。
再看openclaw.json，这是系统的心脏，采用 JSON5 格式，支持注释和$include指令。它的顶层结构大致是：
{ "meta": { "lastModifiedVersion": "0.x.x", "lastModifiedAt": "2025-01-16T10:00:00Z" }, "gateway": { "port": 18789, "mode": "local", "bind": "127.0.0.1", "auth": { "enabled": true } }, "agents": { "defaults": { "model": "claude-sonnet-4-5", "workspace": "~/.openclaw/workspace", "maxConcurrency": 2 } }, "models": { "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "models": ["claude-sonnet-4-5", "gpt-4o"] } } }, "channels": {}, "tools": {} }几个关键点：gateway.port是网关监听端口，UI 客户端都通过它查询会话状态；agents.defaults.workspace指向 workspace 路径，改这里就能切换工作区；models.providers里配置模型提供商，baseUrl和apiKey是核心。注意apiKey用了${TAOTOKEN_API_KEY}这种环境变量引用，比明文写死在配置里安全得多。
配置的读取顺序是：先读openclaw.json，再被环境变量覆盖。支持覆盖的变量有三个：OPENCLAW_HOME改主目录、OPENCLAW_STATE_DIR改状态目录、OPENCLAW_CONFIG_PATH直接指定配置文件路径。排查"为什么改了配置没生效"时，先env | grep OPENCLAW看看有没有环境变量在捣乱。
agents/目录下每个 Agent 一个子目录，以 Agent ID 命名。以主 Agent（通常叫main）为例：
agents/main/ ├── sessions/ │ ├── sessions.json # 会话元数据 │ └── <sessionId>.jsonl # 详细会话历史 ├── auth-profiles.json # Agent 特定认证 ├── models.json # Agent 模型配置 └── qmd/ # QMD 后端索引sessions.json存 sessionId、token 计数、memoryFlush 状态这些元数据；<sessionId>.jsonl是 Append-only 的 JSONL，记录完整对话树，包括消息、工具调用和压缩摘要。想看某次对话到底发生了什么，直接tail -f对应的 jsonl 就行，比翻 UI 快。
3. 可复制配置：把模型接入写进 openclaw.json 并验证加载
这一节给你一份能直接抄的配置，把模型提供商接进 OpenClaw，并演示改完怎么验证。假设你要接入 TaoToken 的 API，先拿 Key：打开 https://taotoken.net/api-keys 创建，然后写进环境变量，别硬编码进配置文件。
# 写入 shell 配置，持久化 echo 'export TAOTOKEN_API_KEY="sk-你的key"' >> ~/.bashrc source ~/.bashrc echo $TAOTOKEN_API_KEY # 确认有输出然后编辑~/.openclaw/openclaw.json，在models.providers下加一段。注意 JSON5 允许注释和尾逗号，但为了兼容性我建议还是写标准 JSON 风格：
{ "models": { "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "models": [ "claude-sonnet-4-5", "claude-opus-4-1", "gpt-4o" ], "defaultModel": "claude-sonnet-4-5" } } }, "agents": { "defaults": { "model": "taotoken/claude-sonnet-4-5", "workspace": "~/.openclaw/workspace", "maxConcurrency": 2 } } }三件套要写全：Base URL 是https://taotoken.net/api，Key 走环境变量引用，Model ID 明确到claude-sonnet-4-5这种粒度。agents.defaults.model里的taotoken/前缀是 provider 名，必须和providers下的键一致，写错了会报模型找不到。
如果你用 Claude Code 这类工具，配置思路一样，只是文件位置不同。Claude Code 的配置在~/.claude/settings.json，把ANTHROPIC_BASE_URL指向https://taotoken.net/api，ANTHROPIC_API_KEY填你的 Key，模型 ID 用claude-sonnet-4-5。Cline 的 MCP 配置则在cline_mcp_settings.json里，同样三件套。Codex 用户改~/.codex/auth.json，结构类似。核心永远是 Base URL + Key + Model ID，缺一个都连不上。
改完配置别急着开聊，先做语法校验。OpenClaw 自带 doctor 命令：
openclaw doctor它会检查配置文件语法、路径可达性、凭证有效性。如果输出里有config parse error，多半是 JSON5 的注释或尾逗号写错了位置。修完再跑一次，直到全绿。
4. 验证请求：确认 AI 助手真的加载了新配置
配置写完不等于生效，得验证。分三步：网关状态、配置加载、实际请求。
第一步，看网关是否在跑、端口对不对：
openclaw gateway status正常输出会显示running和监听端口（默认 18789）。如果显示stopped，先openclaw gateway start。
第二步，确认配置被正确解析。用一个查询命令把当前生效的模型配置打出来：
openclaw config get agents.defaults.model应该返回taotoken/claude-sonnet-4-5。如果返回的是旧值或空，说明配置文件没被读到，检查OPENCLAW_CONFIG_PATH环境变量是否指向了别处。
第三步，发一个真实请求。最直接的方式是开一个会话问一句：
openclaw chat "用一句话说明你现在用的是哪个模型"如果助手正常回复且内容合理，说明 Base URL、Key、Model ID 三件套都通了。想更严谨，直接看日志里的请求记录：
tail -f ~/.openclaw/logs/openclaw-*.log | grep -i "model\|provider\|request"日志里会打印实际使用的 provider 和 model，以及请求耗时。看到provider=taotoken model=claude-sonnet-4-5 status=200就稳了。
再验证一下 workspace 数据加载。改USER.md加一行偏好：
echo "- 用户是后端开发者，偏好简洁回答" >> ~/.openclaw/workspace/USER.md然后开新会话问"我是做什么的"，如果助手答出"后端开发者"，说明 workspace 文件在会话启动时被正确注入了。这一步能帮你确认 workspace 路径配置没写错。
会话历史也可以直接查。找到最近的 sessionId：
ls -t ~/.openclaw/agents/main/sessions/*.jsonl | head -1然后tail它，能看到刚才那轮对话的完整记录，包括你发的消息、模型返回、工具调用。这是排查"助手为什么这么答"最硬的证据。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
配置和验证过程中，报错基本集中在几个固定位置。这一节按真实报错对照排查。
401 Unauthorized：最常见。先确认环境变量有没有被正确读取：
echo $TAOTOKEN_API_KEY如果为空，说明source ~/.bashrc没生效，或者你写进了.zshrc但用的是 bash。Key 本身也要检查有没有多余空格或换行，echo出来看看首尾。还有一种情况是配置文件里写的是明文 Key 但带了引号，JSON5 解析后引号被当成 Key 的一部分，去掉引号或改用环境变量引用。
local proxy failed / connection refused：通常是网关没起来或端口被占。先openclaw gateway status，再lsof -i :18789看端口占用。如果被别的进程占了，改openclaw.json里的gateway.port换个端口，重启网关。另外检查gateway.bind是不是绑到了127.0.0.1，如果你从别的机器访问，需要改成0.0.0.0并配好认证。
reading choices / cannot read property choices：这个报错一般出现在模型返回格式不符合预期时。常见原因是 Base URL 写错了，比如漏了/api或多了斜杠，导致请求打到了错误的端点，返回了 HTML 而不是 JSON。确认baseUrl是https://taotoken.net/api，不要带尾斜杠。另一个原因是 Model ID 拼错，provider 找不到对应模型，返回了错误结构。用openclaw config get models.providers核对一遍。
OAuth 相关报错：如果你用的是需要 OAuth 的 provider，credentials/目录下的令牌可能过期了。先看目录权限：
ls -la ~/.openclaw/credentials/权限应该是700，只有当前用户可读写。令牌过期就重新走一遍授权流程，或者改用 API Key 方式接入，省去 OAuth 刷新环节。agents/main/auth-profiles.json里存的是 Agent 特定的认证配置，如果这里和全局credentials/冲突，以 Agent 级为准，排查时两个都看。
配置改了不生效：九成是环境变量覆盖。跑env | grep OPENCLAW，看有没有OPENCLAW_CONFIG_PATH指向了另一个文件。另外openclaw.json.bak是自动备份，别手动去改它，回滚用cp openclaw.json.bak openclaw.json就行。
workspace 文件不加载：检查agents.defaults.workspace路径是否存在、是否有读权限。路径里的~在某些环境下不会自动展开，建议写绝对路径。还有一点，MEMORY.md只在主会话加载，如果你在群聊里测试，它本来就不该出现，别误判成 bug。
排查完记得跑一次openclaw doctor收尾，它会把你可能漏掉的路径和权限问题一起报出来。
6. 从文件系统继续深入：备份、日志与下一步
把目录结构摸清之后，日常维护就简单了。备份直接打包整个状态目录：
tar -czf openclaw-backup-$(date +%F).tar.gz ~/.openclaw/重点是openclaw.json和workspace/，前者是配置，后者是记忆和人格。openclaw.json.bak系列是自动生成的，回滚时直接覆盖即可。日志在logs/下，长期运行记得定期清理旧文件，browser/目录的缓存也容易膨胀，偶尔看一眼大小。
想继续深入模型接入和 Agent 编码能力，可以看接入文档 https://taotoken.net/doc ，里面有各工具的完整配置示例。想先试试模型对话效果，直接开 https://taotoken.net/chat 聊两句，确认 Key 能用再往配置里写。如果你打算长期跑编码类 Agent，Coding Plan https://taotoken.net/coding-plan 会更合适，额度和并发都按开发场景调过。
最后留一个实用习惯：把~/.openclaw/workspace/纳入 git 管理。AGENTS.md、SOUL.md、USER.md这些文件的每次修改都有 diff 可查，助手"性格"变了能追溯到是哪次改动导致的。配置文件里的 Key 用环境变量引用，就不会误提交敏感信息。这样你的 AI 助手数据家园既是本地的，也是可版本控制的。
