1. 先别急着重装：gemini 报“无法将项识别为 cmdlet”到底卡在哪
你在 Windows PowerShell 里敲下gemini，回车，屏幕上弹出一行红字：
gemini : 无法将“gemini”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。第一反应通常是“是不是没装成功”，于是又跑一遍npm install -g @google/gemini-cli，npm 依然告诉你 added 1 package，可gemini还是不认识。这个循环我见过太多次，问题基本不在安装本身，而在PowerShell 找不到那个可执行文件。
先把概念说清楚。gemini CLI 是一个跑在终端里的命令行工具，它能帮你读代码、改文件、跑命令，适合习惯在命令行里干活的人。它通过 npm 全局安装后，会在 npm 的全局目录里生成一个gemini.cmd（Windows 上是批处理包装脚本）。PowerShell 执行命令时，会去PATH环境变量列出的目录里挨个找同名文件。如果 npm 全局目录不在PATH里，PowerShell 就永远找不到gemini.cmd，于是报“无法将项识别为 cmdlet”。
这里有个容易混淆的点：npx gemini能跑，不代表gemini能跑。npx会自己去 npm 缓存和全局目录里找包并临时执行，它不依赖PATH。所以“npx 能用、直接敲不行”几乎就是 PATH 问题的铁证。
还有一个坑是包名和命令名不一致。早期 Gemini CLI 的包名是@google/gemini-cli，但生成的命令可能是gemini，也可能是gemini-cli，取决于版本。你得先确认实际生成了哪个可执行文件，再决定敲哪个命令。
这篇就按“先确认装没装、再确认 PATH、最后用统一 Key 通道跑一次最小请求”的顺序走。中间会给你可直接复制的 PowerShell 命令，也会说明每一步的预期输出。如果你后面要接 TaoToken 的统一 Key 通道，配置片段我也会一并给出，省得你来回翻文档。
2. 前置准备：确认 npm 全局目录与 TaoToken 统一 Key 通道
在动 PATH 之前，先把两件事确认清楚：npm 全局目录在哪，以及你打算用什么 API 通道。
2.1 找到 npm 全局安装目录
打开 PowerShell，执行：
npm config get prefix典型输出是：
C:\Users\你的用户名\AppData\Roaming\npm这个目录就是 npm 放全局可执行文件的地方。记住它，后面加 PATH 要用。你可以顺手看看里面有没有 gemini 相关文件：
Get-ChildItem "$(npm config get prefix)\gemini*"预期能看到类似：
gemini.cmd gemini.ps1 gemini如果这里什么都没有，说明包根本没装到这个 prefix 下，那要先解决安装问题，而不是 PATH。可以重新执行：
npm install -g @google/gemini-cli安装完再回来Get-ChildItem确认一次。如果还是空的，检查一下是不是用了 nvm 之类的版本管理器，导致 prefix 指向了别处。
2.2 为什么要接 TaoToken 统一 Key 通道
gemini CLI 默认会走 Google 的接口，需要对应的凭据。如果你手上有多个模型工具，每个都单独配 Key、单独记 Base URL，管理起来很碎。TaoToken 提供统一 Key 和统一 API 通道，把不同模型的调用收敛到一个入口，配置一次就能在多个 CLI 里复用。
它的 API 地址是https://taotoken.net/api，官网在https://taotoken.net/?utm_source=taotoken_aicg_blog_end。你需要在控制台创建一个 API Key，后面配置里会用到。创建入口在控制台的 API Keys 页面，文档在接入文档里，模型对话页面可以用来做纯对话验证。
这里要强调一点：TaoToken 是合规的 API 聚合通道，不是让你绕过什么限制。它的作用是统一管理 Key 和请求入口，方便你在不同工具间切换。配置时把 Base URL 指向https://taotoken.net/api，Key 用你在控制台生成的那串，模型 ID 按文档里列出的填。
2.3 三件套先备齐
不管后面用哪种方式接入，你都需要这三样：
| 项目 | 值 | 说明 |
|---|---|---|
| Base URL | https://taotoken.net/api | 统一 API 入口 |
| API Key | 控制台生成 | 形如sk-... |
| Model ID | 按文档填 | 例如具体模型标识 |
把这三样记在记事本里，下一步配置直接粘贴。如果你还没创建 Key，先去控制台建一个，再回来继续。
3. 可复制配置：PATH 修复 + gemini CLI 接入片段
这一节是核心，分两部分：先把 PATH 修好让gemini能被识别，再写配置文件让 gemini CLI 走 TaoToken 通道。
3.1 把 npm 全局目录加进 PATH
先看当前 PATH 里有没有 npm 全局目录：
$npmPath = npm config get prefix $env:Path -split ';' | Select-String -SimpleMatch $npmPath如果没有任何输出，说明确实不在 PATH 里。用下面这段把它写进用户级 PATH（不需要管理员权限）：
$npmPath = npm config get prefix $userPath = [Environment]::GetEnvironmentVariable("Path", "User") if ($userPath -notlike "*$npmPath*") { [Environment]::SetEnvironmentVariable("Path", "$userPath;$npmPath", "User") Write-Host "已添加: $npmPath" } else { Write-Host "已存在，无需重复添加" }执行完必须重开一个新的 PowerShell 窗口，因为环境变量是进程启动时读取的，当前窗口不会自动刷新。新窗口里再验证：
$env:Path -split ';' | Select-String -SimpleMatch (npm config get prefix) gemini --version预期能看到版本号输出。如果gemini --version还是报错，但gemini-cli --version能跑，说明命令名是gemini-cli，用后者即可。
3.2 确认实际命令名
前面提过包名和命令名可能不一致。用这条命令列出所有候选：
Get-ChildItem "$(npm config get prefix)\gemini*" | Select-Object Name根据输出决定敲哪个命令。如果只有gemini.cmd，就用gemini；如果只有gemini-cli.cmd，就用gemini-cli。两个都有就随便挑一个。
3.3 配置 gemini CLI 走 TaoToken 通道
gemini CLI 的配置方式随版本有差异，常见的是通过环境变量或配置文件指定 Base URL 和 Key。下面给一个通用的环境变量写法，在 PowerShell 里临时生效：
$env:GOOGLE_GEMINI_BASE_URL = "https://taotoken.net/api" $env:GOOGLE_GEMINI_API_KEY = "sk-你的Key"如果要持久化，写进用户环境变量：
[Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://taotoken.net/api", "User") [Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_API_KEY", "sk-你的Key", "User")注意变量名要以你所用版本的文档为准，不同版本可能读不同的键名。如果 gemini CLI 支持配置文件，通常放在用户目录下，形如~/.gemini/settings.json。一个可参考的 JSON 片段：
{ "apiBaseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "model": "你的ModelID" }路径和字段名请对照你安装版本的官方说明，不要照抄字段名。核心是三件套齐全：Base URL 指向https://taotoken.net/api，Key 用控制台生成的，Model ID 按文档填。
3.4 如果命令名确实对不上，加个别名
万一你确认文件存在、PATH 也对，但命令名就是和文档不一致，可以在 PowerShell Profile 里加个别名兜底：
notepad $PROFILE在文件末尾加：
function gemini { & "$(npm config get prefix)\gemini.cmd" @args }保存后重新加载：
. $PROFILE这样gemini就能映射到实际的 cmd 文件。不过这只是兜底，优先还是把 PATH 修对。
4. 验证请求：跑一次最小调用确认通道打通
PATH 修好、配置写完，接下来要验证两件事：命令能被识别，以及请求能通过 TaoToken 通道发出去。
4.1 先验证命令识别
新开 PowerShell，执行：
gemini --version预期输出类似：
0.x.x如果这一步就报“无法将项识别为 cmdlet”，回到第 3 节检查 PATH 和命令名。命令识别是前提，不然后面都免谈。
4.2 发一次最小请求
用 gemini CLI 发一条最简单的提示，比如：
gemini "用一句话说明什么是命令行工具"如果配置正确，你会看到模型返回的一句话。这一步能跑通，说明 Base URL、Key、Model ID 三件套都对，通道是通的。
如果 gemini CLI 的交互模式不好脚本化，你也可以先用模型对话页面做一次纯对话验证，确认 Key 本身有效，再回来调 CLI。模型对话入口在官网导航里能找到。
4.3 用 curl 直接验证 API 通道
想更纯粹地验证 TaoToken 通道，可以绕过 CLI，直接用 curl 打一次：
curl.exe -X POST "https://taotoken.net/api/v1/chat/completions" ` -H "Authorization: Bearer sk-你的Key" ` -H "Content-Type: application/json" ` -d '{ "model": "你的ModelID", "messages": [{"role": "user", "content": "ping"}] }'预期返回一段 JSON，里面有choices字段和模型回复内容。如果返回 401，说明 Key 不对；如果返回模型不存在，说明 Model ID 填错；如果连接失败，检查网络和 Base URL 拼写。
这一步能过，说明通道没问题，剩下的就是 CLI 配置的事。
4.4 成功结果长什么样
一次成功的调用，你会看到类似结构：
{ "id": "chatcmpl-xxx", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "pong" } } ] }看到choices里有内容，就说明请求完整走通了。把这个结果和 CLI 的输出对照，两边一致就放心了。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节把你会遇到的典型报错逐个拆开，对照着查。
5.1 401 Unauthorized
报错长这样：
401 Unauthorized原因基本是 Key 不对或没带上。检查三处：Key 是不是复制时多了空格；环境变量名是不是写错导致没生效；请求头里Authorization: Bearer后面有没有跟 Key。用echo $env:GOOGLE_GEMINI_API_KEY确认当前窗口读到的值。
5.2 local proxy failed
报错类似：
local proxy failed: connection refused这通常说明 CLI 试图连一个本地代理端口，但那个端口没服务。检查你是不是配了HTTP_PROXY或HTTPS_PROXY环境变量指向了本地端口。如果有，先清掉：
Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue然后重试。TaoToken 通道是直连https://taotoken.net/api，不需要本地代理。
5.3 reading choices 相关报错
报错类似：
error reading choices: unexpected end of JSON input这多半是响应体不是预期 JSON，可能是 Base URL 拼错打到了别的路径，或者 Model ID 不存在导致返回了错误页。先用第 4.3 节的 curl 验证一次，看返回的原始内容是什么。如果返回的是 HTML 错误页，说明 URL 不对；如果是 JSON 但结构不同，说明模型名或接口版本对不上。
5.4 OAuth 相关报错
报错类似：
OAuth token expired or invalid说明 CLI 还在走默认的 OAuth 流程，没读到你配的 API Key。检查配置优先级：环境变量和配置文件可能互相覆盖，确认你改的是实际生效的那一层。有些版本需要显式指定用 API Key 模式，而不是 OAuth 模式，具体开关看文档。
5.5 命令名对不上
如果gemini报错但gemini-cli能跑，就是命令名问题。用第 3.2 节的方法确认实际文件名，或者用第 3.4 节的别名兜底。别在这上面耗太久，确认清楚就行。
5.6 PATH 改了但没生效
最常见的原因是没重开终端。环境变量在进程启动时读取，改完必须新开窗口。另一个原因是写到了系统级 PATH 但当前用户没权限读，或者写错了变量名。用$env:Path -split ';'打印出来，肉眼确认 npm 全局目录在不在列表里。
6. 后续怎么用：把统一 Key 通道接进你的日常编码流
PATH 修好、通道验证通过之后，gemini CLI 就能正常用了。接下来可以考虑把它接进更长期的编码工作流。
如果你只是偶尔用一下，当前配置就够了。如果你打算把 gemini 当成日常编码助手，或者要接多个 Agent 工具，建议把 TaoToken 的 Coding Plan 用起来。它适合长期编码和 Agent 场景，统一 Key 通道能让多个工具共享同一套凭据，省去反复配置的麻烦。
具体来说，你可以把 Base URL 和 Key 配到多个 CLI 里，比如 gemini、其他编码工具，都指向https://taotoken.net/api。这样换工具时不用重新申请 Key，也不用记多套地址。控制台里可以管理这些 Key，接入文档里有各工具的配置示例。
排障和接入相关的问题，优先看接入文档和 API Keys 页面。想先验证模型效果，用模型对话页面最直接。长期编码或跑 Agent，再考虑 Coding Plan。
最后提醒一句：PATH 这类环境问题，改完一定要新开终端验证，别在当前窗口反复试。我踩过的坑就是改完 PATH 没重开窗口，以为没生效，又折腾了半天。确认命令识别、再确认通道连通，两步分开查，定位会快很多。
