Codex CLI 是 OpenAI 开源的终端编码代理,仓库在 https://github.com/openai/codex,用 Rust 写成,Apache-2.0 许可。截至 2026 年 9 月 22 日核查,最新发布版 0.155.1(rust-v0.155.1,2026 年 9 月 18 日发布),GitHub Star 数 125,859。安装走官方脚本、npm、Homebrew、Release 二进制四条路,配置集中在 ~/.codex/config.toml,登录用 ChatGPT 账号或 API 密钥。 Codex CLI在哪下载:官方入口
Codex CLI 只有一个源头:github.com/openai/codex 仓库。安装脚本、npm 包、Homebrew cask 发的都是同一个二进制,不存在功能有别的不同版本,挑顺手的下就行。先认准入口,能省掉后面大半的麻烦。
- 源码仓库:https://github.com/openai/codex ,README 里的安装命令是一手出处,Release 二进制也挂在这里。
- 官方安装脚本:https://chatgpt.com/codex/install.sh ,macOS 与 Linux 用;Windows 对应 https://chatgpt.com/codex/install.ps1 。
- 二进制发布站:https://releases.openai.com/codex ,安装脚本默认从这里拉取,拉不到时回退到 GitHub Releases。
- npm 包:https://www.npmjs.com/package/@openai/codex ,包名
@openai/codex,跨平台。
- 开发者文档:https://developers.openai.com/codex ,安装、配置、CLI 参考、AGENTS.md 说明都在这一站。
- 桌面端与网页端:CLI 里跑
codex app 拉起桌面应用,网页版在 https://chatgpt.com/codex 。
第三方教程常常贴出改过的脚本地址,或者让你 curl | sh 一个来源不明的链接。判断标准只有一条:域名是否落在 github.com、chatgpt.com、openai.com、npmjs.com 这几个官方域上。不是就别执行。
Codex CLI安装的4种方式与具体命令
四条路装的是同一个二进制,看你机器上现成有什么工具链。
- 独立安装脚本(macOS / Linux):
curl -fsSL https://chatgpt.com/codex/install.sh | sh。官方推荐路径,也用来升级,再跑一遍这条命令即可。
- Windows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"。
- npm 全局安装:
npm install -g @openai/codex。npm 包声明 engines.node 为 16 及以上,Node 版本不够会装不上。
- Homebrew(macOS):
brew install --cask codex。注意 --cask,Codex 以 cask 形式分发,去掉这个参数会装不到。
想手动拿二进制,去仓库 Releases 页按平台挑包:
- macOS:Apple 芯片
codex-aarch64-apple-darwin.tar.gz,Intel codex-x86_64-apple-darwin.tar.gz,另有 .dmg 安装包
- Linux:x86_64
codex-x86_64-unknown-linux-musl.tar.gz,arm64 codex-aarch64-unknown-linux-musl.tar.gz
- Windows:
codex-x86_64-pc-windows-msvc.exe
- 附带文件:
install.sh、install.ps1、config-schema.json,最后一个喂给编辑器可以做配置项补全
安装脚本默认从 releases.openai.com/codex 下载,取不到时自动回退 GitHub Releases。要强制走 GitHub,把 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM 设成 false 再执行。升级也简单:脚本装的再跑一遍安装命令,或用内置的 codex update;npm 装的重新执行一次 npm install -g @openai/codex。
想跑未发布的代码,就走源码构建:git clone 仓库后进入 codex/codex-rs 目录,用 rustup 装好工具链,再 cargo build。调试时设 RUST_LOG 环境变量看日志,或者用 codex -c log_dir=./.codex-log 把日志落到指定目录。
Codex CLI版本、许可与运行环境要求
下表数据来自 GitHub API 与 npm registry,核查时间 2026 年 9 月 22 日。
| |
|---|
| 0.155.1(tag rust-v0.155.1,2026 年 9 月 18 日发布) |
| |
| |
| |
| |
| |
| |
| |
系统要求以官方 docs/install.md 为准:
| |
|---|
| macOS 12+、Ubuntu 20.04+ / Debian 10+、Windows 11 需经 WSL2 |
| |
| |
沙盒是 Codex CLI 的安全底座,各平台用的机制不一样,跨平台部署时要留意差异:
| | |
|---|
| | |
| | |
| 经 WSL2 使用 Linux 沙盒;原生另有 Windows 沙盒实现 | WSL1 自 0.115 起因 bwrap 限制不再支持 |
Codex CLI登录与config.toml配置
装完先登录。在项目目录里跑 codex,首次运行会让你选登录方式,README 推荐 Sign in with ChatGPT,ChatGPT 的 Plus、Pro、Business、Edu、Enterprise 套餐都能用;重新登录或换方式跑 codex login,退出是 codex logout。改用 API 密钥也行,官方标注这条路需要额外设置。
没有浏览器的环境(SSH、远程开发机)用设备码授权:codex login --device-auth。登录凭据存在 ~/.codex/auth.json,也可能进系统钥匙串,这个文件等同于密码,别提交到仓库,也别塞进镜像。CI 里更稳的做法是单次注入:CODEX_API_KEY=sk-... codex exec,密钥只对这一次执行生效。
配置文件是 ~/.codex/config.toml,Windows 上为 %USERPROFILE%\.codex\config.toml。几个高频配置项如下:
| | |
|---|
| | |
| read-only / workspace-write / danger-full-access | |
| | |
sandbox_workspace_write.network_access | | |
| | |
| cached(默认)/ live / disabled | 联网搜索模式,--search 等价于临时设为 live |
一份偏保守的写法:approval_policy = "on-request" 配合 sandbox_mode = "read-only",再把 allow_login_shell 设为 false。需要联网装依赖时,在 [sandbox_workspace_write] 段里开 network_access = true。
要在几套策略间快速切换,用 profile:把配置另存为 ~/.codex/full_auto.config.toml(on-request 配 workspace-write)或 ~/.codex/readonly_quiet.config.toml(never 配 read-only),启动时 codex --profile full_auto 加载,-p 是简写。只临时改一个值,用 -c。
命令行还有几个常用开关:-a 设审批策略,-s 设沙盒模式,-m 指定模型,-C 指定工作目录,--add-dir 追加可写目录,-i 附带图片,--oss 接本地开源模型(配合 --local-provider lmstudio|ollama),--search 开实时搜索,--strict-config 让不认识的字段直接报错,--yolo 跳过审批与沙盒(官方限定只用于外部已加固的环境)。
Codex CLI常用命令与AGENTS.md规则
子命令按用途分成几类,日常用到的不多:
| |
|---|
| |
| 非交互执行,供脚本和 CI 调用,支持 --json、-o 输出最后一条消息、--output-schema 结构化输出、--skip-git-repo-check |
| 接着上一轮会话继续,或从某轮分叉出新会话,--last 取最近一次 |
| |
| |
| |
| |
codex sandbox macos/linux/windows | |
项目约定写在 AGENTS.md 里,Codex 启动时自动读取。发现顺序是:先看全局的 ~/.codex/AGENTS.override.md,它比 ~/.codex/AGENTS.md 优先,两者只取第一个非空文件;然后从项目根目录逐级向下走到当前工作目录,每层目录只取一个(AGENTS.override.md 优先于 AGENTS.md,再退到备用文件名)。
多个文件不是互相替换,而是从根目录往下拼接,越靠近当前目录的内容排在越后面、优先级越高。单文件默认上限 32 KiB,由 project_doc_max_bytes 控制。实操上常见的组合是:全局 ~/.codex/AGENTS.md 放通用工作约定,仓库根放项目说明,子目录如 services/payments/AGENTS.override.md 写该模块的特殊约束并覆盖上层。
Codex CLI常见报错与排错
几个高频问题的成因和处理办法:
| | |
|---|
| untrusted 策略自 0.149.0 起被移除,旧配置还在 | 从 config.toml 删掉该取值,改用 sandbox_mode = "read-only" 配 approval_policy = "on-request" |
| Windows 11 需经 WSL2,WSL1 自 0.115 起不再支持 | 升级到 WSL2,配置文件路径用 %USERPROFILE%\.codex\config.toml |
| | 配置 sandbox_workspace_write.network_access = true,或用 -s workspace-write |
| | 升级 Node 到 16 及以上,或改走安装脚本 / Homebrew |
| | 用 --strict-config 让未知字段报错,或用 --profile 明确指定 |
| | |
不确定沙盒到底拦住了什么,可以直接实测:codex sandbox macos、codex sandbox linux、codex sandbox windows 分别在本平台跑一遍。原生 Windows 另有开关,在 config.toml 的 [windows] 段设 sandbox = "unelevated" 或 "elevated"。
Codex CLI安装配置的注意事项
- 审批策略已换代:approval_policy 的 untrusted 取值自 0.149.0 起不再支持,沿用旧配置会直接启动失败,替换方案是 read-only 沙盒加 on-request 审批。
- WSL1 已出局:Linux 沙盒依赖 bwrap,WSL1 自 0.115 起不再被支持,Windows 用户请用 WSL2。
- 凭据等同密码:~/.codex/auth.json 里是登录凭据,别进版本库、别打进镜像;CI 场景优先用 CODEX_API_KEY 单次注入。
- --yolo 有前提:它跳过全部审批与沙盒,官方限定只用于外部已经加固过的环境,日常开发机上不要当默认值。
- 沙盒默认断网:需要装包、拉依赖的任务,要么开 network_access,要么提前把依赖装好,否则任务会卡在半路。
- AGENTS.md 有体积上限:单文件默认 32 KiB,写长了会被截断,规范类内容尽量精简,细节交给子目录的 override 文件。
- 只认官方域:安装来源限于 github.com、chatgpt.com、openai.com、npmjs.com,来自其他域名的安装脚本一律不要执行。
- 版本会动:本文版本号、Star 数与配置取值取自 2026 年 9 月 22 日的官方仓库与文档,升级前到仓库 Releases 页确认当期版本。
Codex CLI安装配置常见问题
Q:Codex CLI 免费吗? A:软件本身开源,Apache-2.0 许可,装和用都不收授权费。调用模型要有身份,要么是 ChatGPT 的 Plus、Pro、Business、Edu、Enterprise 套餐账号,要么是 OpenAI API 密钥,成本看你的账号额度或 API 计费。
Q:没有 ChatGPT 账号,能用 API 密钥吗? A:能。官方 README 说明 API 密钥这条路需要额外设置;在 CI 里最省事的做法是 CODEX_API_KEY=sk-... codex exec,只对单次执行生效。交互式场景建议跑 codex login 走 ChatGPT 登录。
Q:Windows 能用吗?怎么装? A:官方给出的支持范围是 Windows 11 经 WSL2。安装用 PowerShell 执行 irm https://chatgpt.com/codex/install.ps1 | iex(配合 -ExecutionPolicy ByPass),配置文件路径是 %USERPROFILE%\.codex\config.toml。
Q:配置文件在哪?怎么改? A:~/.codex/config.toml,Windows 是 %USERPROFILE%\.codex\config.toml。想快速切换多套策略,另存为 ~/.codex/<名字>.config.toml,用 codex --profile <名字> 加载;只临时改一个值就用 -c key=value。
Q:怎么换默认模型? A:在 config.toml 里写 model,或者运行时用 codex -m <模型名> 覆盖。接本地开源模型则用 --oss,配合 --local-provider lmstudio 或 --local-provider ollama 指定后端。
Q:怎么让它记住项目的编码规范? A:写 AGENTS.md。放在项目根目录会被自动读取,子目录可以用 AGENTS.override.md 覆盖上层约定,全局约定放 ~/.codex/AGENTS.md。多个文件从根往下拼接,越靠近当前目录优先级越高,单文件上限 32 KiB。
Q:能在 CI 或者脚本里跑吗? A:用 codex exec,它支持 --json 输出结构化事件、-o 只取最后一条消息、--output-schema 约束输出格式。非 Git 目录加 --skip-git-repo-check。早期的 --full-auto 已废弃,改用 --sandbox workspace-write。
Q:怎么升级到最新版? A:脚本安装的再跑一次 curl -fsSL https://chatgpt.com/codex/install.sh | sh,这也是官方给出的更新命令;也可以用内置的 codex update。npm 装的重新执行 npm install -g @openai/codex 覆盖。
Q:为什么它联网装不了依赖? A:workspace-write 沙盒默认不放行网络。在 config.toml 的 [sandbox_workspace_write] 段设 network_access = true。不确定沙盒边界时,用 codex sandbox linux(或 macos、windows)在本机实测一遍。
版本和配置键名会随着发布变动,升级后先跑一次 codex 确认配置没被新版本判为无效。想跟进它的发布节奏与配置变更,可以留意本站的 AI 工具栏目,Codex CLI安装配置的后续更新我们会同步整理。