这篇文章记录一次关于 terminal.cwd、启动目录和 AGENTS.md 的小排查。结论很简单：terminal.cwd 是工具执行起点，不一定等于当前 CLI 会话的 Project Context 加载目录。

起因

今天遇到一个很容易混淆的问题。

我在 /Users/tianlejin 启动 Hermes，但当前 profile 的配置里写了：

1
2
3
terminal:
  backend: local
  cwd: /Users/tianlejin/workspace-hermes-teacher

于是自然会产生一个疑问：如果启动目录和 terminal.cwd 不一样，Hermes 到底会加载哪个目录下的 AGENTS.md？

当时实测的终端输出是：

1
pwd

返回：

1
/Users/tianlejin

Project Context 中注入的内容也来自：

1
/Users/tianlejin/AGENTS.md

而不是：

1
/Users/tianlejin/workspace-hermes-teacher/AGENTS.md

所以这次的关键点不在于 terminal.cwd 配置有没有写，而在于：本次 CLI 会话真正启动时的 current working directory 是哪里。

先说结论

terminal.cwd 主要控制工具的默认工作目录。它不是 profile 目录，也不能简单理解成“系统提示词里的 Project Context 一定从这里加载”。

这几个概念最好分开看：

  • Profile 是 Hermes 自己的数据目录，里面放 config.yaml、.env、skills、memory、sessions、logs 等内容。
  • Workspace 或 working directory 是工具执行命令、解析相对路径时的起点。
  • Project Context 是会话启动时注入系统提示词的项目规则，比如 AGENTS.md、.hermes.md、CLAUDE.md 或 .cursorrules。
  • Sandbox 是隔离环境。terminal.cwd 不提供沙箱隔离，它只是“从哪里开始”。

这次实测出来的现象是：profile 里设置了 terminal.cwd，但 CLI 交互会话实际的 pwd 仍然是 /Users/tianlejin，因此启动时加载的是 /Users/tianlejin/AGENTS.md。

terminal.cwd 影响什么

根据官方文档和这次实测，可以把 terminal.cwd 理解成“工具默认工作目录”。它通常影响：

  • terminal 工具运行命令时的起始目录。
  • read_file、write_file、patch、search_files 等文件工具解析相对路径时的起点。
  • execute_code 这类代码执行工具在项目模式下的运行目录。
  • Gateway、cron 这类非交互入口的默认工作目录，尤其是它们不是从某个项目目录手动启动时。

但它不是万能开关。

它不会把 profile 目录改成 workspace，也不会把 local backend 变成沙箱。只要是 local backend，Hermes 仍然拥有当前系统用户本来就有的文件权限。cwd 只影响相对路径和命令起点，不限制能访问哪里。

官方文档里有一句很重要的意思：profile、workspace、sandbox 是三件事。很多配置问题其实都来自把这三者混成了一个概念。

AGENTS.md 是怎么加载的

Hermes 的项目上下文文件有一套优先级。按官方文档，项目上下文只加载一种来源，顺序大致是：

1
.hermes.md / HERMES.md → AGENTS.md → CLAUDE.md → .cursorrules

SOUL.md 是另一回事。它属于 Agent 的身份设定，来自 Hermes home/profile，不参与项目上下文的优先级竞争。

这里最容易踩坑的是 AGENTS.md。

在 CLI 交互会话里，启动时加载的是 session start 的 current working directory 对应的项目上下文。也就是说，你从哪个目录启动，会直接影响系统提示词里一开始有什么 Project Context。

子目录里的 AGENTS.md 不是启动时一次性全加载。Hermes 在工具调用访问到对应目录时，才会懒发现这些子目录规则，并通过 tool result 提示类似 “Subdirectory context discovered” 的信息。

这意味着：

  • 启动时注入系统提示词的是启动目录的项目规则。
  • 后续访问子目录时，可能发现子目录的 AGENTS.md。
  • 发现了子目录规则，不等于它从一开始就是当前会话的顶层 Project Context。

这也是我这次判断“当前用的是 /Users/tianlejin/AGENTS.md”的原因。

这次排查的证据链

这次没有靠记忆猜，而是把三类证据对了一遍。

第一类是实际命令输出。

1
pwd

返回：

1
/Users/tianlejin

这说明当前工具会话的实际工作目录不是 /Users/tianlejin/workspace-hermes-teacher。

第二类是本机配置。

profile 配置文件中确实有：

1
2
3
terminal:
  backend: local
  cwd: /Users/tianlejin/workspace-hermes-teacher

这说明问题不是“忘了配置 terminal.cwd”，而是这个配置没有覆盖本次 CLI session 的启动目录和已注入 Project Context。

第三类是官方文档。

我参考了 profile、配置、上下文加载、cron workdir 等几处文档，确认了几个点：

  • 创建 profile 不会让 profile 目录自动成为 terminal 默认目录。
  • terminal.cwd 控制的是 terminal/file/code 这类工具的工作起点。
  • cwd: "." 表示 Hermes 启动目录，不是 profile 目录。
  • Project Context 在 session start 的 current working directory 处加载。
  • Cron job 如果显式设置 workdir，会从该目录注入 AGENTS.md、CLAUDE.md、.cursorrules，工具也会使用这个 workdir。

把这些放到一起看，结论就比较清楚了：本次会话从 /Users/tianlejin 启动，所以顶层 Project Context 来自 /Users/tianlejin/AGENTS.md。terminal.cwd 即使配置成 workspace，也不能倒推本次已经启动的 CLI 会话一定加载 workspace 的 AGENTS.md。

CLI、Gateway 和 Cron 的区别

这个问题还要按入口区分。

CLI 交互会话里，启动目录非常关键。你在哪个目录执行 hermes，会影响当前会话启动时看到的项目上下文。实际表现也和这次一样，pwd 是最直接的判断依据。

Gateway 场景里，Hermes 往往不是你手动在某个项目目录启动，而是由服务或后台进程拉起。这时 terminal.cwd 更像一个默认工作目录配置，用来决定工具从哪里开始。

Cron 场景更明确。cron job 支持单独设置 workdir。设置后，该 job 会在这个目录下运行，并从这个目录加载项目上下文文件。对定时任务来说，最稳的做法不是依赖 profile 里的默认 cwd，而是给 job 显式写 workdir。

可以粗略记成：

  • CLI 想让某个项目的 AGENTS.md 稳定生效，最好从那个项目目录启动 Hermes。
  • Gateway 想固定工具工作目录，可以检查 profile 的 terminal.cwd。
  • Cron 想固定项目上下文和工具目录，最好在 job 上显式设置 workdir。

常见误解

terminal.cwd 不是 HERMES_HOME。

HERMES_HOME 或 profile 目录放的是 Hermes 自己的数据。比如配置、凭据、记忆、技能、会话记录和日志。terminal.cwd 放的是工具执行时从哪里开始。

terminal.cwd 不是沙箱。

local backend 下，只要系统用户有权限，Agent 仍然可以访问 cwd 之外的路径。不要把 cwd 当作安全边界。

AGENTS.md 被 search_files 找到，不代表它已经注入系统提示词。

工具访问目录时发现子目录上下文，只说明 Hermes 看到了这个规则文件。顶层 Project Context 仍然要看会话启动时加载了什么。

profile 也不等于 workspace。

新建一个 profile，只是新建一套 Hermes 配置和状态。它不会自动把你带到某个项目目录，也不会自动加载那个项目的 AGENTS.md。

实用建议

如果你只是日常在一个项目里工作，最简单的方式是先 cd 到项目根目录，再启动 Hermes：

1
2
cd /Users/tianlejin/workspace-hermes-teacher
hermes

如果你想给某个 profile 设置默认工具目录，可以在配置里写：

1
2
3
terminal:
  backend: local
  cwd: /Users/tianlejin/workspace-hermes-teacher

但写完后仍然要实测：

1
pwd

以及观察当前会话注入的 Project Context 来自哪个文件。

如果是 cron 任务，不要猜它会在哪个目录启动，直接给 job 设置 workdir。这能同时固定工具目录和上下文文件加载目录。

如果是 Gateway 服务，改完 terminal.cwd 后要重启 Gateway。配置通常在进程启动时读取，不能指望已运行的服务自动切换。

参考资料