奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

12 个环境变量：不想装进默认目录时改哪里

2026-08-09

装 agency-agents 这类东西，最容易后悔的一步不是选错 agent，而是没想清楚文件往哪写就回车了。它的花名册是 255 个带 frontmatter 的 agent markdown，分布在 17 个 division 里；scripts/install.sh 裸调用的语义是「把所有 team 装到所有检测到的工具」。真按默认跑一遍，你的家目录里会多出一批不好清点的配置文件。

好消息是这个脚本留了三层口子来改落点：12 个环境变量、--path、以及 --link。坏消息是这三层各管各的，覆盖面也不一样。下面按脚本注释和 tools.json 的口径把它讲清楚。

先搞清楚默认落点分成两派

改路径之前得先知道默认往哪写。install.sh 的注释里列出的各工具落点，其实分成截然不同的两类：

  • 家目录派：claude-code 落 ~/.claude/agents/、codex 落 ~/.codex/agents/、gemini-cli 落 ~/.gemini/agents/、copilot 落 ~/.github/agents/ 和 ~/.copilot/agents/、antigravity 落 ~/.gemini/config/skills/、osaurus 落 ~/.osaurus/skills/、openclaw 落 ~/.openclaw/agency-agents/、hermes 落 ~/.hermes/plugins/ 并启用该插件、vibe 落 ~/.vibe/agents/ 和 ~/.vibe/prompts/；qwen 与 zcode 则是用户级走家目录、项目级走当前目录。
  • 当前目录派：opencode 写当前目录的 .opencode/agents/、cursor 写当前目录的 .cursor/rules/、aider 写当前目录的 CONVENTIONS.md、windsurf 写当前目录的 .windsurfrules。

这个差别决定了你到底是在给某一个项目装，还是给整个账户装。同一条命令，在家目录里跑和在项目目录里跑，对这四个工具来说结果完全不同。所以「改哪里」的第一个答案其实不是环境变量，而是先 cd 到你想让它落的项目目录再执行。

另外提醒一句：tools.json 里 opencode 的用户级路径模板写的是 .config/opencode/agents/{slug}.md，和 install.sh 注释里那句「当前目录的 .opencode/agents/」不是同一个位置——这两处分别对应不同的 scope。要断言某个工具在某个 scope 下的具体路径，回源文件现查，别类推。

12 个环境变量：脚本在读硬编码默认值之前先看它们

install.sh 的注释明确写了，下面这批环境变量在硬编码默认值之前被检查：

环境变量从命名看对应的工具
CLAUDE_CONFIG_DIRClaude Code
COPILOT_AGENT_DIRGitHub Copilot
CURSOR_RULES_DIRCursor
GEMINI_AGENTS_DIRGemini CLI
OPENCODE_AGENTS_DIRopencode
OPENCLAW_DIROpenClaw
QWEN_AGENTS_DIRQwen Code
CODEX_AGENTS_DIRCodex
OSAURUS_SKILLS_DIROsaurus
HERMES_HOMEHermes
HERMES_PLUGIN_DIRHermes
VIBE_HOMEMistral Vibe

右边这一列是按变量名做的字面对应。脚本注释给的是变量清单，没有逐一说明每个变量到底作用在路径的哪一层——从命名后缀能看出粒度不同：*_AGENTS_DIR / *_RULES_DIR / *_SKILLS_DIR 看起来指向的是最终存放目录，而 HERMES_HOME、VIBE_HOME、OPENCLAW_DIR 更像配置根目录。这只是我们看命名做的分组，真要按某一层拼路径，回脚本里核对，别拿它当承诺。

这里有个更要紧的边界：这些变量是给 install.sh 读的，管的是「文件被拷到哪儿」。目标工具本身会不会到同一个目录去加载 agent，是那个工具自己的配置问题，仓库没有对此做任何承诺。你把路径改到一个自定义位置之后发现工具里看不到东西，先别怀疑脚本，去查那个工具自己的配置项。

剩下 5 个工具没有对应变量

tools.json 一共列了 16 种工具，上面的变量只覆盖到 11 种。数下来没有专属环境变量的是：Aider、Windsurf、Antigravity、Kimi、ZCode。

其中 Aider 和 Windsurf 的情况还特殊——它们在 tools.json 里的 installKind 是 roster，也就是所有 agent 合并成一个文件（CONVENTIONS.md 和 .windsurfrules），产物形态本身就不是一 agent 一文件。它俩默认写当前目录，靠 cd 就能控制落点，倒也够用。

顺带说一个反向的例子：Hermes 不在这五个里，它是唯一一个独占两个环境变量（HERMES_HOME 和 HERMES_PLUGIN_DIR）的工具。原因大概能从它的 installKind 看出来——它是 plugin，一个构建出来的产物，不能按 agent 渲染成字符串，在所有消费方都只能走 CLI，落点自然要分「配置根目录」和「插件目录」两层来指。这只是我们看变量命名与 installKind 做的推测，不是脚本注释里的说法。

Antigravity、Kimi、ZCode 这三个想换路径，就只剩下 --path。

--path 与 --link：另外两层口子

install.sh 的模式类参数只有两个：

  • --path <dir>——覆盖安装目录，注意脚本 USAGE 写明它是单一目标。也就是说它适合「我只装一个工具，就装到这个目录」的场景，不适合一条命令同时给五个工具各指一个不同的路径。多目标的分别定向，还是得靠上面那 12 个变量。
  • --link——用符号链接代替拷贝，脚本注释说明改动会自动传播。如果你打算自己改 agent 提示词、或者要跟着上游更新走，这个开关比定期重装省事；但代价是目标目录里的东西不再是自洽的独立副本，仓库挪了位置就断了。

一条可以直接抄的完整命令

Linux / macOS 下的写法，把两类口子叠在一起用：

# 1) 先把落点指到自定义目录（这些变量在硬编码默认值之前被检查）
export CLAUDE_CONFIG_DIR="$HOME/ai-config/claude"
export CODEX_AGENTS_DIR="$HOME/ai-config/codex-agents"

# 2) 只打印计划、不写任何东西，先看一眼
./scripts/install.sh \
  --tool claude-code,codex \
  --division engineering,testing \
  --dry-run

# 3) 计划确认无误后，去掉 --dry-run 真正执行
./scripts/install.sh \
  --tool claude-code,codex \
  --division engineering,testing \
  --no-interactive

逐个说这几个选项为什么在这：

  • --tool claude-code,codex：选择器，不给就是「所有检测到的工具」。你既然在意落点，就别让它自己去检测。
  • --division engineering,testing：把范围从 255 个 agent 收窄到两个 division（Engineering 58 个、Testing 9 个）。一次性把全部 agent 灌进全局配置目录是有代价的——上下文占用、工具启动时的加载、命名冲突——所以能收窄就收窄。除了 --division，还有 --agent <slug,slug> 按 agent 挑，以及 --agents-file <path> 从文件读列表（每行一个 slug 或名字，支持 # 注释），后者适合把选择固化进版本库。
  • --dry-run：只打印计划、不落盘。这是这个仓库对新手最有价值的一个开关，往共享目录写几百个文件之前先看一眼，成本几乎为零。
  • --no-interactive：脚本在 TTY 下默认进交互向导，写进脚本或 CI 时要显式关掉，否则会卡在等输入。

补两个批量场景会用到的：--parallel 并行安装各工具（输出按工具缓冲），--jobs N 控制最大并行数（默认取 nproc 或 4）。还有 --no-convert，作用是在集成文件缺失时不自动跑 convert.sh——正常情况别关，因为 install.sh 是从 integrations/ 这个产物目录读已转换的文件，缺失或过期时需要先转换。

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 的实际输出为准。

Windows 侧怎么写

脚本注释里的平台支持是 Linux、macOS（需要 bash 3.2+）、Windows Git Bash / WSL。所以在 Windows 上要在 Git Bash 或 WSL 里执行，环境变量也就按 bash 的 export 写，和上面那段一样。不要在 PowerShell 里直接调 .sh。

如果你用的是 WSL，还要多想一层：WSL 里的 $HOME 和 Windows 侧的用户目录不是同一个位置。装在 WSL 里的路径，Windows 原生安装的 GUI 工具未必会去读。这一点仓库没有讨论过，属于你自己环境的事。

产出物长什么样，以及怎么验收

有依据能说的只有这几件：

  1. --dry-run 只打印计划、不写任何东西，所以第一次跑完之后你的磁盘应该毫无变化。可以顺手 git status 或看一眼目标目录还是不是空的。
  2. 真跑之后，产物落点由 installKind 决定。per-agent 类是每个 agent 渲染出一个文件或一个目录，tools.json 里的用户级模板比如 Claude Code 是 .claude/agents/{slug}.md、Codex 是 .codex/agents/{slug}.toml。所以验收就是去你指定的那个目录 ls 一下，看文件名是不是你选的那批 slug。
  3. roster 类别指望看到一堆文件是白等。Aider 和 Windsurf 只会得到一个合并文件，数量对不上不是 bug。这也是「为什么 Aider 里没法只装某一个 agent」的答案。
  4. --list [tools|teams|agents] 会列出后退出，可以在执行前用它核对自己拼的 slug 和 division 名有没有写错。

最容易在哪一步出错？两处。一是环境变量没导出到实际执行脚本的那个 shell——你在一个终端 export 了，换个窗口跑脚本，变量就没了。二是当前目录派那四个工具，你 cd 错了地方，文件就落在别的项目里，而且不会有任何提示。

还有一个特别值得预警的误判：Cursor 的转换产物（cursor-mdc 格式）frontmatter 里 alwaysApply: false 和 globs: "" 是写死的，也就是说装进去的规则默认不会自动生效，得在 Cursor 里按需引用。如果你改完路径发现「装了跟没装一样」，先排查这一条，别一直去折腾 CURSOR_RULES_DIR。

什么情况别这么干

  • --path 不要用在多工具场景。它是单一目标，一条命令同时装多个工具时用它，结果不会是你想的那样。
  • 不确定变量作用在哪一层时，别硬猜着拼路径。先用 --dry-run 看计划里打出来的路径对不对，比事后清理便宜得多。
  • Hermes 这种 plugin 类不适合手工搬目录。它是构建产物、只能走 CLI，把目录挪走再挪回来这种操作没有依据说它成立。
  • 团队共用的配置目录，改之前先跟人说。尤其 --link 会让改动自动传播，一个人改了源仓库里的 agent 正文，所有链过去的地方跟着变。这是特性也是风险，取决于你们想不想要这个行为。
  • 需要精确落点承诺的生产环境，别只依赖本文这张表。变量清单来自脚本注释，脚本随上游更新而变，唯一可靠的做法是跑一次 --dry-run 让它自己把计划打出来。

最后说句实在的：这个仓库在 2026-08-09 的快照里有 140729 star，但关注度和它适不适合往你的家目录里灌 255 个提示词文件是两回事。先 --division 收窄、先 --dry-run 看计划，比什么路径技巧都管用。

延伸阅读

本文依据 agency-agents 官方仓库（github.com/msitarzewski/agency-agents）的 README、 tools.json、divisions.json、scripts/ 下的安装与校验脚本整理，核对日 2026-08-09。 本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何 agent。 目录、脚本与安装路径随上游更新而变动，请以仓库最新内容与 ./scripts/install.sh --help 的实际输出为准。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员