$ UNIXWIN

← Agent 目录 / 通用指南

给任意 Agent 接上 niubash

通用指南 适用任意 agent 事实来源：agents.md

agent 怎么选 shell 是有规律的——摸清它的探测机制，就能接线。 你的 agent 从不在「你正用的 shell」里跑命令：它自己挑一个，而在 Windows 上 这个挑选只由四种探测机制决定。下面把它们逐一拆开，再给一条三步决策流， 目录里没列过的 agent 也能照此接上。

让 AI 接入 niubash →

已适配 24 个 AI agent——15 个开箱即用，另有 38 个候选在调研管道

① 我用 Claude Code / Codex / Cursor…

去目录挑你的 agent——开箱可换与 VSCode 家族都有换壳脚本、验证命令与回滚方法。

去目录挑 →

② 我的 agent 不在列表

本页就是通用接线指南：四种探测机制 + 三步决策流，往下看即可。

开始接线 ↓

③ 让 agent 自己装

AI 门户：把一键安装提示词粘给你的 agent，它自己完成安装与接线。

打开 AI 门户 →

四种探测机制

出自 agents.md「The four mechanisms」。前三种都能由你接线； 第四种是所有裸名调用的硬伤，也是另外三种存在的原因。 每行的「怎么接线」落到第 3 步决策流 里的对应可复制块。

机制覆盖面怎么接线
① $SHELL · POSIX 约定 读进程环境的 agent——最大的一类，含所有 POSIX 风格 CLI （opencode 是纯样本：二进制里 0 处 niu、无 shell 配置项， $SHELL 就是全部机制）。 niu 会话内自动生效：niu 导出 SHELL=<niu.exe 路径>。 但 $SHELL 不持久化——从开始菜单 / Explorer 启动的同一个 agent 拿到的是空值。 在 niu 里启动 agent（第 3 步·第 1 步试跑），或把 SHELL 写入用户环境变量持久化（块 a）。
② per-agent 显式配置 提供 shell 配置文件字段 / CLI 旗标的 agent： Zed（terminal.shell.program）、Claude Code （CLAUDE_CODE_GIT_BASH_PATH）、VS Code 家族 （automationProfile）、DSH（profile 插件）。 读配置项的机制与启动方式无关——设一次，永久生效。 先按第 4 节自查法找到它的 shell 设置项，再指到 niu.exe 或安装器占位的 bash.exe（块 b 是 VS Code 家族的通用片段）。
③ Git for Windows 探针 硬编码 Git 路径、或从 PATH 上的 git 反推的 agent： Claude Code（先扫 C:\Program Files\Git 与 x86 目录，再从 git 反推）、 VS Code 全家（Copilot / Windsurf / Trae / ZCode + Cline、Roo Code、Kilo Code、Continue 等扩展）。 探的是固定位置：C:\Program Files\Git\bin\bash.exe 等。 niubash 安装器已在该路径占位 bash.exe（含 x86 候选与 sh.exe），需管理员跑一次（块 c 验证）。
④ 裸名解析 把 bash / sh 裸名丢给 PATH / ComSpec / PATHEXT 解析的调用方。 硬伤：CreateProcess 的搜索序里系统目录（System32）排在 PATH 之前——裸 bash 永远先命中 C:\Windows\System32\bash.exe（WSL）。详见 agents.md「Why PATH cannot win against System32」。 用户 PATH 抢不过 System32：要么给完整路径指到 Git 探针（并入③），要么让调用方改用 sh（System32 没有 sh 同名者）。

接线决策流（三步）

第一步 · 永远先试「在 niu 会话里启动」

这是唯一「通常直接就成」的做法：niu 导出 SHELL=<niu.exe 路径>， 遵循 POSIX 约定的 agent 原样采用。agents.md 的作者就这么跑： 进程树 powershell.exe ← niu.exe ← opencode.exe， 而 opencode 的 shell 选择器就是 process.env.SHELL ?? which("bash") ?? "/bin/sh"。 成本为零，先试它。

niu 会话内启动 + 验证 
# 1) 进入 niu 会话（SHELL 在这里导出，指向 niu.exe）
niu

# 2) 在 niu 会话里启动你的 agent（示例）：
opencode          # 或 codex / 任意 CLI agent

# 3) 让 agent 跑下面这条验证命令，再按第 2 步对号入座
#    echo "SHELL=$SHELL"; uname -s; uname -a
让 agent 跑的验证命令： echo "SHELL=$SHELL"; uname -s; uname -a

但 $SHELL 不持久化：它只存在于 niu 会话的后代进程里。 从开始菜单 / Explorer 启动的同一个 agent 拿到空 $SHELL， 回落 which("bash")——在装了 WSL 的机器上解析到 C:\Windows\System32\bash.exe，命令就跑在 Linux 里。 所以还需要下面两步把结果钉住。

第二步 · 看结果对号入座

把 agent 跑出的三行输出对照下面的签名表（默认收起，点开「原理」即看）：

原理：它怎么选 shell——uname 签名表

签名表用人话读：看到 MSYS_NT 就是已经在 niu 里（成功）； MINGW64 是掉进了 Git Bash；Linux 是掉进了 WSL； 命令不存在、$SHELL 为空是还停在 PowerShell/cmd。

你看到实际 shell下一步
uname -s = MSYS_NT-…，且 uname -a 结尾 x86_64 Msys niu（winuxcmd shim） 成功 $SHELL 已指向 niu.exe；要跨启动方式钉住就补块 a。 MSYS_NT 是我们有意伪装的兼容人格（uname 报 MSYS 让老脚本以为在 MSYS 里）， 并非真的 MSYS 运行时——niu 内部没有 MSYS。
uname -s = MINGW64_NT-…，MSYSTEM=MINGW64 Git Bash（Git for Windows 自家运行时） 被探针型机制抢了：走机制③（占位路径生效后，探针改打 niubash 的 bash.exe）或机制②（显式指定），也可持久化 $SHELL 兜底。
uname -s = Linux WSL——agent 回落 which("bash") 命中 System32\bash.exe 中招最深的静默错壳：走机制②或机制③，并用机制①（块 a）防回落。
uname 不存在，$SHELL 为空 PowerShell 或 cmd（用 $PSVersionTable.PSVersion vs %COMSPEC% 区分） 安全但不兼容 bash 语法：走机制②（VS Code 家族即块 b）。

这套签名检查同样出现在 Cursor 官方支持帖里：修复的判定就是 uname -a 结尾从 microsoft-standard-WSL2 变成 MINGW64_NT-…——换成 niu 的目标则是 MSYS_NT-…（结尾 x86_64 Msys）。

第三步 · 按机制给配置（三段可复制块）

块 a · 持久化 $SHELL（机制① · PowerShell · 用户级 · 免管理员） 
# 把 SHELL 写入用户环境变量（安装器同款做法：一处注册表值，免提权）
# 路径按实际安装位置调整；默认装在 %LOCALAPPDATA%\Programs\Niubash
[Environment]::SetEnvironmentVariable('SHELL', "$env:LOCALAPPDATA\Programs\Niubash\niu.exe", 'User')

# 撤销（与安装器卸载语义一致）：
# [Environment]::SetEnvironmentVariable('SHELL', $null, 'User')

# 注意：只对之后新开的进程生效——写完请重开终端 / agent

安装器本身也会把 SHELL 写进用户环境（卸载时移除）——这是 agents.md「Recommended order of work」的第 1 项：一个注册表值、无需提权， 覆盖最大一类 agent（所有 POSIX 风格 CLI），并让 $SHELL 不再依赖启动方式。上面命令是同款做法的手动版。

块 b · settings.json automationProfile（机制② · VS Code 家族通用） 
// VS Code 家族 settings.json（VS Code / Windsurf / Trae / ZCode，以及走编辑器
// 终端或 automation profile 的 Cline、Roo Code、Kilo Code、Continue 等扩展）
// path 换成你的实际安装路径，默认 %LOCALAPPDATA%\Programs\Niubash\niu.exe：
"terminal.integrated.automationProfile.windows": {
  "path": "C:\\Users\\<你的用户名>\\AppData\\Local\\Programs\\Niubash\\niu.exe",
  "args": []
}

通过 automation profile 外呼命令的 agent 会继承该配置（VS Code 家族的显式控制法）。 占位路径之外，把 profile 指到 niu.exe 是跳过 bash.exe 启动器一跳的写法。

Cursor 例外：Cursor 的 IDE agent 无视 terminal.integrated.defaultProfile.windows 与 automationProfile.windows，仍跑 PowerShell（变通是开启 Legacy Terminal Tool 设置）；其 Agent CLI 更是硬编码 PowerShell。详见 Cursor 详情页。

块 c · 验证安装器占位的 Git 探针路径（机制③） 
# 安装器的可选提权步骤（管理员跑一次）会放置机制③所需的占位：
#   C:\Program Files\Git\bin\bash.exe         <- Claude Code / VS Code 家族硬编码探针 1
#   C:\Program Files (x86)\Git\bin\bash.exe   <- 第二候选路径
#   C:\Program Files\Git\bin\sh.exe           <- 要求 bash 旁边有 sh 的工具
# 验证占位是否到位（第一行应输出 True；第二行应输出 MSYS_NT-...）：
Test-Path 'C:\Program Files\Git\bin\bash.exe'
& 'C:\Program Files\Git\bin\bash.exe' -c 'uname -s'

这几个文件由安装器的可选提权步骤放置——需要管理员权限跑一次 （Program Files 不是用户 PATH 能写的地方），属「一次成本、全家受益」： Claude Code 与 VS Code 家族的硬编码探针从此都打到 niubash 的启动器上。 该 bash.exe 不是 niu 本体，而是启动 niu.exe 子进程的启动器 （agent → bash.exe → niu.exe）：多花约 17.6 ms/次 -c 调用（niubash#377）；历史上的「每条命令闪一个 console 窗口」问题（niubash#379） 已在 rubash#668 修复，随下一次 rubash 升级发布——升级后可顺手验证闪窗消失。

目录没列的 agent？自查三问

已核验名单只有九个，而 agent 生态远不止。大多数 agent 的 shell 探测 藏在三处之一——按顺序问：

查明白了？欢迎提 PR把结论补进 /agents/ 目录 （agent 名、机制归类、配置方法、验证输出四件套）： github.com/unixwin/unixwin.dev ↗。 agents.md 的「未核验」名单还很长——Amazon Q Developer CLI、Goose、Amp、OpenHands、 Devin……每一份实测侦察都算贡献。

接线时别干这两件事（agents.md「Two things not to do」）： 一是别把 winuxcmd\usr\bin 加进 PATH——几百个名字，其中不少与 System32 撞名； 二是别去替换 C:\Windows\System32\bash.exe。

Known traps · 四条

来源