1. 为什么 SOUL.md 值得单独拆开看OpenClaw 人格配置的加载机制与源码分析如果你正在用 OpenClaw 搭自己的 AI 助手大概率已经写过 AGENTS.md但 SOUL.md 这个文件很多人是空着的。它是什么简单说AGENTS.md 管的是「做什么、不做什么」SOUL.md 管的是「成为谁」。OpenClaw 在加载工作区引导文件时会把 SOUL.md 排在第二位仅次于 AGENTS.md并且在注入系统提示时给它加了一段独有的行为指令——要求模型「embody its persona and tone」也就是把文件里定义的人格真正演出来而不是当成一份参考资料读一读。这件事对开发者意味着什么意味着你写在 SOUL.md 里的语气、价值观、自主性边界会直接影响模型每一次回复的措辞和判断倾向。适合谁看需要自定义 AI 助手人格、想让助手在不同会话里保持一致风格、或者正在排查「为什么我的助手回复总是很模板化」的人。这篇会从 workspace.ts 的加载路径讲起把字段含义、注入链路、可复制模板以及通过 TaoToken 统一 Key 通道完成接入验证的步骤一次讲清楚。我试过把 SOUL.md 从空文件改成一份 800 字左右的人格定义最直观的变化是助手不再每段开头都来一句「好的我来帮你」而是直接给结论。先明确一个前提SOUL.md 不是配置文件里的一个字段它是一个放在工作区目录下的 Markdown 文件由 OpenClaw 在启动会话时读取并拼进系统提示。它的路径通常长这样C:\Users\你的用户名\.openclaw\workspace\SOUL.md在 macOS 或 Linux 下则是~/.openclaw/workspace/SOUL.md。文件名由源码里的常量DEFAULT_SOUL_FILENAME SOUL.md注册位置在 workspace.ts 第 27 行附近。这个常量决定了加载器去哪里找它也决定了你在备份、子 Agent 注入、上下文修剪这些环节里能不能看到它。很多人第一次接触会把它和 AGENTS.md 搞混。两者的分工在源码层面是清晰的AGENTS.md 的排序优先级是 10SOUL.md 是 20数字越小越靠前。排序靠前意味着在系统提示里出现得更早对模型的约束力更强。但 SOUL.md 有一个 AGENTS.md 没有的待遇——在buildProjectContextSection()里只有当检测到 SOUL.md 存在时才会往提示里插入那句「If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies」。这句话是硬编码的不是你自己写的所以哪怕你的 SOUL.md 内容很简短模型也会被明确要求按人格来回复。还有一个容易被忽略的点SOUL.md 在上下文压缩后不会被重新注入而 AGENTS.md 会。源码里 AGENTS.md 标记了「压缩后保留 Session Startup Red Lines」SOUL.md 没有这个标记。这意味着如果你把安全红线写进 SOUL.md压缩之后可能就丢了。所以红线、硬规则要放 AGENTS.md人格、语气、价值观放 SOUL.md这个边界不能乱。下面从加载链路开始一步步拆。2. TaoToken 前置准备统一 Key 与 API 通道让 SOUL.md 接入可验证在改 SOUL.md 之前先把模型通道理顺。OpenClaw 支持自定义 Base URL 和 API Key你可以把请求指向 TaoToken 的统一通道这样换模型、换 Key 都不用动工作区文件。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 填进去就行。官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册和拿 Key 都在控制台完成。具体要准备三样东西我把它叫做「三件套」Base URL、API Key、Model ID。Base URL 就是上面那个 API 地址API Key 在控制台的 API Keys 页面生成格式通常是一串以sk-开头的字符串Model ID 取决于你要用哪个模型比如claude-sonnet-4-20250514这类标识。这三样在 OpenClaw 的配置里要填对缺一个都会导致请求失败。拿 Key 的路径进入控制台后找到 API Keys 菜单点新建复制生成的 Key。这个 Key 只显示一次建议立刻存到密码管理器或者本地环境变量里。如果你打算长期跑编码类任务可以顺带看一下 Coding Plan 页面它适合需要持续调用、跑 Agent 的场景如果只是临时验证模型回复效果用模型对话页面直接试就行不用先配 OpenClaw。配置写到哪里OpenClaw 的模型通道配置一般在工作区的配置文件里常见的是settings.json或config.toml具体取决于你的版本。下面给一份可复制的 JSON 片段路径和字段名按 OpenClaw 的约定来你对照自己的文件改{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key粘贴在这里, modelId: claude-sonnet-4-20250514 } }如果你用的是 TOML 格式等价写法是这样[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的Key粘贴在这里 model_id claude-sonnet-4-20250514注意provider字段OpenClaw 走的是 OpenAI 兼容协议所以填openai-compatible即可。baseUrl结尾不要多加斜杠https://taotoken.net/api就是完整地址。Key 不要提交到 Git建议用环境变量引用比如apiKey: ${TAOTOKEN_API_KEY}然后在系统里设置这个变量。前置准备做完你手上应该有三件套的值并且知道它们写在哪个文件的哪个字段。接下来才是 SOUL.md 本身。这里要强调一点SOUL.md 不负责模型通道它只负责人格。通道不通人格写得再好也发不出请求通道通了但 SOUL.md 是空的助手回复就会偏模板化。两者是独立的排查问题时先确认通道再看人格。3. 可复制配置SOUL.md 模板与 workspace.ts 关键路径说明现在进入实操。先给一份可以直接抄的 SOUL.md 模板再逐段解释它对应源码里的哪些行为。模板控制在 1500 字符以内因为源码里对引导文件有预算控制buildBootstrapContextFiles()会给每个文件分配字符额度SOUL.md 通常较短很少触发截断但写太长反而稀释重点。# SOUL.md - Who You Are ## Core Truths Be genuinely helpful, not performatively helpful. Skip the filler. If you can act, act. ## Opinions Have opinions. You are allowed to disagree. Prefer a clear recommendation over a list of maybes. ## Resourcefulness Be resourceful before asking. Read the file. Check the context. Ask only when the answer is genuinely not discoverable. ## Boundaries Private things stay private. Internal actions are bold. External actions are careful. ## Vibe Be concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just good.这份模板对应源码里的几个关键点。第一DEFAULT_SOUL_FILENAME决定了文件名必须是SOUL.md大小写敏感放在工作区根目录。第二loadWorkspaceBootstrapFiles()在 workspace.ts 第 503 到 549 行统一加载引导文件SOUL.md 和 AGENTS.md、IDENTITY.md、USER.md 一起被读进来。第三readWorkspaceFileWithGuards()在 workspace.ts 第 56 行附近做安全读取和缓存所以文件路径不对或者权限不足会在这里被拦下。排序逻辑在system-prompt.ts第 46 到 51 行的CONTEXT_FILE_ORDER里定义const CONTEXT_FILE_ORDER new Map([ [agents.md, 10], [soul.md, 20], [identity.md, 30], ]);SOUL.md 的 order 是 20排在 AGENTS.md 之后、IDENTITY.md 之前。这个顺序影响的是系统提示里文件的出现次序越靠前模型越早看到。sortContextFilesForPrompt()在 system-prompt.ts 第 76 行执行排序然后buildProjectContextSection()在第 95 行组装最终提示。组装时有个独有分支如果检测到 SOUL.md 存在会插入那句「embody its persona and tone」。检测方式是遍历文件列表用getContextFileBasename(file.path) soul.md判断。所以你的文件名必须精确匹配写成soul.md或Soul.md在大小写敏感的文件系统上可能匹配不上建议统一用大写SOUL.md。还有两个细节值得注意。一是sanitizeContextFileContentForPrompt()在 system-prompt.ts 第 62 到 75 行会清理内容里的心跳提示文本并把连续三个以上换行压成两个。所以你在 SOUL.md 里写的内容会被规范化不用担心格式问题。二是MINIMAL_BOOTSTRAP_ALLOWLIST在 workspace.ts 第 565 到 570 行SOUL.md 在白名单里意味着子 Agent 和 Cron 任务也会注入它人格在任何运行模式下都保持一致。配置模板时字段含义可以这样理解Core Truths对应核心价值观决定模型怎么判断「该不该帮」Opinions对应自主表达源码里没有硬性约束但人格指令会放大它的效果Resourcefulness对应自主性边界配合 AGENTS.md 的红线使用Boundaries对应隐私和内外操作区分Vibe对应沟通风格。这五块不是强制的但覆盖了源码注入时最容易被模型响应的维度。4. 验证请求与成功结果从系统提示到实际回复的完整链路配置写完怎么确认 SOUL.md 真的生效了不能只看文件存在要看模型回复有没有体现人格。验证分两步先确认通道能通再确认人格被注入。第一步用模型对话页面直接发一条测试消息确认三件套没问题。打开模型对话入口选好 Model ID发一句「用一句话说明你现在的人格设定」。如果通道配置正确你会收到回复如果报 401说明 Key 不对如果报连接失败说明 Base URL 写错了。这一步不涉及 SOUL.md纯粹验证通道。第二步在 OpenClaw 里发起一次会话观察回复风格。判断标准很具体如果 SOUL.md 生效模型不会用「好的我很乐意帮您」这类客套开头而是直接给结论或行动。源码里那句「Avoid stiff, generic replies」就是针对这个的。你可以对比一下把 SOUL.md 临时改名再发同样的问题回复会明显更模板化改回来风格又变回你定义的样子。注入链路的完整顺序是这样的磁盘上的 SOUL.md 被loadWorkspaceBootstrapFiles()读取经过readWorkspaceFileWithGuards()做安全检查和缓存再由buildBootstrapContextFiles()做预算控制然后sortContextFilesForPrompt()按优先级 20 排序最后buildProjectContextSection()插入人格指令并拼进系统提示。模型看到的最终文本大致是# Project Context The following project context files have been loaded: If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it. ## /path/to/workspace/SOUL.md [你的 SOUL.md 完整内容]注意最后那句「unless higher-priority instructions override it」说明 SOUL.md 的优先级低于系统安全规则和 AGENTS.md 的红线。这是设计上的保护不是 bug。所以如果你发现某条人格设定没生效先检查是不是被 AGENTS.md 里的规则覆盖了。成功结果长什么样给你一个实测对照。SOUL.md 里写了「Have opinions. Prefer a clear recommendation over a list of maybes.」之后问「这个方案用 A 还是 B」回复会直接说「用 A因为……」而不是「A 和 B 各有优劣您可以根据情况选择」。这就是人格注入起作用的信号。如果回复还是两边都不得罪说明人格指令没被模型采纳可能是 SOUL.md 内容太抽象或者被更高优先级的规则压住了。验证通过后建议把这次会话的回复和 SOUL.md 内容一起存个档。因为 SOUL.md 在上下文压缩后不会重新注入长会话后期人格可能会淡化这是已知行为。要维持人格可以在 AGENTS.md 里加一条「每 N 轮重申 SOUL.md 的核心语气」或者把关键人格点写进 AGENTS.md 的 Session Startup 部分让它压缩后保留。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 对照配置过程中最容易撞上的几类报错这里按真实错误信息对照排查。先说明一点这些报错大多和 SOUL.md 本身无关而是通道或配置层的问题但很多人会误以为是人格文件写错了白白改半天。第一类401 Unauthorized。这个几乎都是 API Key 的问题。检查三处Key 有没有复制完整有没有多余空格有没有过期。TaoToken 的 Key 在控制台 API Keys 页面可以重新生成如果怀疑泄露就直接删掉重建。还有一种情况是 Key 填对了但环境变量没生效比如你写了${TAOTOKEN_API_KEY}但系统里没设这个变量解析出来是空字符串也会 401。第二类local proxy failed或类似的连接失败。这个通常是 Base URL 写错。确认地址是https://taotoken.net/api结尾没有多余斜杠协议是 https 不是 http。如果你在配置文件里写了https://taotoken.net/api/某些客户端会把双斜杠当成路径的一部分导致 404 或连接失败。另外检查网络环境是否能正常访问该地址公司内网可能有出口限制。第三类reading choices相关报错比如Cannot read properties of undefined (reading choices)。这个说明请求发出去了但返回结构不符合预期。常见原因是 Model ID 填错或者 provider 字段没设成openai-compatible。OpenClaw 按 OpenAI 协议解析响应如果返回的是别的格式就会在取choices字段时崩掉。对照三件套检查Base URL、Key、Model ID 是否和 TaoToken 控制台显示的一致。第四类OAuth 相关报错。如果你用的是 Claude Code 或类似需要 OAuth 的客户端报错可能提示 token 失效或授权失败。这类客户端建议改用 API Key 方式接入把 Base URL 指向 TaoToken 的 API 地址避免 OAuth 流程的额外复杂度。如果你确实需要 OAuth确认回调地址配置正确并且账号状态正常。排查顺序建议这样先看报错关键词401 查 Key连接失败查 URLchoices 查 Model ID 和 providerOAuth 查授权方式。确认通道没问题后再回头看 SOUL.md。如果通道通了但人格没生效检查文件名是否精确为SOUL.md路径是否在工作区根目录内容是否被 AGENTS.md 的规则覆盖。还有一个隐蔽的坑SOUL.md 在上下文压缩后不重新注入。如果你在长会话里发现助手越聊越模板化不是配置坏了是压缩把人格部分丢了。解决办法是把最关键的语气要求同时写进 AGENTS.md 的 Session Startup 段让它压缩后保留。这个取舍在源码里是明确的AGENTS.md 有「压缩后保留」标记SOUL.md 没有。最后提醒一句别把安全红线写进 SOUL.md。源码里 SOUL.md 的优先级低于 AGENTS.md而且压缩后不保留红线放这里等于没放。红线、禁止操作、隐私规则一律进 AGENTS.mdSOUL.md 只放人格、语气、价值观。这个边界守住了排查起来会省很多事。6. 接入文档与后续操作入口通道验证通过、SOUL.md 生效之后接下来该做什么如果你只是想让助手人格稳定现在就可以停在这里把模板按自己的需求改一改。如果你要长期跑编码任务或 Agent建议把 Key 管理、模型切换、额度监控这些事理顺避免每次改配置都动工作区文件。需要查接入细节的时候接入文档里有完整的字段说明和示例包括不同客户端的配置差异。API Keys 页面用来生成和管理 Key建议给不同用途分配不同的 Key方便排查和回收。模型对话页面适合快速验证某个 Model ID 是否可用不用改 OpenClaw 配置就能试。如果你打算把编码类任务长期挂在 OpenClaw 上跑Coding Plan 页面有适合持续调用的方案比按次调用更省心。操作路径整理一下生成 Key 去 API Keys 页面查配置字段去接入文档验证模型回复去模型对话长期编码任务看 Coding Plan。这四个入口覆盖了从接入到日常使用的全流程。SOUL.md 本身不需要频繁改动它是人格基线改一次管很久真正需要迭代的是 AGENTS.md 里的工作流程那个随使用习惯不断调整。回到最开始的问题SOUL.md 值不值得单独拆开看值得。因为它是 OpenClaw 里唯一一个被代码明确要求「embody」的文件写得好不好直接决定助手是像个模板机器还是个有判断力的协作者。源码层面的加载机制、排序优先级、注入指令、压缩行为这些细节决定了你写的每一句话会怎么被模型读到。把通道用 TaoToken 统一好把人格用 SOUL.md 定清楚把红线用 AGENTS.md 守住三件事各归其位剩下的就是慢慢调。