1. openclaw workspace 目录结构到底长什么样

openclaw workspace 是智能体的“家”，默认落在~/.openclaw/workspace。它不是一个装代码的工程目录，而是一组 Markdown 文件加少量子目录，用来定义智能体怎么说话、记住什么、能碰哪些工具、什么时候主动干活。如果你刚接触 openclaw，可以把它理解成“给智能体准备的一间带便签墙的办公室”：便签上写着规则、身份、用户偏好和当天待办，智能体每次醒来先读便签，再开始干活。

这套结构适合谁？适合同时用多个 AI 工具的人。比如你一边用 Claude Code 写代码，一边用 openclaw 跑日常任务，还希望两边共享同一套模型通道和 Key 管理方式。workspace 文件配置管得好，智能体行为就稳定；管得乱，就会出现“昨天还记得的事今天忘了”“群聊里把私密偏好说出去”这类问题。

先给一份可直接复制的目录模板，你可以照着建：

~/.openclaw/workspace/ ├── AGENTS.md # Level 1 操作指南，流程与安全边界 ├── MEMORY.md # Level 1 长期记忆，仅主会话加载 ├── SOUL.md # Level 2 人格与语气 ├── USER.md # Level 2 用户画像 ├── IDENTITY.md # Level 2 智能体身份 ├── TOOLS.md # Level 3 工具说明 ├── HEARTBEAT.md # Level 3 心跳任务清单 ├── BOOT.md # Level 4 启动检查（可选） ├── BOOTSTRAP.md # Level 4 首次引导，用完即删 ├── memory/ │ ├── 2026-06-14.md # 每日日志 │ └── 2026-06-15.md ├── .agents/ # 多智能体配置 └── .openclaw/ # 凭据与会话配置（注意权限）

按“对智能体影响程度”分四级，这个分法很实用。Level 1 是 AGENTS.md 和 MEMORY.md，直接决定行为逻辑和长期记忆，改错影响最大。Level 2 是 SOUL.md、USER.md、IDENTITY.md，管“怎么说话”和“我是谁”。Level 3 是 memory/ 日志、TOOLS.md、HEARTBEAT.md，属于运行辅助。Level 4 是 BOOT.md、BOOTSTRAP.md，扩展或一次性文件。

一个常见误区是把所有内容塞进 AGENTS.md。我见过有人把用户偏好、工具说明、心跳任务全写在一个文件里，结果每次会话加载的上下文特别长，既费 token 又容易让模型抓不住重点。正确做法是按职责拆开：流程规则进 AGENTS.md，语气进 SOUL.md，用户信息进 USER.md，工具约定进 TOOLS.md。这样每个文件都短，加载时也清晰。

还有一点要提醒：MEMORY.md只在主会话（私有会话）加载，群聊或和他人共享的会话里不会加载。这是隐私设计，不是 bug。所以涉及个人偏好、预算权限、项目截止日期这类信息，放 MEMORY.md 是安全的；但如果你在群聊里发现智能体“不记得”这些，那是预期行为。

目录建好后，下一步是让这些文件真正被智能体读到。openclaw 的启动逻辑是：每次会话开始，先读 runtime 提供的启动上下文，其中可能已经包含 AGENTS.md、SOUL.md、USER.md 以及当天和昨天的 memory 日志。你不需要在 AGENTS.md 里再手动写一遍“请读取这些文件”，那样反而重复。AGENTS.md 里更该写的是“不要重复读，除非用户明确要求或上下文缺失”。

把目录结构和分级搞清楚，后面配置文件和统一 Key 接入才有稳定的落脚点。下一节先解决一个更前置的问题：多工具协作时，模型 endpoint 和 Key 怎么统一管。

2. TaoToken 前置：多工具统一 Key 通道怎么搭

多工具协作最烦的不是写配置，而是 Key 散落各处。Claude Code 一套、Cline 一套、openclaw 又一套，换模型时要挨个改，某个 Key 额度用完还得翻半天是哪个工具在报 401。我试过把 endpoint 统一到 TaoToken，思路是：所有工具都指向同一个 Base URL，用同一把 Key，模型 ID 按需切换。这样额度、日志、排障都在一个地方看。

TaoToken 在这里扮演的是统一模型通道。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。你需要先拿到 Key，再去控制台确认模型 ID。

拿 Key 的路径：打开 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，创建一把新 Key，复制保存。注意 Key 只在创建时完整显示一次，关掉页面就看不到了，建议直接存进密码管理器。

模型 ID 去哪看？在模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 里可以试跑，确认哪个模型 ID 可用、响应正常。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各工具的配置示例，遇到字段不确定时优先查这里。

如果你长期用编码类工具，比如 Claude Code 或 Codex 这类 Agent 场景，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它更适合高频、长时间的编码任务，和按量调用是两种用法，按自己的使用强度选。

统一 Key 通道的核心是三件套：Base URL、Key、Model ID。任何工具接入时都绕不开这三个。Base URL 统一填https://taotoken.net/api，Key 用刚创建的那把，Model ID 按工具支持的模型填。下面给一个对照表，方便你在不同工具间迁移：

这里有个实操建议：不要所有工具共用一把 Key。虽然统一通道的目的是集中管理，但一工具一 Key 更利于排障。哪个工具出问题，直接看对应 Key 的调用记录，吊销也只影响一个工具。控制台里可以给 Key 起名字，比如openclaw-main、claude-code-dev，一眼能认出来。

还有一个前置动作容易被忽略：确认你的工具走的是哪种协议。Claude Code 走 Anthropic 协议，Cline、Codex 这类多走 OpenAI 兼容协议。TaoToken 的接入文档里对两种协议都有说明，配置时看清楚字段名，别把base_url和ANTHROPIC_BASE_URL搞混。下一节直接给可复制的配置片段。

3. 可复制配置：openclaw 与多工具 settings 片段

这一节给能直接抄的配置。先处理 openclaw 的 workspace 配置文件，再给 Claude Code、Cline MCP、Codex 的接入片段。所有片段里的 Base URL 都指向https://taotoken.net/api，Key 用你自己的替换。

先看 openclaw 侧的配置。openclaw 的凭据和会话配置一般放在~/.openclaw/下，workspace 根目录放行为文件。假设你要在 workspace 里声明模型通道，可以建一个config.toml放在~/.openclaw/：

# ~/.openclaw/config.toml [model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-你的Key" model_id = "你的模型ID" timeout_seconds = 60 [workspace] path = "~/.openclaw/workspace" load_on_start = ["AGENTS.md", "SOUL.md", "USER.md"] main_session_only = ["MEMORY.md"]

注意main_session_only这一项，它对应前面说的 MEMORY.md 只在主会话加载。把隐私边界写进配置，比只写在文档里更可靠。

如果你用 Claude Code，配置走 Anthropic 协议。在项目根目录或用户目录建.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "你的模型ID" } }

这里三件套齐全：Base URL、Key、Model ID。少任何一个都可能报错。Claude Code 的配置路径要和你实际使用的一致，用户级配置在~/.claude/settings.json，项目级在项目下的.claude/settings.json，项目级优先。

Cline 走 MCP 时，配置通常写在 MCP 的 settings 里。以常见的 JSON 配置为例：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "your-mcp-server"], "env": { "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-你的Key", "OPENAI_MODEL": "你的模型ID" } } } }

Codex 的配置走auth.json，路径一般在~/.codex/auth.json：

{ "OPENAI_API_KEY": "sk-你的Key", "OPENAI_BASE_URL": "https://taotoken.net/api", "model": "你的模型ID" }

同样三件套齐全。Codex 对字段名比较敏感，OPENAI_BASE_URL不要写成BASE_URL，否则会走默认地址。

配置改完后，建议做一次语法检查。JSON 文件可以用python -m json.tool验证：

python -m json.tool ~/.claude/settings.json

TOML 文件可以用 Python 的 tomllib 验证：

python -c "import tomllib; tomllib.load(open('$HOME/.openclaw/config.toml','rb')); print('ok')"

输出ok说明格式没问题。这一步能挡掉大部分“配置看起来对但就是不生效”的问题，因为很多工具在 JSON 语法错误时会静默回退到默认配置，不报错。

最后提醒一个 workspace 文件配置的细节：AGENTS.md 里不要写死模型名。模型 ID 应该放在配置层，行为层只写“用当前配置的模型”。这样换模型时只改一处，不用动 AGENTS.md。下一节验证请求是否真的走通了。

4. 验证请求：从 curl 到 openclaw 启动实测

配置写完必须验证，否则你不知道是配置生效了还是工具在偷偷用旧通道。验证分三层：先用 curl 直接打 API，再验证工具级配置，最后看 openclaw 启动时是否读到 workspace 文件。

第一层，curl 验证 Key 和 Base URL 是否可用：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "你的模型ID", "messages": [{"role": "user", "content": "只回复两个字：通了"}] }'

如果返回里有choices字段，且内容包含“通了”，说明 Key、Base URL、Model ID 三件套都对。如果返回 401，是 Key 问题；返回 404，多半是 Base URL 或路径问题；返回 model not found，是 Model ID 问题。这三种错误下一节会细讲。

第二层，验证 Claude Code 是否走新通道。启动 Claude Code 后，在会话里问一个只有新通道模型才知道的问题，或者直接看启动日志。更可靠的办法是临时把 Key 改错，看是否报 401。如果改错 Key 后仍能正常回答，说明配置没生效，工具还在用旧通道。

第三层，验证 openclaw 启动时读到 workspace 文件。在 AGENTS.md 里加一行明显的标记，比如：

## Session Startup - 每次会话开始时，在回复末尾附上标记 [WS-OK]

然后启动 openclaw，发一条消息。如果回复末尾出现[WS-OK]，说明 AGENTS.md 被正确加载。这个技巧很土但很有效，比翻日志快。

再验证 MEMORY.md 的隐私边界。在主会话里让智能体记住一件事，然后去群聊会话里问它，看是否“不记得”。如果群聊里也能答出来，说明main_session_only配置没生效，需要检查 config.toml 的字段名。

验证 memory 日志是否写入。让智能体执行一个任务，然后检查~/.openclaw/workspace/memory/下当天的文件：

ls -la ~/.openclaw/workspace/memory/ cat ~/.openclaw/workspace/memory/$(date +%F).md

如果文件存在且有内容，说明日志写入正常。如果文件不存在，检查 AGENTS.md 里有没有写“记录到当天 memory 文件”的规则，以及 workspace 目录是否有写权限。

验证 HEARTBEAT.md 是否被识别。这个需要触发一次心跳轮询，不同部署方式触发方式不同。简单办法是在 HEARTBEAT.md 里写一条“每次心跳在 memory 里追加一行 heartbeat-ok”，然后等一个心跳周期，看日志里有没有这行。如果没有，检查心跳功能是否启用。

实测下来，最容易出问题的是路径。openclaw 默认路径是~/.openclaw/workspace，但如果你用容器或改了 HOME，实际路径可能不同。用echo $HOME确认，再对照配置里的path字段。路径不对，所有文件都读不到，但工具不一定报错，只会表现成“智能体什么都不记得”。

验证通过后，建议把 curl 命令存成一个脚本，换 Key 或换模型时快速复测。下一节集中处理常见报错。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来。每个报错给现象、原因、修法。

401 Unauthorized。现象是 curl 或工具返回 401。原因通常是 Key 错、Key 过期、Key 没带Bearer前缀、或者 Key 和 Base URL 不匹配（比如用了 A 平台的 Key 打 B 平台的地址）。修法：先确认 Key 是从 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 创建的，再确认请求头是Authorization: Bearer sk-xxx。如果工具配置里字段名是api_key而不是Authorization，按工具文档填，别自己拼。

local proxy failed。现象是工具启动时报本地代理失败。这个报错和网络代理无关，通常是工具内部的本地转发层没起来，或者端口被占。修法：检查工具配置里的 Base URL 是否写成了http://localhost:xxxx这类本地地址。如果你要统一到 TaoToken，Base URL 应该是https://taotoken.net/api，不是本地地址。另外检查是否有其他进程占了工具默认端口，换端口或关掉冲突进程。

reading choices 报错。现象是返回体解析失败，提示读取choices字段出错。原因通常是返回的不是标准 OpenAI 格式，比如返回了 HTML 错误页、或者模型 ID 不对导致返回了错误结构。修法：先用 curl 看原始返回，确认返回体是 JSON 且有choices。如果返回的是 HTML，说明 Base URL 打到了网页而不是 API，检查路径有没有多写或少写/v1。如果返回 JSON 但没有choices，看error字段的内容。

OAuth 相关报错。现象是 Claude Code 或类似工具提示 OAuth 失败、token 无效。原因是你可能同时配了 OAuth 登录和 API Key，两者冲突。修法：用 API Key 接入时，确保没有残留的 OAuth 凭据。Claude Code 可以检查~/.claude/下是否有旧的凭据文件，必要时清理后重新用 settings.json 配置。注意不要混用两种认证方式。

再补一个 workspace 文件相关的报错：智能体启动后不读 AGENTS.md。现象是行为规则不生效。原因可能是文件不在 workspace 根目录、文件名大小写不对（Linux 下agents.md和AGENTS.md是两个文件）、或者配置里的load_on_start没包含它。修法：用ls -la ~/.openclaw/workspace/确认文件名，对照 config.toml 的load_on_start列表。

还有一个隐蔽问题：改了配置文件但没重启工具。大部分工具只在启动时读配置，改完要重启。openclaw 改 workspace 文件后，新会话会重新读，但当前会话可能还用旧上下文。养成“改配置就重启”的习惯，能省很多排查时间。

排障时优先看原始返回，不要只看工具封装的错误信息。工具经常把底层错误包装成一句模糊提示，curl 能看到真相。把 curl 命令和工具配置对照着看，大部分问题十分钟内能定位。

6. 把 workspace 和统一 Key 用顺手的几个习惯

配置跑通只是开始，用顺手靠习惯。第一个习惯：workspace 文件改动走版本管理。把~/.openclaw/workspace初始化成 git 仓库，每次改 AGENTS.md 或 SOUL.md 前先 commit。这样改坏了能回滚，也能看到“哪次改动导致智能体行为变了”。注意.openclaw/下的凭据不要提交，加进.gitignore。

第二个习惯：Key 轮换有流程。一工具一 Key，轮换时先建新 Key，改配置，验证通过后再吊销旧 Key。不要先吊销再建，中间会有空窗期。控制台里给 Key 标注用途和创建日期，三个月轮换一次。

第三个习惯：memory 日志定期归档。memory/目录会越积越多，建议每月把旧日志移到memory/archive/，只保留最近两周在主目录。AGENTS.md 里写清楚归档规则，让智能体自己维护。这样启动时加载的日志不会无限增长。

第四个习惯：HEARTBEAT.md 保持短。一行一任务，超过十行就考虑拆分或降低频率。心跳任务每次触发都消耗 token，任务越多成本越高。把“必须定期做”的放 HEARTBEAT.md，“想起来才做”的放 AGENTS.md 的流程里。

第五个习惯：换模型先改配置层，不动行为层。模型 ID 只在 config.toml 或工具 settings 里出现，AGENTS.md、SOUL.md 里不写具体模型名。这样换模型时改一处，验证一次，所有工具同步生效。

如果你还在选长期编码方案，可以对比按量调用和 Coding Plan 的差异：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。高频编码任务用 Coding Plan 更省心，偶尔调用按量即可。控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理和用量查看都在里面。接入细节查文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，模型可用性在对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 实测。

最后说个真实经验：workspace 文件配置最怕“一次写太多”。先让 AGENTS.md 跑通基本流程，再加 SOUL.md 调语气，再加 HEARTBEAT.md 做定时任务。每加一个文件，验证一次行为变化。这样出问题时你知道是哪个文件导致的。一口气配完再调，排查成本会高很多。