结论先行
终端有变量,不代表 IDEA 启动的 Java 进程也有。此次排查中,终端能够读取 SPARROW_AGENT_SKILL_WORKSPACE,配置的目录也存在,但应用启动日志明确报缺少该配置。最直接的处理是在当前应用的运行配置中显式设置变量,再重新启动验证。
IDEA 支持为运行配置设置环境变量,参见 JetBrains 官方说明。这次只需处理本机启动配置,业务代码无需增加读取 Shell 文件的逻辑。
问题背景
应用启动时注册 Skills 工具,需要一个实际存在的 skills 目录。配置文件使用环境变量占位符:
agent.skills.dirs=${SPARROW_AGENT_SKILL_WORKSPACE:}冒号后没有内容,表示变量缺失时先得到空字符串。本项目启动配置会拒绝空目录,因此问题最终表现为 ChatClient 创建失败,而不是一个直接写着“环境变量读取失败”的错误。
详细内容
沿异常链找到真正缺少的配置
启动失败时,先读最底层原因,不要停在最外层的依赖注入异常。本次异常经过消息订阅器、ChatClient 配置,最终指向:
java.lang.IllegalStateException:
Configure agent.skills.dirs or SPARROW_AGENT_SKILL_WORKSPACE对应配置类先读取 agent.skills.dirs,为空时再读取 SPARROW_AGENT_SKILL_WORKSPACE,两者都为空才抛错。这说明当前应用在创建工具时没有获得有效目录配置,接下来应核对配置来源。
分清已经证实的事实与尚未查明的原因
| 检查位置 | 结果 | 说明 |
|---|---|---|
| 终端进程 | 变量有值 | 证明当前终端环境已设置 |
| 变量指定目录 | 实际存在 | 排除该路径不存在 |
| ~/.zshenv | 有变量定义 | 说明终端的配置来源 |
| IDEA 运行配置 | 未显式设置该变量 | 应用依赖继承到的环境 |
| 应用启动日志 | 目录配置为空 | 说明启动的 Java 进程未获得有效值 |
进程在启动时接收环境变量;修改终端环境不会自动更新已经运行的其他进程。IDEA 在 macOS 上会尝试加载 Shell 环境,因此不能笼统地说“IDEA 不读取 .zshenv”。已有进程保留旧环境、Shell 环境加载失败、运行配置设置不同等情况,都可能造成差异。具体加载行为见 JetBrains Shell Environment Loading。
已定位到应用没有取得所需变量,但尚未检查 IDEA 自身的环境加载日志,不能断言一定由某个启动方式或某次超时造成。
在当前 IDEA 运行配置中补上变量
- 打开 Run → Edit Configurations。
- 选中实际启动的 SparrowApplication,核对入口类和使用的模块。
- 找到 Environment variables。若界面未显示,在 Modify options 中启用相应选项;不同版本的名称和位置可能略有差异。
- 添加变量名
SPARROW_AGENT_SKILL_WORKSPACE,值填写本机 skills 目录的绝对路径。 - 保存配置,结束旧进程,再用同一个运行配置启动。
SPARROW_AGENT_SKILL_WORKSPACE=/absolute/path/to/AICoding/.agents/skills上面是示例路径,必须换成自己的实际目录。此项目的变量本身就指向 skills 目录,不应再追加一层 skills。不要把它放进 Program arguments 或 VM options;这几个字段的作用不同。官方配置入口见 运行参数与环境变量。
用断点确认 Java 进程实际收到了什么
重新启动后,检查原来的缺配置异常是否消失。若仍然失败,在 AgentToolsConfiguration.configure 读取目录的位置设置断点,查看:
System.getenv("SPARROW_AGENT_SKILL_WORKSPACE")
environment.getProperty("SPARROW_AGENT_SKILL_WORKSPACE")
environment.getProperty("agent.skills.dirs")使用推荐的环境变量方案时,前两项应取得目录路径,第三项也应通过占位符得到有效值。如果直接覆盖了 agent.skills.dirs,则 System.getenv 为空也可能正常,判断应以实际使用的配置来源为准。
目录存在只证明路径有效;还要核对应用运行身份能读取目录,且其中包含可加载的 skills。只有重新启动并通过相应初始化,才能说这处启动问题得到验证。后续若出现数据库或模型认证错误,应根据新的异常继续排查。
目录路径可以在本机核对;API Key、Token 和密码只检查是否有值,不输出完整内容,也不要把它们写进共享运行配置。
配置方式怎么选,以及哪些操作容易无效
日常在 IDEA 中开发,优先使用应用自己的运行配置。若希望直接指定 Spring 配置,本项目也允许在 VM options 中设置:
-Dagent.skills.dirs=/absolute/path/to/skills这是 Java 系统属性,不会创建同名环境变量,只适用于通过 Spring 配置读取此属性的代码。推荐方案和替代方案选择一种即可,避免多处设置后不知道实际用的是哪一份。
在 IDEA 内置 Terminal 中 export,只会影响该 Shell 及其之后启动的子进程,不能据此认定工具栏 Run 启动的应用也获得相同值。只新建 .env 文件也不能保证生效;必须由当前 IDEA 版本的运行配置或应用中已存在的加载机制明确读取它。
如果要继续追查 IDEA 为什么没有继承 Shell 环境,可通过 Help → Show Log in Finder 查找 idea.log 中与环境加载有关的错误,再参考 JetBrains 的 Shell 环境加载说明处理。无需为了修复一个本机目录配置而改动全局系统环境。
总结归纳
这类问题的关键,是检查真正启动应用的进程获得了什么配置。先从最底层异常确定变量名,再对比终端、运行配置与应用取值,最后在明确的启动入口传入并重新验证。
本文记录的是已完成的排查和可执行修复步骤;撰写时尚未保存本次 IDEA 配置,也未完成重启验证,不能将方案说明当作修复成功记录。
参考资料
- JetBrains:Program arguments, VM options, environment variables
说明运行参数、Java 系统属性与环境变量的不同配置入口。
- JetBrains:Shell Environment Loading
说明 macOS 上 IDE 加载 Shell 环境的机制,以及加载失败时的日志排查方向。官方资料核对于 2026-10-28。