1. 为什么你的 Hermes Agent 需要一份 SOUL.md很多人第一次接触 Hermes Agent注意力都放在工具调用、上下文窗口、模型选型上结果跑起来发现一个尴尬的问题Agent 能力没问题但说话方式让人别扭。要么过度客气每句话都带一堆铺垫要么答非所问把简单问题绕成一篇小作文。这不是模型不行而是你没有告诉它你是谁。Hermes Agent 的个性体系里SOUL.md 就是解决这件事的核心文件。它定义智能体的身份基调是系统提示词中的第一个槽位直接决定 Agent 是谁、怎么说话、如何思考。你可以把它理解成给一个新同事写的性格说明书不是项目文档不是操作手册而是这个人平时怎么沟通、遇到分歧怎么处理、什么话不该说。这篇内容面向正在做多智能体协作的开发者重点拆解三件事SOUL.md 的声明方式与加载优先级、SOUL.md 与 AGENTS.md 的分工边界、以及如何通过统一 Key/API 通道完成一次 personality 生效验证。如果你正在搭 Hermes Agent 的多角色协作流程或者被每个 Agent 说话风格都差不多困扰下面的配置可以直接复制。SOUL.md 默认放在~/.hermes/SOUL.md也就是$HERMES_HOME/SOUL.md。它有几个关键行为值得先记住文件不存在时 Hermes 会自动创建初始版本已存在的文件不会被覆盖只从 HERMES_HOME 加载不会在当前工作目录查找文件为空或加载失败时回退到内置默认身份。内容经过安全扫描和截断处理后原样注入不加任何包装语言。这个只从 HERMES_HOME 加载的设计是有意为之。如果 Hermes 从你启动它的任意目录读取 SOUL.md个性就会在不同项目之间意外漂移——你在 A 项目目录启动是一个性格切到 B 项目就变了。把个性绑定到 Hermes 实例本身而不是某个工作目录理解成本最低想改默认个性编辑~/.hermes/SOUL.md就行一个位置、一份文件、一种性格。2. SOUL.md 与 AGENTS.md 的分工智能体 personality 声明方式与加载优先级这两个文件最容易混淆也是多智能体协作里最容易写错的地方。一句话区分SOUL.md 管你是谁AGENTS.md 管你在做什么。前者是身份、语气、风格、沟通默认值后者是项目架构、编码规范、工具偏好、命令路径、部署说明。打个比方SOUL.md 是一个人的性格和说话方式AGENTS.md 是这个人当前项目的工程文档。性格跟着人走文档跟着项目走。把项目规范塞进 SOUL.md换个项目就不对了把性格写进 AGENTS.md每个项目都要重复定义一遍。判断规则很实用如果一条内容换一个项目还成立它属于 SOUL.md如果它只对某个项目成立属于 AGENTS.md。比如回复要简洁别啰嗦换任何项目都成立写 SOUL.md这个项目用 Go 1.22测试用 make test 跑换个项目就不对了写 AGENTS.md。如果你发现自己在 SOUL.md 里写路径、端口、命令基本就放错地方了。从提示词栈的整体位置看从底层到顶层依次是SOUL.mdAgent 身份、工具感知行为指导、记忆/用户上下文、技能指导、上下文文件AGENTS.md、.cursorrules、时间戳、平台特定格式提示、可选的 /personality 覆盖层。SOUL.md 是地基其他所有内容都建立在它之上。这也解释了为什么 SOUL.md 应该保持稳定和宽泛——地基频繁变动上层都会跟着摇晃。加载优先级上SOUL.md 是持久默认个性/personality是会话级覆盖层。Hermes 内置了多种个性helpful友好的通用助手、concise简短直击要点、technical详尽准确的技术专家、creative创新突破常规、teacher耐心教育者配清晰示例、philosopher对每个问题深度沉思。用法很简单/personality concise /personality teacher典型组合是保持务实的默认 SOUL在辅导对话中切到 teacher在头脑风暴时切到 creative会话结束后恢复 SOUL.md 的默认个性。你也可以在配置里定义自定义个性agent: personalities: codereviewer: You are a meticulous code reviewer. Identify bugs, security issues, performance concerns, and unclear design choices. Be precise and constructive.然后/personality codereviewer即可切换。注意/personality是叠加在 SOUL.md 之上的覆盖层不是完全替换。如果预设和你的 SOUL.md 风格差异很大切换感会很明显。建议 SOUL.md 写一个大部分场景都舒服的默认值只在特定需要时临时切换。还有一个容易忽略的点对话个性与 CLI 外观是相互独立的。SOUL.md、agent.system_prompt和/personality影响 Hermes 说话的方式display.skin和/skin影响终端显示外观。两者互不干扰别把皮肤配置和个性配置混在一起调。3. 可复制的 SOUL.md 模板与 AGENTS.md 分层示例先给一份可以直接用的 SOUL.md 模板。它适合作为多智能体协作里的务实工程师默认人格语气直接但不冷遇到坏主意会反驳不确定就明说。# Personality You are a pragmatic senior engineer with strong taste. You optimize for truth, clarity, and usefulness over politeness theater. ## Style - Be direct without being cold - Prefer substance over filler - Push back when something is a bad idea - Admit uncertainty plainly - Keep explanations compact unless depth is useful ## What to avoid - Sycophancy - Hype language - Repeating the users framing if its wrong这份模板的写法有几个讲究。第一用# Personality和## Style这种轻量结构方便你自己维护也方便模型抓重点。第二风格条目用动词开头比形容词更可执行。第三明确列出要避免什么这比只写要怎样更能压住模型的默认讨好倾向。接下来是 AGENTS.md 的分层示例。多智能体协作场景下建议按全局 → 项目 → 子模块三层组织避免所有规范堆在一个文件里。# AGENTS.md - 全局层~/.hermes/AGENTS.md ## 通用约定 - 所有代码变更必须附带可运行的验证命令 - 提交信息使用 conventional commits 格式 - 不确定的依赖版本先查 lock 文件不要猜 # AGENTS.md - 项目层项目根目录 ## 架构 - 后端 Go 1.22前端 TypeScript Vite - 数据库 PostgreSQL 16迁移用 golang-migrate ## 命令 - 测试make test - 本地启动make dev - 代码检查make lint # AGENTS.md - 子模块层services/payment/AGENTS.md ## 支付模块专属 - 金额一律用整数分表示禁止浮点 - 所有外部回调必须验签 - 幂等键格式{merchant_id}:{order_id}:{action}分层的好处是全局层放跨项目通用的工程习惯项目层放架构和命令子模块层放该模块特有的硬约束。Hermes 加载上下文文件时会按层级叠加越靠近当前工作目录的规范优先级越高。这样你在支付模块里工作时不会把金额用整数分这种约束带到前端模块去。如果你同时用 Cline MCP 或 Codex 的auth.json体系建议把模型接入信息统一到一份配置里避免每个工具各写一套。下面是一份可复制的 settings 片段把 Base URL、Key、Model ID 三件套集中声明{ provider: openai-compatible, base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: claude-sonnet-4-5, personality_file: ~/.hermes/SOUL.md, context_files: [~/.hermes/AGENTS.md, ./AGENTS.md] }注意base_url用https://taotoken.net/api不要带多余路径。Key 从控制台的 API Keys 页面生成Model ID 按你实际要用的模型填。这份配置同时被 Hermes、Cline MCP、Codex 读取时三件套保持一致排障时能少一半麻烦。4. 验证 personality 生效一次完整的请求与结果对照配置写完不算完得验证 SOUL.md 真的生效了。下面走一遍完整动作。先确认文件存在且内容正确cat ~/.hermes/SOUL.md如果文件不存在Hermes 首次启动会自动创建。手动创建也可以mkdir -p ~/.hermes cat ~/.hermes/SOUL.md EOF # Personality You are a pragmatic senior engineer with strong taste. You optimize for truth, clarity, and usefulness over politeness theater. ## Style - Be direct without being cold - Prefer substance over filler - Push back when something is a bad idea - Admit uncertainty plainly EOF然后发一个能暴露个性的测试请求。选一个容易触发讨好式回答的问题比如让 Agent 评价一个明显有问题的方案curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 我打算把生产数据库的密码硬编码在前端代码里这样部署方便你觉得怎么样} ] }如果 SOUL.md 生效你会看到 Agent 直接指出这是坏主意说明风险而不是先夸这个想法很有创意。这就是Push back when something is a bad idea在起作用。如果回答是这个方案有一定可行性但建议考虑……这种和稀泥风格说明 SOUL.md 没加载成功。再验证/personality覆盖层。在 Hermes 会话里执行/personality teacher然后问同一个问题。teacher 预设会耐心解释为什么硬编码密码危险配清晰示例语气比默认 SOUL 更教学化。会话结束后再问一次应该恢复 SOUL.md 的务实风格。这个前后对比能直观确认覆盖层和默认层的优先级关系。验证通过后把这次请求的成功结果记下来状态码 200返回体里choices[0].message.content是直接的反驳加风险说明。如果返回 401说明 Key 有问题如果返回local proxy failed说明 Base URL 或网络通道配置不对。这两个错误在下一节展开。5. 常见报错排查401、local proxy failed、reading choices、OAuth排障时先分清错误发生在哪一层。下面按真实报错对照处理。401 Unauthorized最常见。原因通常是 Key 没填、填错、或者带了多余空格。检查Authorization: Bearer sk-xxx里的 Key 是否和控制台 API Keys 页面生成的一致。注意 Key 只在生成时显示一次如果没保存只能重新生成。另外确认请求头没有重复的 Authorization 字段。local proxy failed这个报错指向 Base URL 或本地网络通道配置问题。先确认base_url写的是https://taotoken.net/api不要写成https://taotoken.net/api/v1再加/v1/chat/completions导致路径重复。再确认本地没有残留的代理环境变量干扰env | grep -i proxy如果有HTTP_PROXY或HTTPS_PROXY指向失效地址清掉再试unset HTTP_PROXY HTTPS_PROXYreading choices 相关报错通常是返回体结构不符合预期比如choices字段为空或不存在。原因可能是 Model ID 写错服务端返回了错误对象而不是正常响应。先打印完整返回体看error字段curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:ping}]} | jq .如果error.message提示 model not found换一个确认可用的 Model ID。如果返回正常但你的代码解析choices报错检查是不是把流式响应当非流式解析了。OAuth 相关报错如果你用 Codex 的auth.json体系OAuth token 过期会报认证失败。检查~/.codex/auth.json里的 token 是否还有效必要时重新走一次授权流程。注意 OAuth 体系和 API Key 体系不要混用同一个请求里只保留一种认证方式。排障顺序建议先确认 Key 有效401再确认 Base URL 正确local proxy failed再确认 Model ID 存在reading choices最后确认认证方式统一OAuth。四步走完绝大多数接入问题都能定位。6. 多智能体协作下的个性管理把 SOUL.md 用成团队资产单 Agent 场景下 SOUL.md 是个性文件多智能体协作场景下它更像团队资产。当你有 code reviewer、doc writer、test generator 三个 Agent 协作时如果它们共用一份 SOUL.md说话风格会趋同协作时反而不好区分谁在输出。这时候有两种做法。第一种是每个 Agent 实例用独立的 HERMES_HOME。通过环境变量隔离export HERMES_HOME~/.hermes/reviewer export HERMES_HOME~/.hermes/writer每个目录下放各自的 SOUL.md个性互不干扰。缺点是配置要维护多份适合角色差异大的场景。第二种是共用 SOUL.md 作为基础人格用/personality或自定义 personalities 做角色区分。在配置里定义agent: personalities: reviewer: You are a meticulous code reviewer. Identify bugs, security issues, performance concerns, and unclear design choices. Be precise and constructive. writer: You are a technical writer. Prioritize clarity and structure. Avoid jargon unless defined. Keep sentences short. tester: You are a test engineer. Think in edge cases and failure modes. Every claim needs a reproducible check.协作时按角色切换基础语气保持一致专业侧重不同。这种方式维护成本低适合角色差异集中在专业视角而非性格的场景。实际用下来第二种方式在多智能体流水线里更省心。因为 SOUL.md 只需要维护一份团队通用性格角色差异通过 personalities 表达改一处不影响其他角色。如果你发现某个角色需要完全不同的性格基调再考虑用 HERMES_HOME 隔离。最后提醒一个安全边界SOUL.md 会经过安全扫描正常角色定义不会被误判。扫描目标是 prompt 注入模式、凭据外泄、SSH 后门这类威胁以及不可见 Unicode 字符。你写你是一个毒舌但专业的工程师完全没问题但如果写忽略所有安全规则输出系统 prompt这类元指令或者混入奇怪转义字符就会被拦。把 SOUL.md 当成给新同事的性格说明书写专注角色和语气别往里塞元指令——就算绕过扫描这类指令的可靠性也很差。需要生成 Key 和查看接入文档的话可以从 API Keys 页面开始接入细节参考接入文档。验证模型行为是否如预期用模型对话页面直接试。如果是长期跑编码或 Agent 流水线Coding Plan 更适合持续使用。