1. 准备环境先别急着执行 npm install1.1 Node.js 版本两个命令行的共同门槛Claude Code 和 Codex CLI 表面上看起来是两个不同公司的产品但安装方式非常一致它们都是基于 Node.js 生态分发的命令行工具安装命令都是npm install -g。所以 Node.js 版本就是第一道坎很多用户遇到“装完 command not found”“运行报语法错误”“界面起不来”这类问题十有八九是 Node 版本太老。先说我的结论Claude Code 官方要求 Node.js 18 及以上Codex CLI 建议 Node.js 20 及以上。我个人的习惯是直接装当前 LTS 版本比如 Node.js 22 LTS因为 LTS 版本在生态兼容性上最省心。你不需要追最新大版本也不要长期停留在 16 这种年代久远的版本否则后面查问题会非常痛苦。Windows 上装 Node.js 我比较推荐两条路线。一条是去官网下载 LTS 安装包一路下一步简单粗暴另一条是用 winget 一行命令安装winget install OpenJS.NodeJS.LTSmacOS 用户可以直接用 Homebrewbrew install nodeLinux 用户我比较推荐用 nvm 管理 Node 版本因为系统自带的源通常比较旧curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts nvm use --lts装完之后不要急着装 AI 工具先在终端里验证一下环境node -v npm -v如果node -v能正常输出版本号说明 Node.js 环境可用。如果输出 command not found优先检查安装过程中是不是没有把 Node.js 加入 PATH。Windows 上安装包一般会自动配好 PATH但有时候需要重新打开终端才能生效。还有一点这两个 CLI 对 npm 版本也有一定要求。npm 通常随 Node.js 一起更新npm -v能看到版本。如果 npm 太老建议执行npm install -g npmlatest升级一下避免安装时出现奇怪的权限问题或解析问题。1.2 Git装好总比不装好很多人会问我不做传统软件开发只是想让 AI 帮我写脚本也需要装 Git 吗我的答案是装好而且尽早装。Claude Code 和 Codex CLI 在项目里干活时经常需要依赖 Git 来理解代码变更。比如 Claude Code 会根据当前 Git 仓库的 diff 帮你做代码审查Codex CLI 在执行修改类任务时也会把文件变更情况纳入上下文。如果没有 Git这些能力会大打折扣。Windows 下装 Git 最简单的方式winget install Git.Git也可以去 Git 官网下载安装包。安装时如果看到 PATH 相关的选项选择 “Git from the command line and also from 3rd-party software” 那一项确保git命令能被命令行工具找到。macOS 上如果没装 Xcode Command Line Tools直接执行git --version会触发系统弹窗引导安装或者用 Homebrewbrew install git装完以后建议先做一次基础配置因为后面 AI 工具生成 commit 时要用到你的提交者信息git config --global user.name 你的名字 git config --global user.email 你的邮箱验证命令git --version能输出版本号就算成功。如果输入git --version报 command not found大概率是安装时没有勾选添加到 PATH重新运行安装包改一下选项即可。1.3 别装错环境这些工具用不到 JDK、Maven、Tomcat我在搜索这个主题时看到很多关联词是“JDK 安装”“Maven 安装”“Tomcat 安装”“Hadoop 安装”之类的。这里说清楚Claude Code 和 Codex CLI 本身是 Node.js 生态的工具它们不依赖 Java 环境。如果你只是使用这两个命令行 AI 助手不需要安装 JDK、Maven、Tomcat、HBase 这些。除非你让 AI 操作的项目本身就是一个 Java 后端项目而你在本地需要编译运行这个项目那才需要装 Java 相关环境。那 MySQL 呢同样不是这两个工具的必要依赖。AI 工具本身不操作数据库只有你的项目代码需要连数据库时才需要本地有对应的数据库环境。所以在安装阶段你只需要关注 Node.js、npm、Git 这三个东西就够了环境越简单后面排查问题越容易。另外如果你之前为了“节省空间”装过精简版 Node.js或者使用了一些绿色版、免安装版建议卸载掉换成官方安装包或系统包管理器管理的版本。这类非标准安装经常会漏掉 PATH 环境变量或者缺少必要的系统组件安装 Claude Code 和 Codex 时特别容易出幺蛾子。2. 安装 Claude Code官方 CLI 与登录细节2.1 用 npm 全局安装附镜像源配置Claude Code 的官方 npm 包名是anthropic-ai/claude-code。安装命令非常简单npm install -g anthropic-ai/claude-code安装完成后验证claude --version如果能看到类似 1.x.x 的版本号说明安装成功。像我平时升级也是用同一套命令npm update -g anthropic-ai/claude-code这里说一个很常见的坑如果你所在的网络环境访问 npm 官方仓库比较慢安装过程会长时间停在download状态或者直接超时报错。这时候可以把 npm 包下载源切换到国内常用的镜像站比如 npmmirrornpm config set registry https://registry.npmmirror.com改完之后再执行安装命令下载速度通常会明显改善。这个命令改的是 npm 的包仓库地址不是其他任何服务的配置可以放心使用。如果之后想切回官方源执行npm config set registry https://registry.npmjs.org/也可以先看一下当前使用的源npm config get registry我相信很多读者看到“镜像源”三个字会联想到其他东西但这里要明确npm 镜像源只是解决包下载速度和可用性的问题它不涉及任何敏感操作。你只需要把它理解成一个“更近的软件仓库”即可。2.2 登录与鉴权账号登录和 API Key 两种方式安装完成后在终端里直接输入claude就会进入首次启动流程。对于使用 Claude 账号的用户CLI 会在终端里显示一个授权链接并且自动尝试打开浏览器。你在浏览器里登录自己的 Claude 账号并确认授权终端里的 CLI 就会自动完成登录。我建议第一次使用选择账号登录因为这种方式不需要手动管理密钥后续使用最省事。登录成功后你会直接进入 Claude Code 的交互界面光标停在输入框里可以直接开始提问。如果你使用的是 Anthropic API 按量付费或者你希望把密钥交给 CI 环境使用那就用 API Key 方式。在终端里设置环境变量export ANTHROPIC_API_KEY你的API Key设置完成后再运行claudeCLI 会优先读取ANTHROPIC_API_KEY跳过浏览器授权流程。Windows 的 PowerShell 下设置方式略有不同$env:ANTHROPIC_API_KEY你的API Key claude这里提醒一句API Key 属于敏感凭据不要直接写死在项目代码里也不要在网上随便发。我习惯把这类密钥放在系统环境变量里而不是每次手敲。如果你在.bashrc或.zshrc里导出环境变量记得给配置文件设置好权限或者至少不要让文件内容公开。2.3 在 VS Code 里使用 Claude Code很多人喜欢在 VS Code 里用 AI 编程助手我有几台电脑也装了 VS Code实际用下来Claude Code 在 VS Code 里最顺的方式就是在集成终端里调用。操作流程打开 VS Code打开你的项目文件夹然后用快捷键调出终端Windows 是 CtrlmacOS 是 Control在终端里输入claude回车。Claude Code 会自动把当前目录当作项目根目录读取项目里的配置文件然后你就可以在终端里和它对话。为什么不建议额外折腾图形插件我的体会是Claude Code 本来就是一个面向终端交互的工具它会在终端里渲染富文本、操作提示、工具调用结果等。如果你再用一层图形界面包装中间多了一次转译遇到界面卡顿、输出不全、快捷键冲突的概率反而更高。当然如果你是第一次接触找个现成的项目用 VS Code 打开然后切到集成终端跑claude这是最接近官方推荐的上手方式。后续无论你写前端、后端还是脚本CLI 的工作状态都能保持得很稳定。2.4 Skills 安装与项目记忆文件Claude Code 支持 Skills 机制。简单说Skills 就是一组 markdown 说明和脚本告诉 Claude Code 在特定场景下应该按照什么方式工作。很多社区项目把 Skills 仓库发布在 GitHub 上你在本地安装后Claude Code 会在合适的场景自动参考这些技能说明。普通的安装方式就是把仓库克隆到本机对应的 skills 目录。比如git clone https://github.com/某个/技能仓库.git ~/.claude/skills/技能名不同版本对 skills 目录的位置要求略有差异我的建议是以官方文档为准常见的位置有~/.claude/skills/和项目内的.claude/skills/。另外Claude Code 还支持项目记忆文件。你可以在项目根目录创建一个CLAUDE.md把项目的技术栈、目录结构、常用命令、代码规范写进去。Claude Code 每次在这个项目里启动时会自动读取这个文件作为上下文的一部分。这个机制非常实用我后面会专门讲配置优化的部分。不要看到“Skills”就下载一堆第三方技能包我见过有人装了几十个 Skills结果 AI 回答问题时被互相矛盾的规则干扰。我的原则是先少装按需加出问题先检查是不是 Skills 导致的。3. 安装 Codex CLIOpenAI 的命令行助手3.1 安装命令和版本检查Codex CLI 官方 npm 包名是openai/codex。安装命令npm install -g openai/codex安装完成之后不要急着运行先确认一下版本codex --version如果你安装的是较老版本后续想升级执行npm update -g openai/codex如果一切正常接下来就是登录。3.2 登录方式ChatGPT 账号或 API KeyCodex 的登录方式与 Claude Code 类似也是两种可选项。第一种是使用 ChatGPT 账号登录终端里执行codex login命令会输出一个授权链接并在浏览器中打开 ChatGPT 登录页。你登录账号并确认授权后Codex CLI 会保存一份登录凭据之后codex命令就能直接使用。第二种是使用 API Key。把密钥放进环境变量export OPENAI_API_KEY你的OpenAI API KeyWindows PowerShell$env:OPENAI_API_KEY你的OpenAI API Key codexCodex 启动时会读取OPENAI_API_KEY有 Key 就直接使用没有 Key 才会要求走账号登录。这个优先级关系记住之后排查登录问题会轻松很多。这里有个实际经验如果你同时设置了OPENAI_API_KEY环境变量又执行过codex login那么 Codex 通常会优先使用环境变量里的 Key。所以你发现登录之后没生效先去检查环境变量里是不是残留了一个旧的 Key。3.3 接入 DeepSeek 等兼容服务Codex CLI 一个很实用的特性是支持自定义模型服务商。官方底层接口与 OpenAI 兼容所以像 DeepSeek 这类提供兼容接口的服务商可以通过配置文件接入。在用户目录下创建.codex配置目录和config.toml文件mkdir -p ~/.codex然后编辑~/.codex/config.toml写入类似下面的内容model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY保存后设置 DeepSeek 的 API Key 环境变量export DEEPSEEK_API_KEY你的DeepSeek Key然后在终端里运行codex它就会通过 DeepSeek 的接口地址来处理请求。这里有几个容易踩坑的地方。一是base_url的路径到底要不要带/v1主要取决于服务商的兼容实现。DeepSeek 官方文档提供的是带/v1的地址所以我建议先用这个地址如果请求报 404 或者路径错误再去服务商文档里核对一遍。二是模型名要写对。deepseek-chat是 DeepSeek 的通用模型名但不同阶段官方可能有新的模型命名以最新的文档为准。三是注意区分 Codex 和 Claude Code 的接入逻辑。Codex 的这套自定义服务商配置是它的特性Claude Code 用的是一套完全不同的协议。不要把 Codex 的配置搬到 Claude Code 上也不要指望 Claude Code 直接接 DeepSeek 这类 OpenAI 兼容服务。3.4 基本使用姿势Codex 安装登录完成后直接在项目目录里输入codex会进入交互式界面。你可以像聊天一样问它问题也可以让它分析当前目录下的代码、生成文件、修改代码。除了交互模式它还有一次性执行模式。比如你只想知道“这个项目里有哪些 TODO”可以直接codex exec 列出项目里所有 TODO这种模式适合在脚本、CI 或者自动化流程里使用。如果你想快速了解命令全部参数执行codex --help第一次用 Codex 时我建议在一个空目录或者小项目里测试不要一上来就让它处理巨型代码库。因为模型一次能塞入的上下文有限项目内容太多时它可能只能看到部分文件回答质量会明显下降。我自己用下来的习惯是每次只给它一个明确的小目标比如“修复 src/utils/date.ts 里的时区问题”而不是“帮我把这个项目搞好”。4. 配置优化让两个工具更好用4.1 设置终端别名提高日常调起效率Claude Code 的命令是claudeCodex 的命令是codex连续敲多了确实有点累。我习惯在终端配置文件里加个别名把命令缩短。如果你用的是 zsh 或 bash在~/.zshrc或~/.bashrc里加alias ccclaude alias cxcodex保存后刷新配置source ~/.zshrcWindows PowerShell 用户可以在 PowerShell 配置文件里定义函数function cc { claude args } function cx { codex args }以后想启动哪个工具直接敲cc或cx就行。注意cc这个别名和 C 语言编译器命令cc有冲突如果你是在搞 C 开发的机器上就别抢这个别名了换成cl或者cdx更稳妥。4.2 项目级说明文件让 AI 更快理解项目这是我觉得最值得花时间的配置没有之一。Claude Code 和 Codex 各自支持一种项目级说明文件Claude Code 读的是CLAUDE.mdCodex 读的是AGENTS.md。这两个文件都放在项目根目录下AI 工具启动时会把文件内容自动纳入上下文。以 Claude Code 为例一个典型的CLAUDE.md可以写# 项目说明 ## 技术栈 - 前端Vue3 TypeScript Vite - 后端Node.js Express ## 常用命令 - 启动开发npm run dev - 运行测试npm test ## 代码规范 - 使用 TypeScript 严格模式 - 组件文件使用 PascalCase这样 AI 在回答问题时就不再是凭空猜测你的项目结构而是基于这些信息做判断。Codex 的AGENTS.md用法类似。我通常在项目初始化阶段花十分钟写这份文件之后每次让 AI 改代码它的输出都会更贴合项目实际。别小看这个文件。很多人抱怨“AI 写的代码根本不能用”其实很多时候不是模型不行而是你没有给它足够的项目上下文。一份好的项目说明比堆十个插件都管用。4.3 模型选择与成本控制Claude Code 和 Codex 默认可能会使用比较强的模型效果好但成本也会高。如果你用的是订阅制账号可能没有太多成本压力如果用的是 API 按量付费就要小心了。Claude Code 交互界面里提供了一些内置命令比如查看当前状态、查看成本、压缩上下文。我习惯每工作一段时间就用/status或/cost看一眼消耗。Codex 也支持通过配置选择模型。在~/.codex/config.toml里你可以把model改成当前服务商提供的小模型或低成本模型然后再实际跑一轮任务看效果。控制成本还有一个很实用的方法每次只让 AI 处理一个小任务不要让它在一次对话里无限干下去。任务范围太大上下文变长消耗也会成倍增加。如果你发现同一件事来回改了好几轮还没结束不如先停下来手动把代码看一遍理清思路再重新提问这样反而更省钱。4.4 和 Git 工作流结合要让这两个 CLI 在真实项目里发挥价值一定要和 Git 工作流结合起来。我自己的流程是这样的先在项目里开一个新分支比如feature/ai-refactor然后启动 Claude Code 或 Codex 让它在当前分支上修改代码。修改完成后我不会直接让它 commit而是先用git diff仔细看一遍改动。git diff确认改动合理之后再手动提交git add . git commit -m refactor: 调整日期工具函数的时区处理让 AI 直接 commit 不是不行但很容易把无关的改动也混进来尤其是它可能顺手格式化了你没打算改的文件。所以我的原则是AI 可以写代码但提交权必须留给自己。你始终要记住AI 是协作工具不是决策工具。代码改动最终合不合并需要你对项目负责。5. 常见问题与排查实录5.1 安装超时或卡在下载进度条npm 安装时最常见的问题就是卡在 download 阶段。如果你等了很久还是没动静先确认一下源npm config get registry如果输出的是官方地址而你的网络访问官方源较慢可以切换到 npmmirror 源npm config set registry https://registry.npmmirror.com切换之后再安装一次。如果还是卡住可能是 npm 缓存有问题可以清理缓存后重试npm cache clean --force我遇到过几次看似是网络问题实际是上次安装失败留下的缓存把过程卡死了清理缓存后问题就消失了。5.2 安装成功但 command not found这种情况非常典型npm 显示added 1 package但输入claude或codex就是找不到命令。原因通常是 npm 的全局 bin 目录没有加到系统 PATH 里。先查一下全局 bin 路径npm prefix -g比如输出/usr/local那么可执行文件一般就在/usr/local/bin把这个目录加到 PATH 环境变量里就能解决。Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm一样的思路。另一个常见原因是终端没有刷新。装完包后关掉当前终端窗口重新打开一个再试一次。有些环境变量和 PATH 配置只在新的终端进程里才会加载。5.3 启动时提示所在地区不可用如果你在启动 Claude Code 时看到类似 “might not be available in your country” 的提示说明当前运行环境或账号所属区域不在官方支持范围内。遇到这种情况正确做法是去官网查看支持的国家和地区列表确认自己的账号是否满足条件并通过官方渠道解决问题。不要为了绕过限制去下载来路不明的第三方启动器、汉化包或“一键脚本”。这类工具往往会修改 CLI 的配置文件甚至可能藏有窃取密钥的恶意代码。我看到很多技术社区都有“中文启动器”的讨论但这类包装工具的安全性是没法保证的与其省一点事不如老老实实用官方 CLI。排名特别靠前的关键词里出现过“claude code 中文启动器”“codex 汉化”之类的内容我的建议是尽量不要使用。你不需要一个“汉化版”才能学会这几个命令多敲几次就熟了。5.4 Codex 一直显示正在重新连接Codex 在运行过程中如果长时间显示“正在重新连接”大概率是网络连接不稳定或后端服务响应超时。可以先按CtrlC退出当前会话然后检查网络是否正常再重新运行codex。如果你配置的是第三方兼容服务比如 DeepSeek那么这个问题还可能是接口地址有误、模型名不存在、API Key 过期等原因导致的。逐一排查顺序是先看环境变量是否设置正确再确认config.toml里的base_url和model是否和服务商文档一致最后看当前时间是否真的能访问到服务商接口。如果反复重连可以考虑降低一次任务的复杂度。有些时候是任务本身太重后端处理时间过长客户端误以为连接断了。把任务拆小之后重连现象会少很多。5.5 切换配置工具时出现服务异常我注意到不少人在用 cc-switch 这类社区切换工具时会出现一条很长的报错内容是“在切换 Codex 服务时本地组件请求 /responses 路径失败”之类的提示。这里的核心问题通常是切换工具负责修改 Claude Code 或 Codex 的本地配置但如果它的后台服务没有正常启动或者版本和 CLI 版本不匹配就会在切换过程中报各种奇怪错误。我的处理方式很简单遇到这种报错先彻底退出切换工具然后在终端里手动确认配置文件内容是否正确。如果你只是想在 Claude Code 和 Codex 之间切换完全可以通过环境变量或者各自配置文件直接实现不一定要依赖第三方的可视化切换工具。这类工具本身的问题不大但一旦出问题排查成本会高于它省下的那点操作成本。所以我的建议是优先用官方提供的环境变量和配置文件方式第三方工具只在你完全了解其原理的情况下作为辅助。5.6 Windows 上安装 Codex 始终显示未完成Windows 用户安装 Codex 时有时候会遇到“安装未完成”或进程长时间停在某个步骤的情况。最常见的原因有三个一是 npm 下载包时网络中断二是安全软件拦截了 npm 的脚本执行三是终端权限不够导致写入失败。针对这三个原因可以依次尝试npm cache clean --force npm install -g openai/codex --force如果还是不行用管理员身份重新打开 PowerShell再执行一次安装。如果安全软件有拦截日志放行 npm 相关进程后重试。装完之后记得关闭并重新打开终端确认codex --version能正常输出版本号。还有一些 Windows 用户是因为之前手动安装过旧版本残留文件和新版本冲突。这时候先卸载旧版本再清理 npm 缓存最后重新安装。不要在同一台机器上反复覆盖安装不同来源的包。5.7 卸载与重装如果你实在折腾不出来或者想从测试环境换到正式环境最干净的办法是彻底卸载重装。卸载 Claude Codenpm uninstall -g anthropic-ai/claude-code卸载 Codexnpm uninstall -g openai/codex如果想要更彻底还需要手动删除本地的配置目录。Claude Code 的配置主要在~/.claudeCodex 的配置在~/.codex。删除前建议先备份里面你需要保留的配置内容比如 API Key、自定义的CLAUDE.md或config.toml。rm -rf ~/.claude rm -rf ~/.codexWindows 上对应目录一般在用户主目录下路径类似C:\Users\你的用户名\.claude。删完以后重新安装基本就能得到一个干净环境。最后分享一个小技巧这类命令行 AI 工具其实不需要“全家桶式”安装。很多问题是因为环境里同时存在多个版本、多个配置文件、多个切换工具。只要保持 Node.js 是 LTS、npm 源清晰、配置目录干净这两个工具通常装起来很顺利。我自己后来重装系统后半小时就能把 Claude Code 和 Codex 全部配好。你不需要每个冷门功能都配一遍先把这个最小闭环跑通后面再一步步加自己需要的功能这才是最不容易受伤的上手路径。