pub_md/axmd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4d2acdf6efb4d61fed23272d632cc269ab5301bc
axmd/2026/agent_blog/codex_install.md
T

12 KiB
Raw Blame History

title, date, tags, collections, summary, draft, featured
title date tags collections summary draft featured
Codex CLI 安装、配置与常用方法 2026-05-26
Codex
OpenAI
CLI
AI 编程
软件安装
基于 2026-05-26 检索到的 OpenAI 官方文档，整理使用 mamba 准备 Node.js 环境后安装 Codex CLI 的流程、配置文件写法和常用操作。 false false

Codex CLI 安装、配置与常用方法

这篇笔记基于 2026-05-26 检索到的 OpenAI 官方文档整理，目标是把 Codex CLI 的安装、配置文件和常用操作一次讲清楚。考虑到我自己更习惯用 mamba 管理本地 Node.js 环境，下面先保留这条安装路径，再接官方的 npm 安装步骤。原始草稿里那种把真实密钥直接写进配置文件的做法不适合保留，正式使用时应当改成环境变量或官方登录方式。

安装 Codex CLI

使用 mamba 准备 Node.js 环境

如果你平时用 mamba 管理开发环境，可以先单独准备一个 Node.js 环境，再在这个环境里安装 Codex CLI：

mamba create -n node nodejs -y
mamba activate node

如果你已经有可用的 Node.js 环境，可以直接跳到下一步。

使用 npm 安装 Codex CLI

OpenAI 官方文档给出的 npm 安装命令如下：

npm i -g @openai/codex

安装完成后直接运行：

codex

第一次启动时，Codex 会提示登录。官方也给出了升级命令：

npm i -g @openai/codex@latest

如果你只是想先确认 CLI 是否已经可用，最直接的方式就是运行 codex 看是否能进入交互界面。

登录方式

Codex 官方支持两种主要认证方式：

  1. 使用 ChatGPT 账号登录，适合日常交互式使用。
  2. 使用 API key 登录，适合按量计费和自动化场景。

使用 ChatGPT 登录

对 CLI 来说，默认登录路径是 ChatGPT 登录。运行 codex 或显式执行下面的命令后，Codex 会打开浏览器完成登录流程：

codex login

这种方式更适合个人日常使用，因为它直接走 ChatGPT 账号授权流程。

使用 API key 登录

如果你更关心脚本化、CI/CD 或明确的 API 计费路径，可以改用 API key。官方建议把 API key 用在程序化工作流中，而不是写死在配置文件里。

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key

无图形界面环境

如果是在远程服务器、无浏览器环境或者本地回调被网络策略拦截，可以使用设备码登录：

codex login --device-auth

配置文件位置与优先级

Codex 的用户级配置文件位于 ~/.codex/config.toml。如果希望只对某个仓库生效，可以在项目中添加 .codex/config.toml。

官方文档给出的配置优先级从高到低是：

  1. CLI 参数和 --config 覆盖。
  2. --profile <name> 指定的 profile。
  3. 项目级 .codex/config.toml。
  4. 用户级 ~/.codex/config.toml。
  5. 系统级配置。
  6. 内置默认值。

需要注意的是，一些与机器本地环境强绑定的键不适合放在项目级配置里。像 model_provider、model_providers、profiles、openai_base_url 和 chatgpt_base_url 这类字段，官方明确要求放在用户级配置中。

一份适合日常使用的配置

如果你主要是在本机交互式写代码，下面这份配置已经够用：

model = "gpt-5.5"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

cli_auth_credentials_store = "keyring"

[projects."/path/to/project"]
trust_level = "trusted"

这份配置的含义很直接：

  • model 指定默认模型。官方示例给大多数用户推荐的是 gpt-5.5。
  • model_reasoning_effort 控制默认推理强度，可选值包括 minimal、low、medium、high 和 xhigh。
  • plan_mode_reasoning_effort 控制计划模式下的推理强度，适合在 /plan 时单独拉高。
  • approval_policy = "on-request" 表示由 Codex 决定何时向你申请批准，适合多数交互式场景。
  • sandbox_mode = "workspace-write" 表示允许在当前工作区写文件，但不是完全放开机器权限。
  • web_search = "cached" 表示默认启用缓存型网页搜索；如果要查最新资料，可以临时改成 --search 或把配置改成 live。
  • cli_auth_credentials_store = "keyring" 表示尽量把登录凭据放进系统密钥链，而不是纯文件。
  • trust_level = "trusted" 表示把这个仓库标记为可信项目，这样项目级 .codex/ 配置、rules 和 hooks 才会生效。

配置项详解

下面这些字段是最常用、也最值得理解的。

model

model 决定 Codex 默认调用哪个模型。OpenAI 官方示例里推荐大多数用户使用 gpt-5.5；如果你更想显式指定编码导向模型，也可以改成例如 gpt-5.3-codex。

model = "gpt-5.5"

model_provider

model_provider 指向 [model_providers] 中的某个 provider id。默认 provider 是 openai。

model_provider = "openai"

如果你没有自建代理、Azure 或本地模型需求，通常不需要改它。

model_reasoning_effort

这个字段控制模型的推理强度，适合在速度和深度之间做平衡。

model_reasoning_effort = "medium"

一般可以这样理解：

  • low 或 medium 适合日常改代码、解释报错、补文档。
  • high 或 xhigh 更适合复杂重构、跨文件问题定位和方案分析。

plan_mode_reasoning_effort

这是计划模式专用的推理强度覆盖项。也就是说，平时对话可以用 medium，但在 /plan 阶段单独切到 high。

plan_mode_reasoning_effort = "high"

approval_policy

官方支持三种主模式：

  • untrusted：只自动执行已知安全的只读命令，其他操作更谨慎。
  • on-request：由 Codex 决定何时请求批准。
  • never：尽量不询问，风险最高。
approval_policy = "on-request"

如果是个人机器上的正常开发工作流，on-request 通常最稳妥。

sandbox_mode

这个字段控制 Codex 执行命令时的沙箱范围：

  • read-only
  • workspace-write
  • danger-full-access
sandbox_mode = "workspace-write"

通常建议从 workspace-write 起步，不要一开始就切到 danger-full-access。

default_permissions

新权限体系可以用 default_permissions 指向命名权限配置，官方内置了：

  • :read-only
  • :workspace
  • :danger-full-access
default_permissions = ":workspace"

官方文档特别提醒，不要把这套权限配置和旧式的 sandbox_mode 混着用。二选一即可。

web_search

Codex 自带第一方网页搜索工具，顶层配置支持：

  • disabled
  • cached
  • live
web_search = "cached"

如果你查的是版本更新、价格、新闻或最近发布内容，改成 live 更合适。

review_model

如果你经常在交互界面里使用 /review，可以单独给 review 指定模型：

review_model = "gpt-5.5"

不配置时，默认沿用当前会话模型。

cli_auth_credentials_store

这个字段决定 CLI 如何保存登录凭据：

  • file
  • keyring
  • auto
cli_auth_credentials_store = "keyring"

如果本机系统支持密钥链，优先用 keyring 或 auto 更合理。

自定义 provider 的正确写法

原始草稿里把真实密钥直接写进 TOML，这种方式不应该继续使用。官方给出的思路是：

  1. 如果底层仍然使用 OpenAI 身份认证，就设置 requires_openai_auth = true。
  2. 如果底层需要单独的 provider key，就设置 env_key = "YOUR_ENV_VAR"。
  3. wire_api 目前只支持 responses。

场景一：代理后端仍然走 OpenAI 登录

model = "gpt-5.3-codex"
model_provider = "proxy-openai"

[model_providers.proxy-openai]
name = "OpenAI Proxy"
base_url = "https://your-proxy.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

这种写法的重点是：既然已经使用 OpenAI 认证，就不要再写 env_key，因为官方文档明确说明 requires_openai_auth = true 时会忽略 env_key。

场景二：第三方兼容端点使用环境变量认证

model = "gpt-5.3-codex"
model_provider = "compatible-api"

[model_providers.compatible-api]
name = "Compatible API"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "COMPATIBLE_API_KEY"
env_key_instructions = "export COMPATIBLE_API_KEY=..."

这里的 env_key 写的是环境变量名，不是密钥本身。

常用方法

Codex 真正常用的不是“装完能启动”，而是下面这些操作。

进入交互式会话

最常见的用法就是直接启动：

codex

如果启动时顺便给一句任务，也可以这样写：

codex "Explain this repository structure"

附带图片一起提问

CLI 支持把截图或设计图一起传给 Codex：

codex -i screenshot.png "Explain this error"

多张图片也可以一起传：

codex -i img1.png -i img2.jpg "Summarize these diagrams"

查询最新网页信息

官方文档说明，Codex CLI 默认可以使用缓存搜索；如果你需要最新信息，可以显式开启 live web search：

codex --search "Check the latest release notes for this library"

非交互脚本化运行

如果要把 Codex 接进脚本或流水线，核心命令是 codex exec：

codex exec "summarize the repo structure"

如果下游程序要消费结构化事件流，可以输出 JSON Lines：

codex exec --json "summarize the repo structure" | jq

还可以用 JSON Schema 限定最终输出格式，这对自动化很实用。

续跑上一次任务

非交互任务跑到一半后，如果你想接着上一轮继续做，可以使用 resume：

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

Git 仓库保护

官方文档说明，codex exec 默认要求在 Git 仓库内运行，以降低误操作风险。只有在你明确知道环境安全时，才建议跳过这个检查：

codex exec --skip-git-repo-check "summarize files in this directory"

交互模式下最值得记住的 slash commands

下面这些命令最常用：

  • /model：切换模型和推理强度。
  • /plan：先让 Codex 给出计划，再决定是否进入执行。
  • /permissions：动态调整当前会话的审批和权限级别。
  • /review：让 Codex 检查当前工作区改动，优先指出风险和遗漏测试。
  • /diff：查看当前工作树的变更。
  • /mcp：检查本次会话可用的 MCP 工具。
  • /status：查看当前模型、权限、上下文容量等状态。
  • /theme：切换终端高亮主题。

一个更稳妥的使用建议

如果你刚开始用 Codex，建议先采用下面这套组合：

model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

这套配置的特点是：

  • 模型能力足够强。
  • 推理强度不过高，响应速度更平衡。
  • 允许写工作区，但不会默认放开整台机器。
  • 大部分危险动作仍然会停下来让你确认。

等你熟悉自己的工作流后，再去细调 plan_mode_reasoning_effort、review_model、profiles 和自定义 provider。

参考链接

Reference in New Issue View Git Blame Copy Permalink