Vibe Coding 是最近两年被反复讨论的开发方式：你不再逐行手写全部代码，而是用自然语言描述需求，由 AI 工具生成实现，自己把精力放在确认方向、审查差异和修复边界上。真正要把这套流程落地，绕不开 Codex、Claude Code、Cursor 这三个工具。下面直接按实际项目中使用它们的顺序，整理一份可以从零照做的完整教程，包含安装、配置、运行、验证和常见报错排查。
1. 先理解 Vibe Coding，再决定用哪个工具
1.1 从“意图编程”到 AI 辅助开发的工作方式
Vibe Coding 的核心不是“完全不用写代码”，而是把工作重心从“逐行实现”转移到“描述意图、检查产出、修正边界”。你在编辑器或终端里输入一句自然语言，例如“为这个 Python 项目补充命令行参数解析并添加单元测试”，AI Agent 会读取项目结构、生成代码、执行命令，再把结果展示出来。
这种方式能够提高效率，原因在于大模型已经具备较强的代码生成能力，而 Agent 类工具能进一步调用文件读写、终端命令、代码搜索等能力，把“只生成一段代码”扩展成“完成一个开发任务”。但这并不代表可以完全脱离工程能力。你仍然需要理解项目结构、判断生成结果是否正确、处理边界条件，以及在出错时定位问题。
真正适合 Vibe Coding 的场景包括：快速搭建原型、给旧项目补测试、批量重构、解释陌生代码库、生成数据迁移脚本等。不适合的场景则包括：对稳定性要求极高的底层系统、没有测试保护的遗留代码、需要严格合规审计的业务逻辑等。
1.2 为什么 Codex、Claude Code、Cursor 会成为主力工具
这三类工具正好覆盖了 Vibe Coding 的三种形态。
Cursor 是集成在编辑器里的 AI 编程助手，适合日常写代码、改需求、代码补全和对话式修改。它的价值在于“人在编辑器中，AI 在编辑器旁”，交互最短。
Claude Code 是运行在终端里的 Agent 工具，擅长理解整个代码库、跨文件分析、执行重构和批量修改。它更像一个“能读懂项目的技术伙伴”，适合做代码库级别的任务。
Codex CLI 是 OpenAI 推出的命令行 Agent，能够接收文本任务，在本地仓库中读取文件、生成修改、执行命令，适合脚本化、批量化和可重复的自动化开发任务。
在实际项目中，三者不是非此即彼的关系。很多人先用 Cursor 做即时补全，遇到跨文件改动时切到 Claude Code，需要批量处理时再用 Codex CLI。
1.3 三个工具对比：定位、上手难度和使用场景
| 工具 | 形态 | 核心能力 | 适合场景 | 主要门槛 |
|---|---|---|---|---|
| Cursor | 桌面编辑器 | 代码补全、Chat、多文件 Agent | 日常编码、改需求、阅读代码 | 账户额度、模型选择、配置同步 |
| Claude Code | 终端 CLI | 长上下文代码库理解、重构、权限控制 | 大型项目分析、批量重构、代码审查 | Anthropic 账号、权限配置、CLI 环境 |
| Codex CLI | 终端 CLI | 命令行执行、多文件修改、沙箱执行任务 | 自动化批量修改、脚本化开发流程 | 登录认证、CLI 路径配置、模型 API 配置 |
选型时不要只看工具热度，要看你手头的任务类型。如果你只想在编辑器里快速生成一段函数，Cursor 是最高效的；如果要做一次“全仓变量重命名并同步修改测试”，Claude Code 或 Codex CLI 更合适。
2. 安装前先把基础环境补齐：Node.js、CLI 与运行路径
2.1 Vibe Coding 工具依赖哪些本地环境
在安装 Codex CLI 和 Claude Code 之前，先确认本机环境。这两个工具本质上是 Node.js 命令行程序，Cursor 虽然是桌面应用，但在使用部分 AI Agent 功能或集成外部 CLI 时，也会依赖本地命令。
基础环境通常包括：
| 依赖项 | 常见要求 | 用途 |
|---|---|---|
| Node.js | 18+ 或 20+，以工具官方要求为准 | 运行 npm 全局 CLI 工具 |
| npm | 随 Node.js 安装 | 安装、更新 Codex CLI 和 Claude Code |
| Git | 2.x 以上 | 版本管理、查看 diff、回滚 AI 改动 |
| 终端 | Windows Terminal、iTerm2、GNOME Terminal 等 | 运行交互式 Agent |
| 账号或 API Key | OpenAI / Anthropic / 第三方兼容服务 | 模型调用认证 |
建议在干净的开发机上先把这些依赖装好，再开始安装 AI 工具，避免后面遇到“CLI 命令不存在”“npm 全局路径找不到”“登录后无法调用模型”等连锁问题。
2.2 先检查 Node.js 和 npm 是否可用
打开终端，执行以下命令：
node -v npm -v如果 Node.js 未安装，建议通过官方安装包或 nvm 安装。不要直接用系统自带的过旧版本，很多 Agent 工具要求 Node.js 18 以上，版本过低会在启动阶段直接报错。
nvm 方式在 macOS 和 Linux 下比较常用：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20Windows 上可以使用 nvm-windows 或官方安装包。这里要注意：安装完成后必须新开一个终端窗口，否则 PATH 环境变量不会刷新，node和npm可能仍然无法识别。
2.3 npm 全局安装路径与 PATH 问题
Codex CLI 和 Claude Code 都通过npm install -g安装到全局目录。为什么安装成功后，输入codex或claude仍然提示“不是内部或外部命令”？原因通常是 npm 全局 bin 目录没有加入系统 PATH。
查看 npm 的全局安装目录：
npm config get prefix在 Windows 上，全局 bin 目录通常是%APPDATA%\npm；在 macOS 和 Linux 上，取决于 Node.js 是否通过 nvm 安装，常见路径是/usr/local/bin或~/.nvm/versions/node/<当前版本>/bin。
确认目录后，把对应的 bin 路径加入 PATH。Windows 用户可以在系统环境变量中追加%APPDATA%\npm，保存后重开终端。macOS 和 Linux 用户可以在 shell 配置文件中添加：
export PATH="$(npm config get prefix)/bin:$PATH"注意：安装完 CLI 工具后，如果仍然提示“无法识别命令”，不要急着重装，先检查 PATH 是否包含 npm 全局 bin 目录，并且终端是否已重启。
2.4 验证 CLI 是否可执行
环境准备完成后，执行版本命令验证：
codex --version claude --version如果命令能正常输出版本号，说明 CLI 安装成功。这一步很关键，因为后面很多报错，比如“unable to locate the codex cli binary”，本质上是宿主应用找不到 CLI 路径，而不是模型本身的问题。
3. Codex CLI：从安装到跑通第一个 Agent 任务
3.1 安装 Codex CLI
Codex CLI 可以通过 npm 全局安装：
npm install -g @openai/codex安装完成后，执行：
codex --version确认版本号正常后，进行登录认证。Codex CLI 通常支持通过浏览器登录获取会话，也可以配置 API Key 环境变量。示例：
codex login登录完成后，可以运行一个最简单的任务：
codex "列出当前目录下所有包含 TODO 的文件"如果 Codex 能读取目录结构并返回结果，说明安装和认证链路已经打通。
3.2 理解 Codex 的工作方式与常用参数
Codex CLI 的执行流程大致是：接收自然语言任务 -> 读取仓库结构和文件内容 -> 调用模型生成修改方案 -> 在当前分支上执行文件修改和命令 -> 返回结果。这种工作方式适合自动化程度高、可在命令行中复现的任务。
常用参数通常包括：
| 参数 | 作用 | 建议 |
|---|---|---|
--help | 查看命令帮助 | 版本升级后先看帮助 |
--version | 查看版本 | 检查安装是否成功 |
--debug | 输出调试日志 | 网络或配置异常时使用 |
| 提示词字符串 | 描述要执行的任务 | 写清楚任务边界和输出要求 |
具体参数名会随版本调整，落地前先执行codex --help确认。
3.3 配置第三方模型服务：以 DeepSeek 为例
Codex CLI 的模型服务地址默认指向 OpenAI 接口。如果希望接入其他兼容 OpenAI 接口格式的服务，比如 DeepSeek，可以通过配置文件或环境变量指定 Base URL 和 API Key。
社区常见的config.toml配置思路如下，具体文件路径和字段以当前版本官方文档为准：
model = "deepseek-chat" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY"配置完成后，在执行 Codex 之前设置环境变量：
export DEEPSEEK_API_KEY="你的密钥"然后运行：
codex "为项目添加一个读取配置文件的模块"这里要理解几个概念：
model：使用的模型名称，需要服务商支持。base_url：模型服务的请求地址，必须是服务商提供的兼容接口地址。env_key：API Key 从哪个环境变量读取，避免把密钥写进配置文件。
如果你的服务商只提供原生接口，不兼容 OpenAI 协议，那么 Codex CLI 可能无法直接接入，需要先经过一层协议转换服务，再交给 Codex。
3.4 Codex 常见报错和处理方式
Codex 在使用中最容易遇到两类问题：命令找不到、网络请求失败。
“unable to locate the codex cli binary” 是一个典型报错，常见于某个 AI 客户端或编辑器集成了 Codex 引擎时。报错含义是宿主程序尝试启动 Codex CLI，但找不到可执行文件。排查顺序：
- 在终端执行
codex --version，确认 CLI 已安装。 - 确认 npm 全局 bin 已加入 PATH。
- 在宿主工具的设置中配置 Codex CLI 路径，例如环境变量
CODEX_CLI_PATH或软件内的codex cli path配置项。 - 配置完成后重启宿主应用。
另一类报错与模型请求接口有关，例如请求/responses接口失败。排查时先检查 Base URL 是否正确、当前网络能否访问目标 API 域名、API Key 是否有效。可以执行：
codex --debug "写一个读取文件的小程序"这样能输出更多请求信息，便于定位是哪一层失败。
4. Claude Code：用对话式 Agent 处理整个代码库
4.1 安装与登录 Claude Code
Claude Code 是 Anthropic 推出的终端 Agent 工具，安装方式同样是 npm 全局安装：
npm install -g @anthropic-ai/claude-code验证安装：
claude --version启动交互式对话：
claude登录方式有两种：一种是执行claude login并通过浏览器认证；另一种是设置环境变量ANTHROPIC_API_KEY。在团队环境中，更推荐用环境变量注入密钥，避免把账号信息写进项目文件。
4.2 常用命令和交互方式
Claude Code 启动后是交互式会话，你可以输入自然语言任务，也可以使用斜杠命令管理会话。
常用斜杠命令：
| 命令 | 作用 |
|---|---|
/status | 查看当前会话状态、上下文容量 |
/clear | 清空上下文历史 |
/permissions | 查看和管理工具执行权限 |
/help | 查看帮助 |
在会话中，示例交互：
请分析 src/ 目录下哪些函数缺少类型注解，并生成一个补全计划。Claude Code 会读取项目结构、定位文件、分析代码，然后给出修改建议。你确认后，它会继续执行文件修改。
4.3 如何减少“一直点确认”的权限打扰
Claude Code 为了保证安全性，默认在执行文件写入、终端命令等操作前需要用户确认。很多新手会觉得很繁琐，于是想关闭确认。
不推荐直接使用类似--dangerously-skip-permissions的参数，因为这意味着 AI 生成的所有命令都会直接执行，一旦提示词被误导或注入恶意内容，风险很高。
更好的做法是配置白名单。通过/permissions管理权限，允许特定命令或工具免确认，同时保留危险操作的人工确认。也可以使用claude的权限配置文件，把高频、低危命令加入允许列表。
注意：不要为了“方便”而全局关闭权限确认。在可信任的开发环境之外，尤其是涉及生产服务器、数据库、部署命令时，必须保留确认步骤。
4.4 接入兼容 API 或 DeepSeek 等模型
如果服务商提供 Anthropic 兼容接口，可以通过环境变量切换 Claude Code 的后端模型。社区常见的配置方式如下：
export ANTHROPIC_BASE_URL="https://api.example.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的密钥" export ANTHROPIC_MODEL="deepseek-chat"设置完成后启动：
claude这里要强调：ANTHROPIC_BASE_URL必须指向服务商真实提供的 Anthropic 兼容地址。如果服务商不支持该协议，需要先通过合规的接口转换方案接入。
4.5 Windows 安装和运行时常见报错
Claude Code 在 Windows 上安装时，可能出现两类典型问题。
一是“此程序或功能与 64 位版本的 Windows 不兼容”这类提示。常见原因是下载到了过期版本，或者系统组件缺失。处理方式：从官方渠道获取最新版本安装包，确认 Windows 系统已更新到受支持版本，然后以管理员身份重新安装。
二是“missing hcs services: hns, vmcompute, vfpext”这类提示。这通常不是 Claude Code 本身的 bug，而是 Windows 缺少 Hyper-V、容器或虚拟化相关服务。以管理员身份打开 PowerShell，执行：
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All Enable-WindowsOptionalFeature -Online -FeatureName Containers执行后重启系统。该操作会修改 Windows 功能，仅建议在开发机上操作，并提前保存工作。
5. Cursor：把 AI 能力无缝集成进编辑器
5.1 下载、安装与登录 Cursor
Cursor 是桌面编辑器，安装方式相对简单。从官网下载对应操作系统的安装包，安装完成后打开，使用邮箱或第三方账号登录。免费版有使用次数限制，额度用完后会提示等待恢复或升级付费计划。额度政策会随产品调整，以官网实时说明为准。
登录后，建议先确认自己的项目目录，再开始使用 AI 功能。
5.2 设置中文界面：命令面板切换语言
Cursor 默认可能是英文界面。设置中文的步骤：
- 打开命令面板：Windows/Linux 按
Ctrl+Shift+P，macOS 按Cmd+Shift+P。 - 输入
Configure Display Language。 - 如果没有中文包，选择
Install additional languages，在扩展列表里搜索Chinese并安装。 - 安装后选择
Chinese，重启 Cursor。
如果重启后仍然显示英文，检查系统语言包是否安装完成，或再次打开命令面板重新选择语言。这个现象常见于语言包安装后没有完整重启。
5.3 Cursor 的三个核心功能：Tab、Chat、Composer/Agent
Cursor 的核心能力可以分成三层。
Tab 补全：当光标停在某一行时，Cursor 会根据上下文预测接下来的代码，按Tab接受建议。适合写样板代码、重复结构、单元测试模板。
Chat 对话：选中代码后通过快捷键唤起对话窗口，可以提问、要求解释、请求修改建议。适合阅读代码、排查逻辑问题、生成小范围改动。常用快捷键是Ctrl+L或Cmd+L。
Composer / Agent：可以同时修改多个文件，并尝试执行终端命令。适合跨文件重构、添加功能模块、补齐测试。常用快捷键是Ctrl+I或Cmd+I。使用 Agent 前，建议先用 Git 创建分支并提交一次 baseline，这样即使 AI 改乱了也能回滚。
5.4 Cursor 如何连接外部 CLI 工具
有些版本或插件允许在 Cursor 内使用 Codex CLI 作为执行引擎。如果遇到 “unable to locate the codex cli binary” 报错，说明 Cursor 找不到 Codex CLI 的可执行文件。
处理方式：
- 确认
codex --version能正常输出。 - 在系统环境变量中增加 npm 全局 bin 路径。
- 在 Cursor 设置中填写 Codex CLI 的绝对路径，或设置
CODEX_CLI_PATH环境变量。 - 重启 Cursor。
如果使用第三方兼容模型，同样需要配置 Base URL 和 API Key，不要让密钥硬编码在项目文件里。
6. 用一套工作流把三个工具组合起来
6.1 典型 Vibe Coding 项目流程
单独使用某个工具只能覆盖开发环节的一部分。更完整的流程是让三者协作。
一个可参考的工作流：
- 在 Cursor 中打开项目，使用 Chat 让 AI 阅读 README、理解项目背景。
- 用 Claude Code 分析代码库，列出当前任务涉及的文件和影响面。
- 用 Codex CLI 执行批量修改，例如统一命名规范、生成测试文件。
- 通过
git diff审查所有改动，检查 AI 是否修改了无关文件。 - 运行测试和构建命令，验证功能是否正常。
- 让 AI 生成提交说明，再由人工确认后提交。
这套流程的核心是：AI 负责生成和修改，人工负责决策和验证。
6.2 任务类型与工具选择
| 任务类型 | 推荐工具 | 原因 |
|---|---|---|
| 补全一段代码、写单测 | Cursor | 交互路径短，适合即时修改 |
| 读懂整个项目结构 | Claude Code | 长上下文和代码库分析能力强 |
| 批量替换、执行脚本 | Codex CLI | 命令行自动化和脚本化体验好 |
| 多文件重构并同步改测试 | Claude Code 或 Codex CLI | Agent 能跨文件修改并执行验证 |
| 查看 AI 修改了哪些内容 | Git + 任意工具 | 版本管理是最可靠的审查手段 |
这里没有“唯一正确答案”。团队可以根据项目语言、代码库大小、模型成本选择组合方式。
6.3 如何管理 AI 生成代码的质量
Vibe Coding 最容易翻车的地方，不是 AI 生成了错误代码，而是开发者没有检查就直接合并。
质量管理的底线规则：
- AI 每次大改动前，先创建分支或提交一次 baseline。
- 审查
git diff，逐文件确认改动范围。 - 对生成代码运行测试，不要只看“编译通过”。
- 检查是否存在硬编码密钥、危险命令、路径穿越、SQL 拼接等问题。
- 对 AI 生成的依赖变更保持怀疑，确认版本来源。
提醒：AI 工具最擅长生成“看起来正确”的代码，真正要靠的是你的 review 和验证流程。
7. 常见问题排查：从现象到结论
7.1 安装类问题排查表
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
codex或claude不是内部或外部命令 | npm 全局 bin 未加入 PATH | 执行npm config get prefix | 将 bin 目录加入 PATH，重开终端 |
| unable to locate the codex cli binary | 宿主应用找不到 Codex CLI | 执行codex --version | 安装 CLI，配置CODEX_CLI_PATH或应用内路径 |
| 安装 Claude Code 后无法启动 | Node.js 版本过低或系统组件缺失 | 执行node -v | 升级 Node.js，更新系统组件 |
| Windows 报“64 位版本不兼容” | 安装包或系统组件不匹配 | 查看系统版本和安装来源 | 从官方下载最新版，更新系统后重装 |
| missing hcs services: hns, vmcompute, vfpext | Windows 虚拟化/容器服务未启用 | 以管理员 PowerShell 执行服务检查 | 启用 Hyper-V 和 Containers 功能后重启 |
| Cursor 设置中文不生效 | 语言包未安装或未重启 | 重新打开命令面板 | 安装中文语言包并完整重启 |
7.2 网络与认证类问题排查
网络和认证问题是 AI 工具使用中比较隐蔽的一类。现象通常是：工具能启动，但发消息后长时间无响应，或直接报接口错误。
排查顺序：
- 确认 API Key 是否设置正确，环境变量是否在当前终端生效。
- 确认 Base URL 是否配置正确，是否指向服务商提供的真实地址。
- 确认当前网络是否能访问对应 API 域名。
- 查看调试日志：Codex 使用
--debug，Claude Code 查找 verbose 日志，Cursor 查看输出面板。 - 确认模型名称是否被服务商支持。
- 如果是本地内网服务，确认服务状态和端口是否正常。
7.3 一套通用的排查链路
遇到 Vibe Coding 工具问题，不要盲目重装，按顺序排查效率更高：
- 命令能否执行：版本号是否输出。
- 登录和密钥是否有效：能否认证成功。
- 模型配置是否正确：模型名、API 地址、Key 是否匹配。
- 工作目录是否选对：是否在 Git 仓库内、路径是否包含中文或空格。
- 日志是否有有效线索：优先看错误堆栈，而不是只看“失败”两个字。
- 网络与权限：域名连通性、端口、系统功能服务。
这条链路适合绝大多数 CLI Agent 和编辑器插件问题。
8. Vibe Coding 的最佳实践与后续学习建议
8.1 安全与权限管理
使用 AI 编程工具时，安全底线不能放松。API Key 和 Token 必须通过环境变量或密钥管理工具注入，不能写进项目代码、配置文件并提交到仓库。对 AI 生成的命令要执行最小权限原则，不推荐把--dangerously-skip-permissions作为日常参数使用。
在涉及数据库、部署、生产命令的场景，必须人工确认每一步。AI 工具可以帮忙生成命令，但“执行这条命令会造成什么影响”必须由开发者负责。
8.2 工程化与可维护性
Vibe Coding 不是“让 AI 乱改代码”，而是需要工程化约束。建议项目根目录维护一份 AI 规则说明，例如：
- 哪些目录不允许修改。
- 使用什么语言和风格。
- 测试必须通过后才能提交。
- 新增依赖前要说明理由。
AI 工具通常能读取这类说明文件，并在生成代码时参考。这样可以降低生成结果偏离项目规范的概率。
8.3 一条适合新手的练习路线
如果你刚接触 Vibe Coding，不建议直接拿生产项目做实验。可以从以下路线开始：
- 用 Cursor 改写一个自己写过的小项目，补全注释和单元测试。
- 用 Claude Code 分析一个开源项目，让它生成架构说明和函数调用关系。
- 用 Codex CLI 实现一个批量文件处理任务，例如批量重命名、批量添加日志。
- 把三个工具接入同一套 Git 工作流，对比谁更适合哪些任务。
- 尝试接入第三方兼容模型，理解 Base URL、API Key、模型名之间的关系。
每一步都需要验证结果：能跑通、能解释、能回滚，才算真正掌握。
8.4 一份可复用的环境检查清单
在开始一个 Vibe Coding 项目之前，可以对照以下清单确认环境：
- Node.js 版本满足工具要求。
- npm 全局 bin 目录已加入 PATH。
codex --version和claude --version能正常输出。- Git 仓库已初始化，当前分支已提交 baseline。
- API Key 已通过环境变量注入，未硬编码。
- 确认模型服务商支持对应协议和模型名。
- 已创建独立分支用于 AI 批量修改。
- 确认没有在生产目录中直接运行高风险命令。
把这份清单贴在常用开发环境里，能减少很多“装完跑不起来”的重复排查。Vibe Coding 本身并不复杂，复杂的是安装、权限、模型配置、代码审查这些工程细节。把基础打好，才能让 AI 工具真正成为日常开发的助力。
