1. OpenClaw Workspace 里的 MD 文件到底在干什么如果你刚接触 OpenClaw看到工作目录里躺着一排.md文件——AGENTS.md、SOUL.md、IDENTITY.md、USER.md、TOOLS.md、MEMORY.md、HEARTBEAT.md——第一反应大概是这不就是几个说明文档吗删了会怎样答案是删了你的 Agent 会失忆加性格崩坏。这些 MD 文件不是给人看的 README而是 OpenClaw 在启动时读取、排序、裁剪、注入到 System Prompt 里的运行时配置骨架。它们决定了 Agent 是谁、守什么规矩、记得什么、什么时候主动干活。我实测下来OpenClaw 的 Workspace 配置加载链路大致是这样loadWorkspaceBootstrapFiles()从磁盘读文件buildBootstrapContextFiles()做预算控制默认 60K 字符上限sortContextFilesForPrompt()按 order 字段排序最后buildProjectContextSection()把内容拼进 System Prompt。压缩compaction发生后readPostCompactionContext()还会从AGENTS.md里把 Session Startup 和 Red Lines 重新提取注入保证关键规则不丢。这篇文章面向需要理解 Workspace 配置骨架的开发者交付可复制的config.toml/settings.json骨架并给出逐项验证配置生效的操作步骤。适合谁正在搭 OpenClaw 数字员工、想搞清楚 MD 文件加载优先级、或者配置改了不生效需要排障的人。2. TaoToken 前置拿到 API Key 并确认接入点OpenClaw 的模型调用需要走一个兼容 OpenAI 协议的端点。TaoToken 提供的就是这个接入层你需要在它的控制台生成 API Key然后填进 OpenClaw 的配置里。操作路径很直接打开 https://taotoken.net/api 对应的控制台入口注册后在 API Keys 页面创建一个新 Key。创建时建议按用途命名比如openclaw-workspace-dev方便后面轮换时定位。拿到 Key 之后你需要确认两件事一是 Base URL 填什么二是模型名怎么写。TaoToken 的 API 端点是https://taotoken.net/api在 OpenClaw 的 provider 配置里通常填这个作为base_url。模型名按你实际要用的填比如claude-sonnet-4-20250514这类。注意API Key 不要硬编码进AGENTS.md或任何会被注入 System Prompt 的 MD 文件。那些文件的内容会进模型上下文等于把密钥喂给模型。Key 只放在config.toml或环境变量里。如果你还没决定用哪个模型可以先在模型对话页面试一下响应质量再决定写进配置的模型名。长期跑编码或 Agent 任务的话Coding Plan 的额度模型更适合持续调用。3. 可复制配置config.toml 与 settings.json 骨架OpenClaw 的配置分两层config.toml管 provider、模型、预算这些运行时参数settings.json管 Workspace 路径、文件加载开关、注入策略。下面是我实际用的一套骨架你可以直接抄。3.1 config.toml 骨架# ~/.openclaw/config.toml [provider.taotoken] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} # 从环境变量读取不要写死 model claude-sonnet-4-20250514 timeout_seconds 120 max_retries 3 [workspace] root ~/openclaw-workspace bootstrap_budget_chars 60000 # 总预算对应 buildBootstrapContextFiles 的上限 per_file_budget_chars 12000 # 单文件上限对应 12K 那条线 [workspace.injection] enable_agents_md true enable_soul_md true enable_identity_md true enable_user_md true enable_tools_md true enable_memory_md true enable_heartbeat_md true cache_boundary_after MEMORY.md # HEARTBEAT.md 在缓存边界之下动态注入 [compaction] post_compaction_reinject true reinject_source AGENTS.md reinject_sections [Session Startup, Red Lines]这里几个参数值得展开。bootstrap_budget_chars是总预算超过这个字符数buildBootstrapContextFiles()会按 order 从低到高保留高 order 的文件可能被截断。per_file_budget_chars是单文件上限防止某个 MD 文件写太长把预算吃光。cache_boundary_after决定了哪些文件走静态缓存、哪些走动态注入——HEARTBEAT.md是唯一在边界之下的因为它内容会变。3.2 settings.json 骨架{ workspace: { files: [ { name: AGENTS.md, order: 10, subagent_visible: true, survive_compaction: true }, { name: SOUL.md, order: 20, subagent_visible: true, survive_compaction: false }, { name: IDENTITY.md, order: 30, subagent_visible: true, survive_compaction: false }, { name: USER.md, order: 40, subagent_visible: true, survive_compaction: false }, { name: TOOLS.md, order: 50, subagent_visible: true, survive_compaction: false }, { name: MEMORY.md, order: 70, subagent_visible: false, survive_compaction: false }, { name: HEARTBEAT.md,order: 99, subagent_visible: false, survive_compaction: false, dynamic: true } ] }, sandbox: { user_md_mount_mode: read_only } }order越小优先级越高AGENTS.md是 10最高。subagent_visible控制子 Agent 能不能看到这个文件——MEMORY.md和HEARTBEAT.md设为 false因为长期记忆和心跳任务不需要子 Agent 感知。survive_compaction只有AGENTS.md是 true对应源码里readPostCompactionContext()从它提取 Session Startup 和 Red Lines 重注入的逻辑。3.3 预算分配建议默认 60K 字符总预算别全用满留 40% 余量给动态内容和工具列表。参考分配文件建议大小占比理由AGENTS.md4000-800010-15%核心规则需完整SOUL.md500-15001-3%人格定义简洁有力IDENTITY.md300-8002%名片信息USER.md500-30001-5%用户画像TOOLS.md1000-40002-7%环境配置MEMORY.md4000-800010-15%长期记忆HEARTBEAT.md200-10002%任务清单合计约 25K占 40% 左右。剩下的预算留给 System Prompt 里的工具列表、运行时信息和对话历史。4. 验证请求确认配置真的生效了配置写完不代表生效。OpenClaw 的加载链路有好几个环节任何一环出错都会导致 MD 文件没被注入。下面是我用的逐项验证步骤。4.1 验证文件被读取先确认loadWorkspaceBootstrapFiles()能读到文件。在 Workspace 根目录跑ls -la ~/openclaw-workspace/*.md应该看到 7 个文件。如果某个文件缺失OpenClaw 会跳过它而不是报错所以这一步必须手动确认。4.2 验证排序与预算用一个最小的调试脚本模拟排序逻辑# verify_order.py import json with open(settings.json) as f: cfg json.load(f) files sorted(cfg[workspace][files], keylambda x: x[order]) total 0 budget 60000 for f in files: size f.get(size, 0) total size status OK if total budget else OVER_BUDGET print(forder{f[order]:3} {f[name]:15} size{size:6} cumulative{total:6} {status})跑出来如果某个文件标了OVER_BUDGET说明它会被截断需要压缩内容或调大预算。4.3 验证注入结果最直接的验证启动 OpenClaw 后发一条消息让它复述自己的规则。比如请列出你当前遵守的 Session Startup 步骤和 Red Lines。如果AGENTS.md被正确注入Agent 应该能准确复述。如果它说我没有这些信息说明注入链路断了。4.4 验证压缩后重注入这一步容易被忽略。触发一次压缩对话足够长然后问你刚才压缩后还记得哪些核心规则如果post_compaction_reinject生效Agent 应该还能说出 Session Startup 和 Red Lines。如果它失忆了检查config.toml里reinject_source和reinject_sections是否拼写正确。4.5 验证 HEARTBEAT 动态注入HEARTBEAT.md是唯一动态文件。在文件里写一行测试任务- 每 30 分钟检查一次待办队列然后观察 OpenClaw 的日志应该能看到心跳触发时HEARTBEAT.md被重新读取。如果日志里没有检查dynamic: true是否设了以及cache_boundary_after是否指向了MEMORY.md。5. 本篇常见错排查5.1 改了 MD 文件但 Agent 行为没变最常见的原因OpenClaw 只在启动时读一次静态文件。改完SOUL.md或AGENTS.md后需要重启进程或者触发一次 workspace reload。HEARTBEAT.md例外它是动态的改了下次心跳就生效。5.2 报错 bootstrap budget exceeded总预算 60K 被吃满了。排查顺序先看MEMORY.md是不是膨胀了长期记忆最容易失控再看AGENTS.md是不是写成了万字长文。临时方案是调大bootstrap_budget_chars但根本方案是精简内容。5.3 API 返回 401 或 403Key 没读到。检查config.toml里api_key ${TAOTOKEN_API_KEY}对应的环境变量是否真的导出了echo $TAOTOKEN_API_KEY如果为空说明环境变量没设。别把 Key 直接写进 toml那样轮换时容易漏改。5.4 子 Agent 看不到某个文件检查settings.json里对应文件的subagent_visible。MEMORY.md和HEARTBEAT.md默认是 false这是设计如此不是 bug。如果你确实需要子 Agent 读记忆改成 true但要注意上下文膨胀。5.5 压缩后规则丢失survive_compaction只有AGENTS.md是 true。如果你把关键规则写在了SOUL.md里压缩后就会丢。正确做法是把必须保留的规则放进AGENTS.md的 Session Startup 或 Red Lines 章节这两个章节会被readPostCompactionContext()专门提取。5.6 TOOLS.md 改了但工具没变源码里有一句明确的澄清TOOLS.md does not control tool availability。这个文件只是给模型看的工具笔记真正控制工具可用性的是 OpenClaw 的插件注册机制。别指望改TOOLS.md能开关工具。6. 继续往下走配置骨架搭好、验证通过之后下一步通常是两件事一是把模型调用稳定下来二是把 Agent 跑成长任务。模型调用这块如果你还在试不同模型的效果可以直接在模型对话里对比响应确认哪个模型适合你的 Workspace 场景再写进config.toml。接入细节和参数说明在接入文档里有完整列表遇到 401、超时、模型名不匹配这类问题先翻那里。如果你要让 OpenClaw 长期跑编码或 Agent 任务按量计费的 Key 容易在长对话里烧得快Coding Plan 的额度模式更适合持续调用。配置改完后记得重启进程静态 MD 文件不会热加载——这个坑我踩过不止一次。
)
