Codex安装部署教程：命令行里跑通第一个任务-知了AI

终端里跑一个能自己读代码、改文件、执行命令的代理，这件事在两年前还是实验，现在已经是日常。Codex 就是这类工具里最典型的一个：它在你的项目目录里启动，读懂仓库结构，提出改动，等你确认后落盘。装它不难，难的是搞清楚它到底能自己动多少——权限给少了它处处卡住，给多了它可能改掉你不想动的文件。

这篇教程把安装和上手拆成两条线：前六节解决「怎么装、怎么登录、怎么跑通第一件事」，后六节解决「怎么让它按你的规矩干活」——权限、项目约定文件、模型档位、配置文件、脚本化调用。如果你只想要一条能跑的命令，看第三节就够；如果你打算长期用，第七节之后更值得读。

一、Codex 是什么，装的是哪一部分

1.1 同一个名字下的四种形态

Codex 现在不是单一产品，而是一套：终端里的命令行工具、编辑器插件、ChatGPT 桌面端里的工作区、以及把任务丢到云端的模式。它们共用同一份配置文件和同一套 MCP 服务，所以配置一次，几处都能用。

这篇讲的是命令行版本。它的特点是能在任意目录启动、能被脚本调用、能接进 CI。插件和桌面端更适合看一眼 diff 点个确认，命令行版本适合把重复动作固定下来。

1.2 它和别的终端代理差在哪

同样是终端代理，Codex 的取舍偏向「默认保守」：网络默认关闭，沙箱默认只允许写工作目录，连工作目录里的版本控制目录、配置目录都保持只读。这个设计让它第一次上手时显得有点笨，但也让它不容易在你没看清的情况下把仓库搞乱。

对比项	Codex 命令行	同类终端代理	编辑器内嵌助手	网页版对话
运行位置	本机终端，直接在仓库里	本机终端，直接在仓库里	编辑器进程内	远端浏览器
能否执行命令	能，受沙箱约束	能，受权限约束	部分能	不能
能否脚本化	能，有非交互模式	能	不能	不能
默认网络访问	关闭，需显式开启	多数默认开启	跟随编辑器	仅对话
适合的场景	批量重构、CI、固定流程	日常结对开发	边写边改	问方案、查资料

二、装之前先确认三件事

2.1 系统与依赖

macOS 的 Apple 芯片和 Intel 芯片都支持，Linux 支持 x64 与 arm64，Windows 也能原生跑。用 npm 安装需要先有 Node 环境；用独立安装脚本或 Homebrew 则不需要。Linux 和 WSL2 上还要额外装一个沙箱依赖，Ubuntu 和 Debian 系用 apt 装，Fedora 系用 dnf 装，缺了它启动时会报警告，并退回一个需要非特权用户命名空间的备用方案。

2.2 三条安装路径怎么选

安装方式	适用平台	前置依赖	升级方式	推荐人群
独立安装脚本	macOS、Linux、WSL2	无	重跑同一条命令	大多数个人开发者
Homebrew	macOS	已装 Homebrew	brew upgrade	习惯用包管理的人
npm 全局包	全平台	Node 环境	重跑安装命令	已有 Node 工具链的人

三种方式最后得到的都是同一个 Codex 命令，别混装。混装的典型后果是机器上出现两个版本，终端里敲出来的是旧的，你怎么改配置都不生效。

2.3 国内网络的两个现实问题

一是安装脚本要访问境外地址，网络不稳时建议改用 npm 并指定国内镜像源。二是登录时浏览器回跳可能失败，这时候不是装错了，是回跳被拦，换设备码登录能绕过。这两件事后面都会再提。

三、三平台安装步骤

3.1 macOS 与 Linux：一条脚本

打开终端，执行 Codex 官方脚本，装完重开一个终端窗口让路径生效。升级也是同一条命令，不需要先卸载。这种装法的好处是自带运行时，不依赖你机器上的 Node 版本，也不会因为 Node 升级而失效。

3.2 Windows：新开一个 PowerShell 窗口

在开始菜单里找到 PowerShell，以普通权限新开窗口，执行官方给的安装命令，脚本会自动下载并放进用户目录。装完关掉窗口重开，让环境变量生效。

3.2.1 PowerShell 提示禁止运行脚本

这不是 Codex 的问题，是执行策略限制。两个处理方式：改用命令提示符跑 npm 安装，或者把当前用户的执行策略改成允许本地脚本。改完记得重开窗口。企业电脑如果策略被组策略锁死，找管理员，别自己硬改机器级设置。

3.3 npm 与 Homebrew：适合已有工具链的人

npm 路线就是全局装包，国内网络慢时加镜像源参数。macOS 上如果提示权限不足，说明全局目录不在你的可写范围，正确做法是修好 npm 的全局前缀，而不是每次都用提权安装——提权装出来的文件属主是 root，后面升级会一路报错。

3.4 验证装没装上

敲一次版本查询命令，能输出版本号就算成功。如果提示找不到命令，八成是路径没刷新：关掉终端重开，或者手动把安装目录加进环境变量。这一步别跳过，很多人后面所有失败都源于这里。

四、登录与认证：两种账号体系

4.1 用订阅账号登录

第一次在项目目录里启动 Codex，它会问你怎么认证。选浏览器登录，会自动打开页面，登录完成后凭据回传到本地。这种方式的额度跟着你的订阅计划走，会话里可以随时查看还剩多少。适合已经有订阅的人，不用另外申请密钥。

4.2 用接口密钥登录

没有订阅、或者要按量计费，就用密钥。做法是把环境变量里的密钥通过管道喂给登录命令，注意不要把密钥直接写进命令历史，也不要提交到仓库。密钥登录的模型范围跟着这把密钥走，部分依赖工作区的云端功能不可用，这是正常限制。

4.3 无图形界面的服务器怎么办

远程机器、容器里没有浏览器，用设备码登录：命令会给你一个码，你在另一台设备的浏览器里输入并确认。这个方式需要在账号安全设置里先允许设备码登录，企业账号可能要管理员开启。

4.4 凭据存在哪，怎么退出

凭据落在用户目录下的配置文件里，也可能是系统凭据库。这个文件等同于密码，别复制给别人，别放进同步盘。查询当前认证方式、清除凭据都有对应命令，换账号时先退出再登录，别直接覆盖。

五、权限与沙箱：决定它能自己动多少

这是 Codex 最值得花时间理解的一块。它有两个独立的控制：沙箱决定「能碰什么」，审批决定「什么时候停下来问你」。两个都设对了，它才既好用又安全。

5.1 沙箱的三档

Codex 的只读档：能读文件、能跑只读命令，不能改任何东西，适合先摸清仓库。工作区可写档：能在工作目录内改文件、跑命令，但网络默认关闭，越界要请示。全权限档：没有任何限制，只在隔离的容器或临时机器上用。

5.2 审批的两种

一种是「越界前询问」，也就是它要出沙箱边界时才停下来问你；另一种是「从不询问」，适合只读的自动化脚本。旧教程里还有第三种叫「不信任」，现在已经不能选了，看到别照抄。

使用场景	沙箱档位	审批策略	实际效果	风险等级
刚接触一个陌生仓库	只读	越界前询问	只读不改，先看清结构	最低
日常改代码（版本控制目录内）	工作区可写	越界前询问	能改能跑，出界要问你	中
只读脚本、巡检任务	只读	从不询问	全程无人值守，不改文件	低
隔离容器里的批处理	全权限	从不询问	无限制执行	高，仅限一次性环境

5.3 需要多一个目录时别开全权限

它读不到隔壁目录的配置，正确的做法是额外挂载一个目录，或者给某条命令前缀加规则，允许、询问或禁止。直接切到全权限是最省事也最危险的选择——省下的一次配置，可能在某个下午变成一次误删。

5.4 那条「一把梭」参数不要碰

有个跳过所有沙箱和审批的开关，别名很好记，官方文档自己都标注不推荐。它存在的原因是给一次性容器用的，不是给日常开发用的。你在自己主力机器上用它，等于把一个会执行任意命令的程序放进了没有围栏的场地。

六、跑通第一个任务

6.1 先提交一次，再让它动手

进项目目录，确认工作区干净，先做一次提交。这不是形式主义：它改完你能用版本控制一键回退，心里有底，才敢让它改更多。没有版本控制的目录，建议先初始化，或者干脆别在那种目录里跑代理。

6.2 一句话任务要写清四件事

目标、相关文件或上下文、约束条件、完成标准。反例是让 Codex「优化一下这个项目」，正例是「给命令行加一个试运行参数，只打印将要改动的内容不写文件，改动集中在入口文件和参数解析两处，加一个测试用例，跑通现有测试后告诉我改了什么」。后者一次能成，前者要来回五轮。

6.3 看 diff，像审一个新同事的提交

它会展示改动，包括还没被版本控制跟踪的新文件。逐行看，重点看三件事：有没有超出任务范围的改动、异常分支有没有处理、有没有偷偷改了配置或依赖。看 diff 这个动作，是这个工具能不能长期用下去的分水岭。

七、七个高频命令

命令	作用	什么时候用	是否改动文件
初始化项目约定	在当前目录生成项目说明文件骨架	第一次进一个仓库	会新建一个文件
切换模型	换模型和推理档位	任务难度变化时	不会
权限设置	调整沙箱与审批，查看可写目录	发现它被卡住时	不会
查看差异	展示全部改动	每次接受改动前	不会
查看状态	会话配置与用量	想知道还剩多少额度	不会
压缩上下文	总结对话，腾出空间	长会话开始变迟钝	不会
新开会话	在同一终端里重置对话	换任务时	不会

另外有两个启动参数很实用：一个可以在第一条指令里附带截图或架构图，排查界面问题时省掉大量描述；另一个给单次运行开启联网检索，适合需要查最新文档的任务。联网是显式开启的，不会默认偷偷访问。

八、项目约定文件：把规矩写下来

8.1 先生成骨架，再往里填

在仓库根目录给 Codex 跑一次初始化命令，会生成一个约定文件。它是纯文本，写清楚仓库结构、怎么装依赖、怎么跑测试、代码规范、哪些目录不许动、什么算完成。写得好，后面每次会话都省下你重复解释的力气。

8.2 它按什么顺序读

先读全局的，再读项目里的，从仓库根目录一路读到你现在所在的目录，越靠近当前目录的优先级越高，靠后的覆盖靠前的。合并后的内容有大小上限，默认三十二千字节，超了会被截断。所以别把整本规范往里塞，写关键约束。

8.3 写什么最值

按经验排序：构建和测试命令最重要，其次是目录职责说明，再其次是代码风格与禁止事项。最没用的是一堆愿景描述。代理不缺方向感，缺的是「这个项目怎么跑起来、改完怎么验证」。

九、模型与推理档怎么选

模型定位	能力取向	成本	适合任务	不适合
旗舰档	综合最强，长链路推理稳	最高	跨模块重构、复杂缺陷定位	改个变量名这种小事
主力档	接近旗舰，成本更低	中等	日常开发、绝大多数任务	极难的端到端问题
轻量档	快、便宜	最低	批量小改动、格式整理	多步骤规划

推理档位是另一个维度。默认档够用，遇到需要仔细规划的任务再往上调；最高档会花更多时间思考，还有一档会把工作拆给子代理并行跑。多数任务用不到这两档，盲目拉满只是把等待时间变长。

十、配置文件与分层优先级

10.1 一个最小可用配置

配置文件在用户目录下的隐藏文件夹里，纯文本格式。最小配置只需要四行：默认模型、推理档、审批策略、沙箱档位。写进去之后，每次启动都按这个来，不用每次敲参数。

10.2 五层优先级，从高到低

命令行参数最高，其次是项目内的配置（仅对受信任项目生效），再其次是命令行选中的配置档，然后是用户级配置，最后是系统级与内置默认值。理解这个顺序，你就能解释「为什么我改了配置没生效」——大概率是被更高层的设置覆盖了。

10.3 用配置档切换场景

给不同场景建不同的配置档，比如「快速小改」用一个便宜模型，「深度重构」用旗舰模型，启动时指定档案名即可。每个档案只写与默认值不同的项，别整份复制，否则改一处要同步好几份。

十一、接 MCP 与外部工具

它支持挂载本地或远程的 MCP 服务，把外部系统变成它能调用的工具。装之前想清楚两件事：这个服务要什么权限，它会不会把数据带出去。挂上之后可以在会话里查看当前有哪些工具可用，再决定让它调哪个。企业内部系统接入时，优先走内网服务，别用公网中转。

十二、放进脚本与流水线

12.1 非交互模式的三个要点

Codex 的非交互模式跑任务，进度走标准错误，最终结果走标准输出，所以能干净地接管道。默认是只读的，要改文件必须显式给工作区可写档。它要求当前目录是版本控制仓库，不是的话需要加参数跳过检查——这个参数只在你确定环境安全时用。

12.2 让输出可被程序消费

三种方式：输出成逐行事件流，适合喂给日志系统；把最终消息写进指定文件，适合做产物；按给定的结构约束输出，适合下游直接解析。这三种组合起来，就能把「让代理评审一次改动」变成一个可以定时的任务。

12.3 流水线里的边界

流水线环境建议用只读档加从不询问，需要它改代码的环节单独放行，并且限制在一次性容器里。别在共享的构建机上开全权限，那台机器上可能有别人的凭据。

十三、故障排查对照

现象	多半原因	处理方式
提示找不到命令	安装目录不在环境变量里	重开终端，或手动加路径
装了两个版本，改配置不生效	混装，实际调用的是旧版本	卸载多余那份，只留一种装法
启动报警告说沙箱不可用	Linux 缺沙箱依赖	用包管理器装上再启动
登录后浏览器回跳失败	回跳被拦截	改用设备码登录
它总说没有网络权限	网络默认关闭	单次运行显式开启检索
改文件被拒	沙箱只读，或目录不在可写范围	切工作区可写档，或额外挂载目录
长会话开始答非所问	上下文塞满	压缩对话，或新开会话
流水线里跑不出结果	目录不是仓库，或默认只读	给可写档，必要时跳过仓库检查