soul.md配置错误会导致agent行为异常；需检查语法格式、关键字段、特殊符号、文件权限及是否被覆盖为默认注释模板。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您修改了 Hermes Agent 的 SOUL.md 文件，但 Agent 行为出现异常、响应空洞、拒绝执行指令或反复输出模板化语句，则很可能是 SOUL.md 配置错误导致系统提示词注入失效。以下是排查与修复该问题的步骤：
一、SOUL.md 语法格式错误导致解析失败
SOUL.md 是纯 Markdown 文本文件，Hermes 在每次调用 LLM 前会将其内容整体拼入系统提示词。若文件中存在未闭合的代码块、非法 YAML 前置符、或混入非 UTF-8 字符（如 Windows 编码的 BOM），会导致读取中断，Agent 将退化为无约束的通用模型行为。
1、使用命令检查文件编码与基础结构：
file -i ~/.hermes/SOUL.md
2、确认文件不含 YAML front matter（即删除所有以 --- 开头和结尾的段落）
3、用 vim 或 nano 打开文件，执行 :set nobomb 并保存，确保无 BOM 头
4、逐行检查是否误用缩进式列表代替段落换行，SOUL.md 中禁止使用无序/有序列表语法，所有内容必须为连续段落或加粗强调
二、关键约束字段缺失或冲突
SOUL.md 的核心作用是定义 Agent 的人格边界与行为契约。若缺失“原则声明”“能力范围”或“禁令条款”，Hermes 将失去操作依据，可能在执行工具调用时主动拒绝、或在应拒绝时擅自越权。
1、打开 ~/.hermes/SOUL.md，确认至少包含三个逻辑区块：
• 开篇人格定位（例如：“你是一个专注科研文献管理的助手，不提供医疗建议”）
• 显式能力清单（例如：“你能读取 PDF、提取 DOI、生成 BibTeX 条目”）
• 明确禁令（例如：“禁止生成代码、禁止访问未授权网站、禁止猜测用户未提供的信息”）
2、检查是否存在自相矛盾的语句，例如同时声明“你从不虚构事实”和“你可以基于常识补全缺失年份”
3、删除所有含“请”“应该”“尽量”等模糊动词的句子，SOUL.md 必须使用断言式陈述句，如“你只返回 BibTeX 格式”而非“你尽量返回 BibTeX 格式”
三、特殊符号或 HTML 实体干扰注入流程
Hermes 将 SOUL.md 内容原样拼入系统提示词字符串。若文件中包含未转义的花括号 {}、美元符 $ 或反引号嵌套，可能被底层模板引擎误识别为变量占位符，造成提示词截断或注入失败。
1、运行 grep -n "[{}$`]" ~/.hermes/SOUL.md 定位高危字符行号
2、将所有独立出现的 { 替换为 \{，所有 } 替换为 \}
3、将所有单个反引号 ` 替换为双反引号 ``，或直接删除（SOUL.md 不支持内联代码）
4、特别注意：不得在 SOUL.md 中插入任何 符号，它们会破坏 LLM 提示词结构
四、文件权限或路径错误导致读取为空
Hermes 启动时会尝试读取 ~/.hermes/SOUL.md。若该路径被重命名、软链接断裂、或权限设置为不可读（如 chmod 000），Agent 将静默使用空字符串作为人格输入，等效于无灵魂状态。
1、执行 ls -l ~/.hermes/SOUL.md 验证文件存在且为普通文件
2、执行 cat ~/.hermes/SOUL.md | head -n 5 确认可读且前五行有可见内容
3、检查父目录权限：ls -ld ~/.hermes 应显示 drwxr-xr-x 或更宽松权限
4、若输出“Permission denied”，立即执行 chmod 644 ~/.hermes/SOUL.md
五、SOUL.md 被意外覆盖为默认空注释模板
部分用户在首次运行 hermes setup 后未手动编辑 SOUL.md，或误执行了重置命令，导致文件保留官方初始模板——仅含大量注释行（以
