1. 开工之前先弄懂 Codex 是什么再决定怎么装1.1 一句话认识 Codex终端里的编程搭档Codex 是 OpenAI 出品的命令行编程代理也是目前把“自然语言描述需求”直接落成代码操作做得最成熟的一批工具之一。它跟网页版聊天窗口最大的区别在于Codex 运行在你自己的电脑上能直接读写项目文件、执行终端命令、跑测试然后根据测试结果回头改代码。简单说它不是一个只会“给建议”的对话框而是一个愿意动手改文件的助理。正因为它是本地工具所以安装时要多花一点心思你要先把它的运行环境准备好再给它身份验证登录和 API Key最后才能让它干活。这也是很多小白卡住的原因——并不是 Codex 本身难装而是前面的 Git、Node.js、账号注册这些环节中总有一个地方没接上。这篇教程会从零开始把环境准备、codex 安装、账号注册与登录、首次运行再到常见报错排查讲清楚最后还会介绍怎么接入 DeepSeek 以及把交互改成中文。1.2 适用场景与第一课安全边界先说结论任何对命令行零基础但又想用 AI 写代码的人都可以按本文走一遍。学完之后你会掌握的不仅是 Codex还包括 Git、Node.js、环境变量这些基本功这些能力后续学别的东西也用得上。但我也要说清楚Codex 有权执行终端命令第一次使用请在一个空的练习目录里进行别一上来就拿公司项目或重要文件试。我见过有人让它自动清理“缓存目录”结果它扫掉了一堆不该删的上线文件。这类教训不是工具的问题而是使用习惯的问题。在正式开始前再确认一下你的电脑类型和操作习惯。Windows、macOS、Linux 都能装命令略有差异我会在代码块里分别标出。如果你平时连“环境变量”都没听过也不要紧看到哪里不懂就回到这一节看一遍前 20 分钟打好基础后面才能顺。2. 前置环境先把 Git、Node.js、Python 安排明白2.1 Git 安装三个系统各说一遍我不建议跳过这一步因为很多教程只讲装 Codex不讲 Git结果用户跑着跑着就会遇到 git 相关报错。Codex 本身安装不强制依赖 Git但它经常用 Git 来显示改动diff、帮你提交代码、管理版本。如果没有 GitCodex 的很多体验会大打折扣。Windows去 Git 官方网站下载 Windows 版本的安装包双击后一路 Next。唯一要注意的是在选择默认编辑器那一步我建议选 Visual Studio Code不要选 Vim否则以后操作会有学习成本。安装完成后打开 PowerShell 输入git --version看到类似git version 2.4x.x就说明装好了。macOS如果你已经安装过 Xcode Command Line Tools自带 Git否则最省事的方式是用 Homebrew 执行brew install git然后同样用git --version验证。LinuxDebian/Ubuntu执行sudo apt update sudo apt install git -y。Fedora 系用sudo dnf install git -y。装完验证版本。2.2 Git 基础配置不配置会直接报错很多人以为装完 Git 就完事了其实还差两步。在终端里依次执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条命令是告诉 Git“你是谁”。不设置的话第一次用 Codex 帮你初始化仓库或提交代码时Git 会直接报错常见的提示是Please tell me who you are。新手看到这种报错会懵其实它就是在问你的身份信息。邮箱不一定要真实常用但建议填一个你记得住的因为以后提交记录上会显示它。2.3 Node.js 与 npmCodex 的主要安装通道Codex 通过 npm 包管理器分发所以 Node.js 环境是躲不开的。这句话翻译成人话就是你想用npm install装 Codex就得先把 Node.js 装好。Node.js 是一个让 JavaScript 能跑在电脑上的运行时npm 是它的“软件商店”。Windows/macOS直接去 Node.js 官方网站下载 LTS 版本。LTS 全称是“长期支持版”不会频繁变更新适合大多数普通用户。安装时 Windows 用户记得勾选默认选项即可macOS 用户也用官网安装包一路下一步。装完以后重新打开一个终端窗口输入node -v和npm -v。能看到v20.x或v22.x这样的输出就说明环境通了。如果你的电脑里已经装过老版本 Node比如v16或更低请先升级。Codex 对运行环境有一定版本要求版本太旧会出现各种莫名其妙的报错。2.4 Python 环境先装好用不用另说严格来说Codex 不依赖 Python。但装了有两个好处一是你让它写脚本时可以直接在本机运行验证二是很多项目模板和自动测试脚本默认需要 Python。我建议你顺手装一个反正官方安装包也不大。Windows去官网下载 Windows 安装包安装时一定一定勾选Add Python to PATH否则后面执行python会提示找不到命令。macOS/LinuxmacOS 自带 Python3但版本可能老Linux 用自带包管理器安装即可。验证命令python --version。如果输出的是 Python 3.10 以上就没问题。到这里前置环境就完成了。你会发现这些步骤不复杂但它们是一个链条Git 负责版本层面的事Node 负责把 Codex 下载到本地Python 负责运行后续脚本。三者分工明确少一个都容易在后面的某个步骤里莫名其妙卡住。3. 安装 Codex 的三种方式推荐第一种3.1 推荐npm 全局安装这是目前最通用、文档最多、也最容易排查问题的方式。在终端执行npm install -g openai/codex-g表示“全局安装”意思是把codex命令放到系统命令目录里以后在任何路径下都能直接调用。安装过程会有进度条几十秒到几分钟不等取决于网络状况和电脑性能。装完以后终端里会多出一个codex命令。如果报错信息里包含EACCES或permission denied说明全局目录没有写入权限。macOS/Linux 可以在命令前面加sudosudo npm install -g openai/codexWindows 用户在 PowerShell 里一般没有这个问题但如果遇到“无法加载文件因为在此系统上禁止运行脚本”的提示执行这样一条命令然后把终端关掉重新打开Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser3.2 macOS 用户还可以用 Homebrew如果你已经在用 Homebrew安装更简单brew install codex之后升级用brew upgrade codex。这种方式的优点是和系统的包管理统一缺点是版本更新可能比 npm 渠道稍慢。两种方式不要混着装选一种即可。3.3 预编译二进制包npm 装不上的备用方案还有一种备选方案是从官方发布页下载已经编译好的程序包。它不需要 Node 环境适合那些实在不想装 Node或者 npm 反复出问题的人。去 Codex 的官方发布页或项目发布地址找到对应电脑系统的压缩包。下载后解压里面通常有一个可直接执行的codex或codex.exe文件。把这个文件放到一个你记得住的目录然后把该目录加入系统 PATH 环境变量。Windows 用户可以通过“设置 - 系统 - 关于 - 高级系统设置 - 环境变量”修改 PATHmacOS/Linux 用户在~/.bashrc或~/.zshrc末尾加一行export PATH$PATH:/你放codex的目录保存后执行source ~/.zshrc或重开终端生效。这种方式最麻烦的点就是 PATH 配置所以我把它排在最后。小白用户优先用 npm 方式就好。3.4 如何判断安装成功装完之后不要急着做下一步先验证一次codex --version如果能看到一个类似codex 0.x.x的版本号说明命令已经进入系统 PATH安装成功。如果终端提示command not found就是命令路径不在 PATH 里。解决方法和刚才 PATH 那步一样去环境变量确认目录有没有加对。4. 注册与登录拿到 Codex 的“身份证”4.1 注册 OpenAI 账号Codex 默认需要 OpenAI 账号来鉴定身份。打开 OpenAI 官网点击右上角的 Sign up用你的邮箱注册。密码建议用有大小写、数字、符号的组合不要和别的网站共用。注册时官方会发一封验证邮件点邮件里的链接完成验证。这里我给一个建议注册完以后去账号设置里开启两步验证Two-Factor Authentication。这不是必须的但对你这种要长期使用的人来说值得做。因为之后你会创建 API KeyAPI Key 本质就是钱包权限一旦泄露可能被别人刷掉额度。多一层验证总没坏处。4.2 两种登录方式的区别Codex 登录时主要会区分两种身份一种是“ChatGPT 订阅登录”一种是“API Key 登录”。如果你已经开通 ChatGPT 订阅比如 ChatGPT Plus、Pro 等登录时选择 ChatGPT 登录方式CLI 会借助订阅里的权限来工作。如果你只是注册了普通账号没有订阅那就走 API Key 路线。API Key 是平台给开发者用的访问凭证按用量计费首次实名后平台通常也会赠送一小限额用来测试足够了。对大多数跟着本文走的小白来说先走 API Key 路线更省事因为不需要额外开通订阅功能验证足够。等用熟练了你再决定是否升级订阅。4.3 申请与保存 API Key登录 OpenAI 平台后进入 API keys 页面点击 Create API key。创建后系统会显示一串以sk-开头的字符串这个字符串只在创建那一刻完整显示一次之后你再回去看只能看到脱敏前缀。所以我强烈建议创建成功后立刻复制保存可以放到本机密码管理器里也可以先存到临时文本文件用完再删除。然后把 Key 设置成环境变量。这样 Codex 运行时会自动读取而不必每次手动输入。bash/zsh 用户编辑~/.bashrc或~/.zshrc添加一行export OPENAI_API_KEYsk-你的key保存后执行source ~/.bashrc或重开终端。Windows PowerShell 用户可以通过“系统属性 - 环境变量”添加用户变量或者在当前会话执行$env:OPENAI_API_KEY sk-你的key一定要避免的事把你的 API Key 直接写进项目代码里更不要发到网上。它会变成别人替你买单的工具。4.4 codex login 与首次启动环境变量配好后运行codex login不同版本的命令细节略有差异有的版本会弹出浏览器页面让你确认有的版本会直接提示输入 Key。如果你运行codex login时提示没有这个子命令也没关系直接运行codex首次启动时会进入一个交互式配置流程按提示选择登录方式即可。首次启动时Codex 会生成一个配置文件通常是~/.codex/config.toml。它会问你要用哪个服务商、哪个模型、默认工作目录等等。这一阶段看不懂的选择项直接接受默认值即可。只要能进入类似聊天对话的界面就说明注册、登录、配置三步全部打通了。5. 第一次跑通让 Codex 帮你干活5.1 Codex 的三种工作模式为了不让新手被各种命令行参数吓到我把最常见的运行状态总结成三种交互模式直接输入codex回车进入一个对话式终端你一句需求它一步操作适合边聊边改。单次执行模式输入codex 需求描述它会一次性完成整个需求适合指令明确、不希望来回确认的任务。全自动模式输入codex --full-auto 需求描述它会尽量跳过每一步确认连续执行一系列操作。新手我不建议一上来就用这个模式等你对它的行为模式有感觉了再试。另外还有一个很重要的安全参数是“审批策略”。默认模式下Codex 要执行命令或修改文件时会在终端里列出具体操作等你确认。这个机制是在保护你的电脑平时不要为了省事把它关掉。5.2 实战创建一个小脚本找一个空目录比如D:\codex-demo或~/codex-demo在里面执行codex 写一个猜数字小游戏保存为 guess.py再告诉我怎么运行正常情况下Codex 会先分析需求然后创建guess.py在终端展示它写了什么然后给出运行建议。你可以接着运行python guess.py第一次跑通这个流程你就能理解它和普通聊天工具的核心区别它不是给你一堆代码让你复制而是真的把文件写到了磁盘上。5.3 实战让它修改多个文件脚本类需求太简单再试一个稍微完整的场景。在目录里准备一个简单的网页项目比如有一个index.html、一个style.css。然后对 Codex 说把页面标题改成“我的 AI 读书清单”在页面底部加一个“添加笔记”的按钮并把按钮样式加到 style.css 里这次它会同时改两个文件最后可能还会建议用 Git 生成 diff。如果你已经按前面教程配置了git config可以让它顺手git init并提交一次它会像人类工程师一样把改动整理成一个 commit。对新手来说这种组合拳比单独写代码更有实感。5.4 新手用好 Codex 的几条心得我用了几个月最大的感受是你的需求描述越具体它的表现越靠谱。不要只说“帮我写个工具”要说“帮我写一个 Python 脚本读取当前目录下所有 txt 文件统计每个文件的行数并输出成 CSV”。模糊描述会让它自由发挥而自由发挥时很容易跑偏。另外一次只做一件事。刚开始用它时我习惯把一堆需求塞进一句话里结果它东改一下西改一下最后我压根看不明白。正确的做法是拆成几条指令每一条确认完再下一条。效率反而更高。6. 常见报错与排查实录小白避坑手册这一节我按阶段整理成表格方便你按图索骥。6.1 安装阶段的报错报错特征常见原因解决方法EACCES/permission denied全局安装目录无写入权限用 sudo 重试或配置 npm 用户级目录command not found: codex命令没有进入 PATH重新检查全局安装路径与环境变量ETIMEDOUT/ 下载超时网络不稳定或 npm 镜像拖速重试或检查当前网络能否正常访问服务站点PowerShell 禁止运行脚本脚本执行策略限制执行Set-ExecutionPolicy ...后重开终端npm 超时问题在大型包上很常见不一定是你电脑坏了。先重试一次尽量不要开着大量下载软件同时安装会好很多。6.2 登录和鉴权阶段的报错401 Unauthorized或Invalid API Key说明 Codex 拿到的 key 不对。先去确认环境变量里是不是多了一个回车、少了一个字符很多新手就是复制的时候多复制了空格。403 Forbidden大概率是账号权限不够或者当前 Key 没有绑定对应服务的权限。回到 OpenAI 平台检查账号状态和 API 访问权限。登录成功后马上又退出看一下是不是同时存在多个登录凭据互相覆盖。可以删除~/.codex目录下的登录缓存文件重新codex login。6.3 网络与链路类报错有一种报错非常典型API Key 看起来没问题配置也对请求一发出就出现类似“本地链路在处理 codex endpoint /responses 时失败”的英文提示。新手遇到它基本都会慌以为软件坏了。依据我的经验顺序排查四件事确认当前网络环境能否正常打开 Codex 官网和对应服务站点。如果网站都打不开先排除网络原因再谈其他。把 Codex 升级到最新版。这类报错里有很大一部分是旧版本与当前服务端协议不兼容导致的。检查系统 DNS 和防火墙设置。有些安全软件会拦截终端进程的联网权限放行codex进程再试。清理~/.codex下的临时状态文件后重新登录。缓存文件损坏也可能造成请求被中断。这类问题只有极少数情况是 Codex 自身 bug绝大多数是运行环境层面的问题。你按顺序排查通常比反复重装软件更有效。6.4 模型相关的报错如果在配置文件里手动指定了一个 Codex 不支持的模型名称会出现类似the xxxx model is not supported when using codex with a ...的报错。这个报错的意思是你指定的模型不在当前 CLI 版本支持的列表里。解决方法是先注释掉自定义模型用默认模型启动之后再考虑换模型或者把 Codex 升级到支持该模型的版本。还有一种情况是账号对该模型没有访问权限那你需要在对应服务商那里确认权限是否开通。6.5 其他零散问题Git 未配置身份会报错前面已经说过如果出现“端口被占用”通常是本机其他服务占用了 Codex 使用的端口重启终端或换目录即可。把报错原文复制到搜索引擎里搜是最快的学习方式但注意别把 API Key 也贴进去。7. 进阶玩法接入 DeepSeek、让交互变成中文7.1 为什么要接入第三方模型Codex 的魅力之一是它的开源生态允许你通过配置文件自定义模型服务商。简单说你可以把底层那个负责“思考”的模型换成其他服务商提供的模型。DeepSeek 因为中文理解能力强、API 价格实在成为很多人接入的首选。这样做的价值不只是省钱有时候中文长尾需求的表达确实由中文友好型模型处理起来更顺手。7.2 在 config.toml 里配置 DeepSeek打开~/.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 wire_api chat然后你还要去 DeepSeek 开放平台注册一个账号创建 API Key把 Key 设置成环境变量DEEPSEEK_API_KEY。重启终端后运行codex它就会按配置的路子走 DeepSeek 的接口。不同 Codex 版本的配置字段可能有差异如果你启动时提示model_provider不存在或字段名不对就以该版本的官方配置说明为准我这里的版本是通用写法。7.3 常用配置项值得花十分钟读一读配置文件是你和 Codex 默契的关键。几个常用配置值得自己改一改默认模型model ...决定每次启动用哪个模型。审批策略approval_policy控制命令是每次都问你还是自动批准。新手保留默认确认制。沙箱权限sandbox_mode控制 Codex 在多大范围内动文件。想让它只修改当前目录就设置成只写当前工作区。这些选项读一遍文档成本不高但能把工具的脾气摸准以后少踩很多坑。7.4 让 Codex 说中文的小技巧很多小白误以为“汉化”就是把安装界面变成中文。其实 Codex 的交互界面全是英文但真正影响你体验的不是按钮上的单词而是它回答你时的语言。最直接的办法是在每次启动的指令里加一句“请始终使用中文回复”。你会发现它的分析和代码注释都变成中文了。如果你想把这个习惯固定下来可以在配置文件里把默认的 system 提示词改成包含“你是我的结对程序员所有解释和总结都用中文”的版本。第三方模型普遍中文支持很好大家喜欢接 DeepSeek 的另一个原因正是它的中文对话质感更自然。最后分享一个我这段时间一直在用的小习惯每次开始新项目先让 Codex 在目录里生成一个todo.md把需求拆成一二三四条再让它照着清单一条一条做。这样做的好处是你能清楚看到它接下来要干什么中途发现跑偏可以及时喊停。等对它熟悉了再慢慢从交互模式切到全自动模式这样既保住了效率也保住了对代码仓库的控制权。工具是其次把节奏握在自己手里才是最划算的。