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_KEYsk-你的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/apiKey 走环境变量引用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/apiANTHROPIC_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以及请求耗时。看到providertaotoken modelclaude-sonnet-4-5 status200就稳了。再验证一下 workspace 数据加载。改USER.md加一行偏好echo - 用户是后端开发者偏好简洁回答 ~/.openclaw/workspace/USER.md然后开新会话问我是做什么的如果助手答出后端开发者说明 workspace 文件在会话启动时被正确注入了。这一步能帮你确认 workspace 路径配置没写错。会话历史也可以直接查。找到最近的 sessionIdls -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 的 providercredentials/目录下的令牌可能过期了。先看目录权限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 能用再往配置里写。如果你打算长期跑编码类 AgentCoding Plan https://taotoken.net/coding-plan 会更合适额度和并发都按开发场景调过。最后留一个实用习惯把~/.openclaw/workspace/纳入 git 管理。AGENTS.md、SOUL.md、USER.md这些文件的每次修改都有 diff 可查助手性格变了能追溯到是哪次改动导致的。配置文件里的 Key 用环境变量引用就不会误提交敏感信息。这样你的 AI 助手数据家园既是本地的也是可版本控制的。