AI天信恒瑞AI分享站
登录注册
返回模型教程

模型教程

Codex 安装部署与使用全流程：从本地开发到服务器自动化

从 macOS、Windows、Linux 安装，到登录、AGENTS.md、权限沙箱、MCP、非交互执行和服务器/CI 自动化，系统梳理 OpenAI Codex 的安装部署方法。

2026-04-3015 分钟教程 / AI入门

更新时间：2026-04-30。本文参考 OpenAI 官方 Codex 文档、OpenAI Help Center、OpenAI Codex 官方仓库，并结合本机实测命令整理。本机当前 codex --version 为 codex-cli 0.124.0；写作时 npm view @openai/codex version 返回 0.125.0，版本会持续更新，请以安装时的官方与包管理器结果为准。

Codex 工作流

这篇教程适合谁

Codex 是 OpenAI 面向软件开发的编程智能体。你可以在终端、桌面端、IDE 或云端任务里使用它，让它读取真实代码库、解释项目结构、修改文件、运行命令、写测试、做代码审查，并把工作过程收敛成可检查的 diff。

这篇教程主要解决四类问题：

  • 不知道 macOS、Windows、Linux 应该如何安装 Codex。
  • 想把 Codex 放进真实项目，而不是只在聊天窗口里问代码。
  • 想在服务器或 CI 中使用 codex exec 做自动化任务。
  • 担心它误删文件、误读密钥、乱跑命令，需要一套权限和安全配置方法。

先给结论：个人本机入门优先使用 npm install -g @openai/codex；macOS 用户也可以用 Homebrew cask；Windows 用户可以先安装 Codex 桌面端，CLI 仍建议用 npm 或 WSL 路线；服务器和 CI 场景要使用最小权限、固定工作目录、明确 sandbox 与 approval 策略。

安装前准备

项目 建议
操作系统 macOS、Linux、Windows 或 WSL。桌面端另有 macOS / Windows 应用路线
Node.js 推荐安装当前 LTS 版本，使用 npm 全局安装 CLI
Git 建议安装并确认 git --version 可用
账号 ChatGPT 账号、OpenAI API Key，或企业统一配置的 OpenAI 接入
项目环境 最好在 Git 仓库中使用，便于查看 diff 和回滚
终端 macOS 用 Terminal / iTerm2；Windows 用 PowerShell / Windows Terminal；Linux / WSL 用 Bash 或 Zsh

如果你只是想体验交互式开发，装好 CLI 并登录就够了。如果你想在服务器、CI、后台任务里跑 Codex，需要额外准备环境变量、权限策略和日志留存方式。

安装路径怎么选

Codex 安装路径选择

场景 推荐方式 命令或入口
macOS / Linux / WSL 通用 npm 全局安装 npm install -g @openai/codex
macOS Homebrew Homebrew cask brew install --cask codex
Windows 桌面体验 Microsoft Store 安装 Codex 桌面端 在 Microsoft Store 搜索 OpenAI Codex
Windows CLI Node.js + npm，或 WSL + npm npm install -g @openai/codex
服务器 / CI npm 固定版本安装 npm install -g @openai/codex@0.125.0
团队统一环境 镜像、脚本或 devcontainer 固定 Node、Codex 版本和安全策略

如果你只在本机写代码，选 npm 或 Homebrew 即可。如果你要让 CI 自动跑 Codex，建议固定版本，不要每次都安装最新版本，避免一次升级影响构建稳定性。

macOS 安装

方式一：npm 安装

先确认 Node.js 和 npm 可用：

node --version
npm --version

安装 Codex CLI：

npm install -g @openai/codex

检查版本：

codex --version

如果提示 command not found: codex，通常是 npm 全局 bin 目录没有加入 PATH。可以先查看 npm 全局路径：

npm config get prefix
ls "$(npm prefix -g)/bin/codex"

然后把对应目录加入 shell 配置。zsh 常见写法：

NPM_PREFIX="$(npm prefix -g)"
echo "export PATH=\"$NPM_PREFIX/bin:\$PATH\"" >> ~/.zshrc
source ~/.zshrc
codex --version

如果你用的是 nvm、fnm、volta，优先按对应工具的方式管理 Node 和全局包，避免系统 Node 与用户 Node 混用。

方式二：Homebrew 安装

macOS 用户也可以用 Homebrew：

brew install --cask codex

升级：

brew upgrade --cask codex

确认：

codex --version

写作时本机查询 Homebrew cask 里的 codex 版本为 0.125.0。如果你所在网络或 Homebrew 源同步较慢，版本号可能暂时落后。

Windows 安装

Windows 现在有两条常见路线：桌面端和 CLI。

方式一：Codex 桌面端

如果你希望像编辑器一样管理多个任务、查看 diff、并行启动 agent，可以先从 Microsoft Store 安装 Codex 桌面端。安装后按界面提示登录 ChatGPT 账号。

桌面端适合这些场景：

  • 不想一开始就记命令行参数。
  • 想同时管理多个 Codex 任务。
  • 想用系统级沙箱和图形化 diff 审查。

方式二：Node.js + npm 安装 CLI

先安装 Node.js LTS，然后在 PowerShell 中运行：

npm install -g @openai/codex

检查版本：

codex --version

如果公司电脑限制全局 npm 安装，可以使用管理员 PowerShell，或者改用 nvm-windows / fnm 管理用户级 Node。

方式三：WSL 安装

如果你的项目本来就跑在 Linux 工具链里，例如 Docker、Bash、Makefile、Python、Ruby、Go，可以直接在 WSL Ubuntu 里安装：

npm install -g @openai/codex
codex --version

WSL 的优点是 Linux 命令兼容性好；缺点是 Windows 文件系统和 WSL 文件系统之间要注意路径差异。建议把项目放在 WSL 自己的 Linux 文件系统中，例如 ~/projects/my-app，不要长期在 /mnt/c/... 下高频读写。

Linux / 服务器安装

服务器上建议先安装 Node.js LTS，再安装 Codex：

npm install -g @openai/codex
codex --version

生产服务器不建议直接在业务目录里让 Codex 获得过大权限。更稳的做法是：

  • 单独创建低权限用户，例如 codex-runner。
  • 只给它读取代码仓库和写入临时工作区的权限。
  • 不把生产 .env、私钥、数据库备份放进可读目录。
  • 在 CI 或临时容器中运行自动化任务。

示例：

sudo useradd -m -s /bin/bash codex-runner
sudo mkdir -p /opt/codex-workspaces
sudo chown -R codex-runner:codex-runner /opt/codex-workspaces

切换用户后再安装和登录：

sudo -iu codex-runner
npm install -g @openai/codex
codex --version

登录和认证

首次交互式使用：

codex login

查看登录状态：

codex login status

如果你要在服务器或 CI 中使用 API Key，可以把 key 通过标准输入交给 Codex：

printenv OPENAI_API_KEY | codex login --with-api-key

企业环境建议把 key 放在 CI Secret、云厂商 Secret Manager 或内部密钥系统中，不要写进仓库、镜像、脚本注释或聊天记录。

第一次进项目：先让它读，不要让它改

Codex 第一次使用路线

进入项目：

cd /path/to/your/project
codex

第一次不要直接说“帮我重构项目”。更稳的第一句是：

请先不要修改文件。请阅读项目结构，告诉我这个项目的技术栈、核心入口、主要模块和风险点。

然后让它继续梳理：

请解释用户登录从前端页面到后端 API 再到数据库的调用链路。只分析，不修改。

准备让它改代码时，先要计划：

我想修复登录失败后没有错误提示的问题。请先列出你准备查看哪些文件、准备修改哪些文件、如何验证。先不要改代码。

确认范围后再执行：

按上面的计划执行。只改登录相关文件，改完后运行对应测试，并总结每个文件为什么改。

这个节奏很重要：先读代码、再出计划、再执行、再验证，能明显减少大范围误改。

用 AGENTS.md 固化项目规则

Codex 会读取项目中的 AGENTS.md，把它当作本仓库的工作说明。它适合存放团队希望 Codex 长期遵守的规则，例如常用命令、代码风格、目录边界、禁止事项、测试要求。

一个企业项目可以这样写：

# 项目说明

这是一个 Next.js + PostgreSQL 的企业 AI 分享站。

## 常用命令

- 安装依赖：npm ci
- 本地开发：npm run dev
- 类型检查：npm run typecheck
- 单元测试：npm test
- 构建：npm run build

## 工作规则

- 所有用户可见文案使用中文。
- 修改认证、权限、内容发布相关逻辑时必须补充测试。
- 不要读取、打印或提交 .env、私钥、数据库备份。
- 先说明计划，再小步修改，最后运行相关验证命令。

当你第二次纠正同一个问题，就应该考虑把这条规则写进 AGENTS.md。这比每次在提示词里重复更稳定。

权限、沙箱和审批策略

Codex 部署与自动化安全

Codex CLI 支持通过参数控制模型、工作目录、沙箱和审批策略。常用参数如下：

参数 用途 示例
-C, --cd 指定工作目录 codex -C /path/to/project
-m, --model 指定模型 codex -m gpt-5.2
-s, --sandbox 设置沙箱模式 codex -s workspace-write
-a, --ask-for-approval 设置审批策略 codex -a on-request
--search 启用网页搜索 codex --search
--full-auto 低摩擦自动执行 适合隔离环境中的低风险任务

新手建议从保守组合开始：

codex -s workspace-write -a on-request

这表示 Codex 可以在工作区内操作，但遇到需要审批的动作会停下来问你。不要在真实项目里随手使用危险权限：

codex --dangerously-bypass-approvals-and-sandbox

这个模式只适合外部已经隔离好的容器、一次性虚拟机或测试沙箱。真实业务仓库、生产服务器、含密钥目录都不建议使用。

配置文件：把默认习惯写清楚

Codex 支持用 ~/.codex/config.toml 管理个人默认配置，也可以通过命令行参数覆盖。

示例配置：

model = "gpt-5.2"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[features]
web_search = false

你也可以临时覆盖单项配置：

codex -c 'model="gpt-5.2"' -c 'approval_policy="on-request"'

团队环境不要把个人偏好写成所有人必须遵守的规则。项目级规则写进 AGENTS.md，个人快捷配置放在自己的 ~/.codex/config.toml。

非交互执行：服务器和 CI 的核心能力

codex exec 可以让 Codex 在非交互模式中执行一次任务，适合脚本、CI、定时任务和流水线。

最简单的例子：

codex exec "请检查当前项目是否有明显的 TypeScript 类型错误风险，只分析，不修改。"

指定工作目录：

codex exec -C /opt/my-app "请阅读项目并总结主要模块。不要修改文件。"

从标准输入传入内容：

git diff --stat | codex exec "请根据这段 diff stat 判断改动风险，并列出需要重点审查的文件。"

输出最后一条消息到文件：

codex exec -o codex-summary.md "请审查当前 diff，并输出中文审查摘要。"

CI 中建议使用保守权限：

codex exec \
  -s read-only \
  -a never \
  --skip-git-repo-check \
  "请审查当前代码变更，只输出风险和建议，不修改文件。"

如果你确实要让 Codex 在 CI 中改文件，建议只在临时分支或临时工作区运行，并强制后续有人审查 diff。

代码审查工作流

Codex 自带 review 子命令，适合对当前仓库做代码审查：

codex review

也可以在非交互模式里做更明确的审查：

git diff main...HEAD | codex exec "请做代码审查，重点看安全、权限、边界条件、缺失测试。用中文输出文件名、风险等级和建议。"

建议把审查重点写清楚，不要只说“帮我 review”。好的审查提示通常包含：

  • 审查范围：当前 diff、指定文件、指定 PR。
  • 审查重点：安全、权限、性能、数据一致性、测试覆盖。
  • 输出格式：按严重程度排序，必须引用文件路径。
  • 限制条件：只分析，不修改。

MCP 和外部工具

Codex 可以通过 MCP 接入外部工具，例如浏览器、设计工具、文档、数据库、公司内部系统。

查看已配置的 MCP：

codex mcp list

添加 MCP：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

移除 MCP：

codex mcp remove openaiDeveloperDocs

企业接 MCP 时要注意两件事：第一，工具能读到什么数据；第二，工具能执行什么动作。能读客户数据、生产数据库、内部文档的 MCP，不应该默认给所有人开放写权限。

常用命令速查

命令 用途
codex 进入交互式 CLI
codex "解释这个项目" 带初始提示进入会话
codex --version 查看版本
codex login 登录
codex login status 查看登录状态
codex logout 退出登录
codex exec "任务" 非交互执行一次任务
codex exec -C /path/to/project "任务" 指定工作目录执行
codex review 运行代码审查
codex resume 恢复历史会话
codex mcp list 查看 MCP 配置
codex app 启动或安装 Codex 桌面端
codex completion zsh 生成 zsh 补全脚本

交互式会话里还可以使用斜杠命令。不同版本的命令会变化，进入后运行：

/help

先看当前版本支持什么，再决定要不要把常用命令写进团队文档。

新手最容易踩的坑

1. 安装成功但命令找不到

先确认：

which codex
codex --version

如果 which codex 没结果，检查 npm 全局目录：

npm config get prefix
ls "$(npm prefix -g)/bin/codex"

再把全局 bin 目录加入 PATH。

2. 在非 Git 目录里执行复杂任务

Codex 在 Git 仓库里更容易安全工作，因为你可以随时查看 diff：

git status
git diff

如果项目不是 Git 仓库，建议先初始化或复制到临时目录再试：

git init
git add .
git commit -m "baseline before codex"

3. 上来就让它“大改”

不要这样问：

帮我优化整个项目。

更稳的是：

请只分析，不修改。先指出最值得优化的三个点、影响文件、风险和验证方式。

4. 让它读到敏感文件

不要让 Codex 默认读取 .env、私钥、数据库备份、客户导出数据。团队应该在 AGENTS.md 和权限配置中明确禁止，并在审查时检查输出中是否出现敏感内容。

5. CI 中给了过大的权限

CI 中优先使用：

codex exec -s read-only -a never "请审查当前变更，只分析，不修改。"

需要自动改文件时，也应该跑在临时分支，后续通过人工审查和测试合并。

推荐的企业落地流程

  1. 先让团队在一个低风险项目试用，例如内部文档站、脚手架、测试补充。
  2. 写好 AGENTS.md，把技术栈、常用命令、测试要求、禁止事项沉淀下来。
  3. 默认使用 workspace-write + on-request，敏感项目使用只读分析。
  4. 把常见任务做成模板：读项目、修小 Bug、补测试、审查 diff、生成发布说明。
  5. 服务器和 CI 只允许最小权限，所有自动改动必须进 PR 或临时分支。
  6. 每周复盘一次，把高频提示词和踩坑记录更新到团队文档。

Codex 的价值不是把“写代码”这一件事变快，而是把理解项目、形成计划、动手修改、运行验证、解释 diff 这整条链路组织起来。它适合作为工程协作工具，不适合被当成不受约束的自动脚本。第一天就把安装、权限、项目规则和验证流程搭好，后面的效率才会稳定。

参考来源