AI终端助手三剑客：Claude Code、Codex CLI、Gemini CLI安装配置与选型指南-平芜编程栈

1. 为什么要在电脑上折腾 AI 终端助手

1.1 从“网页聊天”到“终端里干活”的转变

很多人第一次接触大模型，都是在浏览器里开一个对话框，问一句答一句。这种方式适合查资料、写文案，但一旦落到真实的开发场景里，问题就来了：你正在终端里跑一个构建脚本，报了一屏错误，想复制出来问 AI，得先选中、复制、切窗口、粘贴，等它回复完，再切回来改代码。来回折腾几次，思路就断了。

AI 终端助手解决的正是这个“断片”问题。它把模型能力直接塞进你每天敲命令的地方——终端。你在项目目录里直接输入一句自然语言，它就能读你的文件、跑你的命令、改你的代码，全程不用离开键盘。Claude Code、Codex CLI、Gemini CLI 这三个是目前在开发者圈子里讨论度比较高的代表，它们形态相似但各有侧重，下面我会把三者的安装、配置、日常用法和踩坑经验一次讲透。

这篇文章适合谁看？如果你满足下面任意一条，就值得往下读：

你每天有大量时间泡在终端里，想少切窗口、少复制粘贴；
你想让 AI 直接操作你的项目文件，而不是只给你一段“参考代码”；
你已经在用某个网页版模型，但觉得“它看不到我的项目”很别扭；
你想对比几个终端助手，挑一个长期用下去。

需要先说明一点：这三个工具都依赖背后的模型服务，使用前你需要有对应平台的账号和访问凭证。具体怎么获取，各平台规则不同，本文不展开，只讲拿到凭证之后怎么在电脑上把它跑起来、用顺手。

1.2 三个工具一句话定位

先用最直白的话把它们区分开，方便你决定先装哪个：

工具	一句话定位	典型使用场景
Claude Code	深度理解项目、擅长多文件重构	大型代码库改造、跨文件逻辑梳理
Codex CLI	轻量、启动快、命令执行直接	快速脚本编写、单文件调试
Gemini CLI	免费额度友好、多模态输入	日常问答、图片/截图辅助理解

这个定位不是绝对的，三者能力有重叠，但上手之后你会发现各自的“手感”确实不一样。我的建议是：如果你只想装一个，先装 Claude Code，它对项目的理解深度最让人省心；如果你预算敏感或者想先试试水，Gemini CLI 的免费额度足够你玩很久。

2. 装之前必须搞清楚的几件事

2.1 运行环境的最低要求

这三个工具本质上都是命令行程序，通过 Node.js 或独立二进制分发。装之前先确认你的环境：

操作系统：macOS、Linux 原生支持最好；Windows 用户建议用 WSL2，直接在 PowerShell 里跑也能用，但路径和权限问题会多一些。
Node.js 版本：多数工具要求 18 以上，建议直接上 20 LTS。用node -v查一下，版本太低就先升级。
终端：系统自带终端够用，但如果你想要更好的体验，iTerm2（macOS）或 Windows Terminal 会更舒服，尤其是需要看彩色输出和长文本滚动时。
网络：这一点不用多说，能正常访问对应服务即可，具体配置各人环境不同，自行处理。

提示：Windows 用户如果遇到command not found或者路径里出现反斜杠报错，八成是没走 WSL。别硬扛，装个 WSL2 能省掉后面 90% 的奇怪问题。

2.2 账号与凭证的准备思路

三个工具都需要一个“钥匙”才能调用模型。这个钥匙通常是一串 API Key 或者登录态。获取方式各平台不一样，我这里只讲拿到之后怎么管：

不要硬编码在代码里。把 Key 写进脚本然后提交到仓库，是新手最常犯的错。正确做法是放进环境变量，或者用工具自带的登录命令。
环境变量命名要记牢。不同工具用的变量名不同，装的时候看清楚文档，写错了它不会报“你写错了”，只会报“未授权”，很容易误导。
多工具共存时注意隔离。如果你三个都装，建议给每个工具单独建一个 shell 配置文件片段，或者用 direnv 这类工具按目录加载，避免互相覆盖。

我自己的习惯是在~/.zshrc里统一管理，每个工具一段注释隔开，改的时候一眼能找到。这个习惯在后期排查“为什么这个工具突然不认我的 Key 了”时特别有用。

2.3 安装方式的选择逻辑

三个工具都提供了多种安装途径，常见的有 npm 全局安装、官方安装脚本、包管理器（brew 等）。怎么选？

npm 全局安装：最通用，跨平台一致，升级用npm update -g就行。缺点是依赖 Node 环境，Node 出问题它也跟着出问题。
官方脚本：通常是一行 curl 管道到 shell，装的是独立二进制，不依赖 Node。启动快，但升级要重新跑脚本。
包管理器：macOS 上用 brew 最省心，升级、卸载都干净。Linux 上看发行版，有的有官方源。

我的建议：如果你 Node 环境本来就干净，用 npm 装最省事；如果你不想让 Node 版本问题牵连到 AI 工具，用官方脚本装独立版。下面实操部分我会以 npm 为主，因为它的报错信息最清晰，出问题好排查。

3. Claude Code 实操：从安装到第一次改代码

3.1 安装与初始化

假设你已经装好了 Node 20，打开终端：

npm install -g @anthropic-ai/claude-code

装完之后，进入你的项目目录，直接输入：

claude

第一次运行它会引导你完成登录或配置凭证。这一步跟着提示走就行，它会让你粘贴 Key 或者打开浏览器授权。完成后你会看到一个交互式界面，光标在底部等着你输入。

这里有个细节：一定要在项目根目录启动。Claude Code 会把当前目录当作工作区，它能读到的文件范围基本就是这个目录及其子目录。如果你在 home 目录启动，它会试图索引一大堆无关文件，又慢又乱。

3.2 让它读懂你的项目

启动后第一件事，不是马上让它改代码，而是先让它“熟悉环境”。我通常会说：

请先浏览当前项目结构，告诉我这是一个什么类型的项目，主要模块有哪些，用了哪些技术栈。

它会自己去读package.json、README、目录结构，然后给你一个概览。这一步的价值在于：你能立刻判断它有没有“看懂”。如果它把测试目录当成核心模块，或者漏掉了关键配置文件，说明你的项目结构可能有点乱，或者需要在项目里加一个说明文件告诉它重点在哪。

我实测下来，Claude Code 对中等规模项目（几百个文件）的理解相当准。它会主动去读相关文件，而不是只扫一眼文件名。这一点比很多“只看你粘贴的代码”的工具强太多。

3.3 一次真实的多文件重构记录

举个我实际遇到的场景：一个老项目里，日志模块散落在十几个文件里，每个文件都自己console.log，格式还不统一。我想统一成一个 logger 工具。

我的操作流程是这样的：

先描述需求：“项目里日志输出很乱，我想统一成一个 logger 模块，支持日志级别，替换掉所有直接的 console.log。”
它会先搜索所有console.log出现的位置，列给我看。
我确认范围后，它开始逐个文件修改，每改一个会告诉我改了什么。
改完让我 review，我可以用/diff看具体改动。

整个过程大概十几分钟，涉及二十多个文件。如果手动改，我估计要一两个小时，还容易漏。这里的关键经验是：先让它列清单，你确认后再动手。直接说“帮我改”它也会改，但万一范围理解错了，回滚很麻烦。

注意：改之前确保你的项目在 git 管理下，并且工作区是干净的。这样万一改崩了，git checkout .一键回滚。这是用任何 AI 改代码工具的铁律。

3.4 常用命令与交互技巧

Claude Code 的交互界面里有一些快捷操作，用熟了效率翻倍：

/help：看所有可用命令，忘了就敲这个。
/diff：查看本次会话的所有文件改动，review 必备。
/clear：清空当前对话上下文，换任务时用，避免它被之前的对话干扰。
Esc：中断当前正在执行的操作，它跑偏了随时喊停。

还有一个技巧：用自然语言描述“为什么”而不只是“做什么”。比如不说“把这个函数改成 async”，而说“这个函数里的 IO 操作阻塞了主流程，我想让它异步化，你看怎么改合适”。后者它会考虑更多上下文，给出的方案往往更合理。

4. Codex CLI 实操：轻快直接的命令执行

4.1 安装与首次运行

Codex CLI 的安装同样走 npm：

npm install -g @openai/codex

装完在项目目录里输入codex启动。它的界面比 Claude Code 更简洁，启动速度也更快，基本是秒开。第一次运行同样需要配置凭证，跟着提示走即可。

Codex CLI 的一个特点是它对“执行命令”这件事特别直接。你让它跑个测试，它真的会去跑，然后把输出拿回来分析。这一点在调试时非常爽——你不用自己复制错误信息，它自己就能看到。

4.2 适合它的任务类型

用了一段时间后，我总结出 Codex CLI 最擅长的几类活：

写一次性脚本：比如“把这个目录下所有图片转成 webp”，它直接给你脚本并执行。
单文件调试：某个函数报错，把文件路径给它，它能定位并修复。
命令解释：遇到一条看不懂的 shell 命令，直接问它，解释得比 man 手册通俗。

它不太擅长的是一次性动几十个文件的大重构，那种活还是交给 Claude Code。这不是能力问题，是设计取向——Codex CLI 更偏向“快速响应、单点解决”。

4.3 一个调试实例

有次我跑一个 Python 脚本，报了个KeyError，但错误信息只说了哪个 key，没说哪一行。我把脚本路径给 Codex CLI，说“这个脚本报 KeyError，帮我定位并修复”。

它的操作是：先读脚本，找到所有字典访问的地方，然后跑一遍脚本复现错误，根据 traceback 定位到具体行，最后给出修复方案。整个过程不到一分钟。如果我自己来，可能要在几个字典访问之间来回看半天。

这里有个经验：给它复现命令，比只给错误信息更有效。你可以直接说“运行python script.py会报错，帮我看看”，它自己跑一遍比看你粘贴的错误日志理解得更深。

4.4 与 Claude Code 的配合用法

我现在是两个都用：Claude Code 负责“大工程”，Codex CLI 负责“小快灵”。具体分工：

新功能开发、跨模块重构 → Claude Code
临时脚本、单点 bug、命令查询 → Codex CLI
两个都开着，哪个顺手用哪个

它们不冲突，可以同时装。唯一要注意的是凭证管理别搞混，各自的环境变量分开写清楚。

5. Gemini CLI 实操：免费额度下的日常助手

5.1 安装与配置

Gemini CLI 的安装方式：

npm install -g @google/gemini-cli

启动命令是gemini。它的配置流程稍微不同，通常需要你先在对应平台拿到 API Key，然后通过环境变量或配置文件传入。具体变量名以官方文档为准，我这里不写死，因为平台规则可能调整。

Gemini CLI 最大的吸引力是免费额度比较友好，对于日常问答、代码解释、小段代码生成这类轻量任务，基本够用。如果你还在观望要不要为 AI 工具付费，从它开始试水是个不错的选择。

5.2 多模态输入的实用场景

Gemini 系列对图片的理解能力是它的一个亮点。在终端里，你可以把一张截图或者设计稿的路径给它，让它分析。实际用下来，这几个场景特别实用：

看报错截图：有时候错误在图形界面里，截图给它，它能读出错误信息并给建议。
看 UI 设计稿：把设计图给它，让它生成对应的 HTML/CSS 骨架。
看流程图：手绘的流程图拍照给它，让它转成文字描述或代码逻辑。

这个能力在终端工具里不算普遍，算是 Gemini CLI 的差异化优势。不过要注意，图片路径要写对，终端里没有“拖拽上传”这种操作，得手动敲路径。

5.3 日常问答的顺手用法

除了多模态，Gemini CLI 在日常问答上也很顺手。我经常用它做这几件事：

解释一段看不懂的正则表达式；
把一段 shell 命令翻译成人话；
快速生成一个常用配置文件的模板。

它的响应速度不错，免费额度下也没有明显的卡顿感。对于“我就问一句”的场景，比打开浏览器快得多。

5.4 什么时候该换工具

Gemini CLI 也有它的边界。当你需要它深度理解一个大型项目、做跨文件重构时，它的表现不如 Claude Code 稳定。这不是说它不行，而是各家的侧重点不同。我的做法是：轻量任务用 Gemini，重活换 Claude Code，两者互补。

6. 三个工具横向对比与选型建议

6.1 能力对比表

维度	Claude Code	Codex CLI	Gemini CLI
项目理解深度	强	中	中
启动速度	中	快	快
多文件重构	擅长	一般	一般
命令执行	支持	支持且直接	支持
多模态输入	有限	有限	强
免费额度	无	无	有
上手难度	低	低	低

这张表是我用下来的主观感受，不是官方参数。你的实际体验可能因为项目类型、使用习惯而不同。

6.2 按需求选型

只想装一个，且预算不敏感：Claude Code。它的项目理解能力最省心，长期用下来效率提升最明显。
预算敏感，先试试水：Gemini CLI。免费额度够你判断自己是否真的需要这类工具。
经常写脚本、调 bug：Codex CLI。它的命令执行最直接，调试体验流畅。
全都要：三个都装，按任务类型切换。它们不冲突，共存没压力。

6.3 我的实际组合

我现在的主力组合是 Claude Code + Codex CLI。Gemini CLI 偶尔用来处理图片相关的任务。这个组合覆盖了我 95% 的终端 AI 需求。装三个不会让电脑变慢，它们都是按需启动的，不用的时候不占资源。

7. 常见问题与排查技巧实录

7.1 安装阶段的典型报错

报错一：EACCES权限错误

这是 npm 全局安装最常见的坑。原因是 npm 的全局目录权限不对。解决方案有两个：

方案 A：用 nvm 管理 Node，全局包会装到用户目录下，不会有权限问题。这是我最推荐的方式。
方案 B：改 npm 全局目录到用户目录：npm config set prefix ~/.npm-global，然后把~/.npm-global/bin加进 PATH。

不要用sudo npm install -g，这会把文件属主搞乱，后面升级时更麻烦。

报错二：command not found

装完了但敲命令没反应，八成是 PATH 没配好。用npm bin -g看看全局 bin 目录在哪，确认它在你的 PATH 里。改完 PATH 记得source ~/.zshrc或重开终端。

报错三：Node 版本过低

工具要求 Node 18+，你系统里可能是老版本。用node -v确认，低了就升级。如果你不想动系统 Node，用 nvm 装一个新版本，按项目切换。

7.2 运行阶段的常见问题

问题一：启动后一直转圈，没反应

先检查网络是否能正常访问对应服务。如果网络没问题，可能是凭证配置有误。重新跑一次登录流程，或者检查环境变量名有没有拼错。环境变量名拼错是最隐蔽的坑，因为工具通常只报“未授权”，不会告诉你“你变量名写错了”。

问题二：它读不到我的文件

确认你是在项目根目录启动的。如果项目有特殊的目录结构（比如代码在src/下但配置在根目录），可以在第一次对话时明确告诉它“代码在 src 目录，配置在根目录”。它会记住这个上下文。

问题三：改代码改错了，怎么回滚

如果你在 git 管理下，git diff看改动，git checkout .全部回滚，或者git checkout -- 文件名回滚单个文件。如果没在 git 下，那就只能手动改了。所以再强调一次：用 AI 改代码前，确保 git 工作区干净。

问题四：响应很慢

可能是模型服务端负载高，也可能是你的网络到服务端的链路问题。换个时间段试试，或者换一个工具对比一下。如果三个都慢，那大概率是网络环境问题，不是工具本身的问题。

7.3 避坑速查表

现象	可能原因	解决方向
安装报 EACCES	npm 全局目录权限	用 nvm 或改 prefix
命令找不到	PATH 未配置	检查全局 bin 目录
启动转圈	网络或凭证	检查网络，重配凭证
读不到文件	启动目录不对	在项目根目录启动
改错代码	未用 git	改前确保工作区干净
响应慢	服务端或网络	换时段或换工具对比

7.4 几条用血泪换来的经验

第一，永远在 git 干净的状态下让 AI 改代码。我有一次偷懒，工作区里有一堆没提交的改动，结果 AI 改完之后我分不清哪些是它的、哪些是我自己的，最后只能全部丢弃重来。从那以后，改代码前必git status确认。

第二，先让它说方案，你同意了再动手。直接说“帮我改”它也会改，但万一方向错了，回滚成本高。养成“先讨论、后执行”的习惯，效率反而更高。

第三，上下文不是越长越好。一个任务做完，用/clear清掉，再开新任务。上下文里堆太多无关信息，它的判断会变差。这跟人一样，同时想太多事容易乱。

第四，凭证不要写在项目文件里。用环境变量，或者工具自带的凭证管理。项目文件可能被提交、被分享，写死在里面等于泄露。

第五，三个工具不要同时在一个项目里改同一个文件。它们互相不知道对方改了什么，容易冲突。一个任务用一个工具，做完再换。

8. 进阶玩法与效率提升

8.1 把常用提示词存成模板

如果你经常做某类任务，比如“给这个函数写单元测试”，可以把提示词存成一个文本文件，用的时候直接引用。Claude Code 支持从文件读取提示，具体方式看它的文档。这样能省掉每次重新描述的时间，也保证提示质量稳定。

8.2 结合 git hook 做自动化

一个进阶玩法是把 AI 检查接进 git hook。比如在 pre-commit 阶段，让 AI 检查本次改动的代码有没有明显问题。这个玩法需要一些脚本功底，但搭好之后很省心。注意不要让 AI 的检查阻塞正常的提交流程，它应该是“提示”而不是“拦截”。

8.3 多工具协同的工作流

我现在的典型工作流是这样的：

用 Gemini CLI 快速查资料、解释概念，确定方案方向；
用 Claude Code 做实际的代码修改和重构；
用 Codex CLI 跑测试、调试报错；
改完用 git 提交，提交信息让 Claude Code 帮忙生成。

这个流程跑顺之后，我从“想做什么”到“代码提交”的时间明显缩短。关键不是工具多，而是每个工具用在它最擅长的地方。

8.4 保持对代码的掌控感

最后说一个心态问题。AI 终端助手很强，但你不能完全放手。我的原则是：每一行它改的代码，我都要能看懂。如果它改了一段我看不懂的逻辑，我会让它解释，解释不清楚就回滚重来。工具是来放大你的能力的，不是来替代你的判断的。保持这个心态，你用得越久，效率越高，而不是越用越依赖、越用越心虚。

这套东西我前后折腾了小半年，从最开始装一个报错半天，到现在三个工具切换自如，中间踩的坑基本都写在上面的排查表里了。如果你刚开始，建议先从 Gemini CLI 试水，觉得顺手了再上 Claude Code。别一上来就三个全装，容易懵。