Codex CLI 0.171.0:默认 GPT-6.2 Sol、TUI 工作区与远程执行指南
Codex CLI 0.171.0 将 GPT-6.2 Sol 设为默认目录模型,默认开启分栏 TUI 工作区,新增 codex exec --remote <ADDR> 与 /rc,并在切换工作目录时保留权限配置。本文帮助你核对生效模型 ID、切回 GPT-6.2 Astra 或配置 BetterToken 等自定义 API 供应商、按需关闭工作区,并确认远程执行前提。
本文内容

升级到 Codex CLI 0.171.0(2026 年 11 月 20 日发布)后,模型目录会将 gpt-6.2-sol 设为默认选项,同时默认开启分栏 TUI 工作区。这会直接影响未在 config.toml 中固定 model 的开发者、用脚本调用 codex exec 的团队,以及将 Codex 接入自定义 API 供应商的用户。如需继续使用 Astra,可在 config.toml 中固定 model = "gpt-6.2-astra";如需恢复单栏终端界面,可运行 codex features disable tui_workspace;如需按量计费调用 GPT-6.2 API,可按下方步骤完成配置。
在 Codex CLI 0.171.0 中运行 GPT-6.2 Sol 与 Astra 的接入方式
修改配置前,先确定 Codex 使用哪种鉴权与计费方式调用 GPT-6.2。不同的登录方式决定了可用的模型 ID,也决定了 Codex 云端任务与 /rc 远程控制等 ChatGPT 专属功能是否可用。
| 接入方式 | 账号与鉴权 | 计费单位 | Codex 0.171.0 支持范围与限制 | 适用场景 |
|---|---|---|---|---|
ChatGPT 订阅(codex login) | 通过浏览器登录 ChatGPT 账号 | 套餐使用额度(本地消息与云端对话共享) | 支持 Codex 云端功能与 /rc 远程控制;ChatGPT Pro 200 支持搭配 Sol 使用 Ultrafast | 已有符合条件的 ChatGPT 套餐,且需要云端任务或远程控制功能 |
| OpenAI API 直连 | OpenAI Platform 账号 + API 密钥 | 每 1M tokens(USD) | 支持 gpt-6.2-sol 与 gpt-6.2-astra;不含云端功能,且 API 密钥鉴权下无法使用 /rc 远程控制 | 需要 OpenAI 官方直连计费与 API 组织级数据策略 |
| BetterToken API 网关 | BetterToken 账号 + API 密钥 | 按模型计费单位从余额按量扣费 | 通过 OpenAI Responses 协议(https://www.bettertoken.ai/v1)上架 gpt-6.2-sol 与 gpt-6.2-astra;充值付费余额不按月清零 | 希望无需 ChatGPT 订阅,以按量计费方式接入多模型 API |
使用 BetterToken 配置 Codex CLI 0.171.0
BetterToken 是一个提供按量计费的多模型 API 接入层,并非 OpenAI 官方产品。截至 2026-11-21,BetterToken 已在其实时价格页面上架 gpt-6.2-sol 与 gpt-6.2-astra,均支持 OpenAI Responses 协议(https://www.bettertoken.ai/v1)。如需了解 Codex 兼容性概览,可查阅 Codex API 接入说明。
注册 BetterToken 账号后,前往 BetterToken 控制台创建自己的 API 密钥。在 auth.json 中启用基于文件的 API 密钥鉴权会替换官方 ChatGPT 登录,因此 /rc 远程控制和 ChatGPT Pro 200 的 Ultrafast 模式等 ChatGPT 专属功能在该模式下不可用。如果你想在接入第三方供应商的同时保留官方 ChatGPT 登录,请勿直接编辑 auth.json,而是参考 BetterToken 的保留官方登录配置指南。
编辑配置文件前,请先完全退出 Codex CLI 与 Codex App,因为两个客户端共用同一 Codex 目录下的 config.toml 与 auth.json(若设置了 $CODEX_HOME 则使用该目录,否则 macOS/Linux 默认为 ~/.codex,Windows 默认为 %USERPROFILE%\.codex;客户端差异可参考 Codex CLI、Codex App 与 VS Code 扩展对比)。请先将当前生效目录中的 config.toml 与 auth.json 备份到安全位置;若缺少 config.toml,请先创建该文件。
在 config.toml 中,原地更新已有的根级键 model_provider、model 或 cli_auth_credentials_store,并在任意 [tables] 之前仅补充缺失的键。如果文件中已存在 [model_providers.bettertoken],请将以下字段合并到该表中,不要重复添加表头;如果不存在,则参照 BetterToken Codex 配置指南 添加下表,并保留其余无关配置不变:
model_provider = "bettertoken"
model = "gpt-6.2-sol"
cli_auth_credentials_store = "file"
[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
若希望默认使用 Astra,只需将 model 改为 "gpt-6.2-astra"。采用文件鉴权时,请从 [model_providers.bettertoken] 中移除 env_key 与 experimental_bearer_token。
接下来,在同一个生效 Codex 目录中写入 auth.json。在装有 Bash 和 Python 3 的 macOS 或 Linux 环境下,可运行下方命令以无回显方式输入密钥;若输入被取消或为空,脚本会直接中止且不改动 auth.json,写入前会先以仅所有者可读写的 0600 权限创建替换文件。原生 Windows 用户请按照 BetterToken Codex 配置指南 中的 auth.json 文件鉴权步骤操作,在当前 Codex 目录($CODEX_HOME 或 %USERPROFILE%\.codex)中将 auth_mode 设为 "apikey",并将 OPENAI_API_KEY 设为你的密钥:
CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_DIR"
if IFS= read -rs BETTERTOKEN_API_KEY && [ -n "$BETTERTOKEN_API_KEY" ]; then
export BETTERTOKEN_API_KEY CODEX_DIR
python3 -c 'import json, os, pathlib, tempfile
dir_path = pathlib.Path(os.environ["CODEX_DIR"])
fd, tmp_name = tempfile.mkstemp(prefix=".auth.", dir=dir_path)
try:
os.fchmod(fd, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as fh:
json.dump({"auth_mode": "apikey", "OPENAI_API_KEY": os.environ["BETTERTOKEN_API_KEY"]}, fh, indent=2)
fh.write("\n")
os.replace(tmp_name, dir_path / "auth.json")
except Exception:
os.unlink(tmp_name)
raise'
unset BETTERTOKEN_API_KEY
else
echo "API key entry cancelled or empty; auth.json was not changed." >&2
fi
如果本机已安装 Node.js 且希望自动完成配置,BetterToken Codex 文档 也提供了 macOS 与 Linux 的一键脚本 curl -fsSL "https://www.bettertoken.ai/install-codex-provider.sh" | bash,以及面向 Windows 的 PowerShell 安装脚本(install-codex-provider.ps1)。启动 Codex 前,请将生成的 config.toml 与 auth.json 与上方手动配置逐项核对。
配置完成后,启动一个新的 codex 会话,运行 /status 确认 Model(gpt-6.2-sol)与 Model provider 行显示无误,再发送一条简短提示词。收到正常回复即说明 Responses 连接可用。
如果你更倾向于使用 OpenAI 官方途径,可运行 npm install -g @openai/codex@0.171.0 安装或升级到 0.171.0(或直接在已有的 0.171.0 环境操作),并通过 codex --version 确认输出包含 0.171.0。随后运行 codex login 使用 ChatGPT 订阅登录,或参照 OpenAI Codex 鉴权文档 使用 OpenAI API 密钥登录。正在对比订阅额度与 API 计费的团队,可参考 ChatGPT 与 Codex 共享额度规划。
确认 GPT-6.2 Sol 默认模型并切换回 Astra 或其他模型
在 PR #62106 中,Codex CLI 0.171.0 将 gpt-6.2-sol 和 gpt-6.2-astra 加入内置目录、Amazon Bedrock 与 Vertex 目录,并将 gpt-6.2-sol 设为目录默认选项(priority: 1)。同一改动还将 gpt-6.1-sol 在目录中的上下文窗口提升至 500,000 tokens。
在 0.171.0 内置目录(codex-rs/models-manager/models.json)中,gpt-6.2-sol 标注的上下文窗口为 500,000 tokens,gpt-6.2-astra 为 272,000 tokens,两者的 default_reasoning_level 均为 "low"。根据截至 2026-11-21 的 OpenAI API 官方文档,GPT-6.2 Sol 与 GPT-6.2 Astra 均支持 1,050,000 tokens 上下文窗口(最大输入 922,000,最大输出 128,000),且均拒绝将推理强度设为 none。
升级后当前生效模型是否会改变,取决于你的配置与所用目录(见 codex-rs/models-manager/src/manager.rs):
- 若
config.toml中未设置model,get_default_model会从当前可用目录中选取默认值(default_model_from_available)。当会话使用 0.171.0 内置目录时,该默认值就是gpt-6.2-sol。 - 若用户级
config.toml(或受信任项目的.codex/config.toml)中显式指定了model,Codex 会继续沿用该模型,除非开启了供应商回退机制且原模型不可用。
运行以下命令可查看当前已安装二进制文件内置的模型目录:
codex debug models --bundled
在交互式 TUI 会话中输入 /status,即可查看 Model 行(若配置了供应商,也会显示 Model provider 行)。若不想修改 config.toml 而临时切换模型,可在 TUI 中执行 /model,或在启动命令中传入 --model / -m:
codex -m gpt-6.2-astra
codex exec -m gpt-6.2-astra "Audit the auth middleware for race conditions"
如需将 gpt-6.2-astra(或旧型号如 gpt-6.1-sol)设为持久默认模型,请在 $CODEX_HOME/config.toml(默认为 ~/.codex/config.toml)文件内将 model = "gpt-6.2-astra" 设为根级键,放在所有 TOML 表([tables])之前(更新已有项或新增该键),然后重启 Codex。
截至 2026-11-21,OpenAI 官方公布的 Standard API 文本 token 标价(输入不超过 272K tokens 时)为:GPT-6.2 Sol 输入 $2 / 输出 $10(每 1M tokens),GPT-6.2 Astra 输入 $8 / 输出 $40(每 1M tokens)。两款模型在单次请求输入超过 272K tokens 时,整次请求的输入与缓存单价翻倍,输出单价为短上下文费率的 1.5 倍。日常编码可优先使用 Sol,遇到需要更深入推理的跨文件任务时再切到 Astra;更完整的选型框架可参考 GPT-6 Astra、Sol 与 Luna 选型指南。另外,搭配 Sol 使用的 Ultrafast 模式属于 ChatGPT Pro 200 订阅特性(在 OpenAI API 上,Ultrafast 按 Standard 费率的 3 倍计费,该费率适用至 2027 年 2 月 28 日当天,以太平洋时间为准),并非自定义网关的默认选项。
自定义供应商场景下目录名称与实际模型 ID 的对应关系
Codex 在模型选择器中展示 GPT-6.2-Sol 和 GPT-6.2-Astra 这类易读名称,但各家供应商实际要求的接口模型 ID 并不相同。
| 供应商 | GPT-6.2 Sol ID | GPT-6.2 Astra ID | 说明 |
|---|---|---|---|
| OpenAI API(直连) | gpt-6.2-sol | gpt-6.2-astra | 与 Codex 内置目录标识一致 |
BetterToken(https://www.bettertoken.ai/v1) | gpt-6.2-sol | gpt-6.2-astra | 截至 2026-11-21 已验证支持 OpenAI Responses(openai-response),同时支持 openai 与 anthropic 端点类型 |
| Amazon Bedrock | openai.gpt-6.2-sol | openai.gpt-6.2-astra | 目录规范化逻辑同时识别 Bedrock Runtime 跨区域 ID global.openai.gpt-6.2-astra 与 us.openai.gpt-6.2-astra |
| Google Vertex AI | gpt-6.2-sol | gpt-6.2-astra | 已通过 PR #62106 加入内置 GCP 目录 |
其他自定义 model_provider | 由供应商定义 | 由供应商定义 | 需在 config.toml 中显式固定精确的 model = "..." |
当 config.toml 省略 model 时,Codex 会从当前生效目录解析默认值,而不会自动推测自定义网关的命名规则。如果自定义 model_provider 使用带厂商前缀或别名的模型 ID,且与内置目录标识不同,请求可能会失败;此时需要在 config.toml 文件内将 model = "..." 显式设为根级键,放在所有 TOML 表之前并填入网关要求的精确模型 ID(切勿写在 [projects."<path>"] 等表内,该表仅用于存放项目 trust_level)。
TUI 工作区默认开启:界面变化与关闭方法
PR #61352 将 tui_workspace 特性升级为 Stable 并设为 default_enabled: true。升级后,终端主对话旁会新增侧边栏工作区:
- 文档预览(PR #61888、PR #61889):点击对话记录中的文件链接后,侧边栏会以只读 Markdown 标签页渲染内容,支持搜索、键盘与鼠标选中、离线复制 Markdown,以及用
Tab/Shift+Tab切换链接并按Enter打开。 - 图片预览(PR #61919):PNG、JPEG、GIF 与 WebP 链接会在侧边栏中显示图片预览,并附带格式与尺寸标签;当终端不支持图形渲染时自动回退为文本显示。已生成并保存的图片会显示在助手回复之后,并带有可点击的
Generated image标签。 - 子代理记录(PR #62157):在侧边栏选中某个子代理时,会在主对话旁打开只读查看标签页,而不会覆盖当前主会话。
关闭侧边栏视图的方式取决于当前焦点所在的区域:
- 焦点在文档预览中时,按
Esc即可关闭预览。 - 焦点在子代理记录查看器中时,按
Esc会返回子代理列表并保持原代理选中;如需关闭该标签页,请使用侧边栏的关闭按钮或关闭快捷键。
如果只想在单次会话中关闭 TUI 工作区,可在启动 Codex 时附加 --disable 参数:
codex --disable tui_workspace
如需在 $CODEX_HOME/config.toml 中永久关闭 tui_workspace,可运行:
codex features disable tui_workspace
或者手动在 $CODEX_HOME/config.toml 中写入以下配置:
[features]
tui_workspace = false
重新启动一个新的 codex 会话,即可确认工作区侧边栏保持关闭。关闭 tui_workspace 会一并停用侧边栏及其全部预览标签页。
远程执行对比:codex exec --remote 与 TUI 的 /rc、/remote
Codex CLI 0.171.0 新增了两项用途不同的远程功能:
codex exec --remote <ADDR>面向已运行的codex app-server,可新建线程或按 UUID 恢复已有线程,并在该线程中执行一个非交互回合。/rc(别名/remote)用于在 TUI 内部管理受控本地后台服务的设备远程控制。
codex exec --remote <ADDR> 的语法、传输方式与限制
PR #61707 允许 codex exec 连接到现有的应用服务端,支持的地址格式包括 ws://host:port、wss://host:port、unix://(默认 Unix 套接字)或 unix://PATH。
本机或 SSH 端口转发场景(回环地址): 监听在 ws://127.0.0.1:PORT 的明文 WebSocket 服务仅适用于本机访问或 SSH 端口转发隧道。先在该主机启动服务端:
codex app-server --listen ws://127.0.0.1:4500
随后在同一主机上(或通过转发了 4500 端口的 SSH 隧道)运行 codex exec:
codex exec --remote ws://127.0.0.1:4500 "Run the test suite and summarize failures"
跨主机或 CI 构建节点场景(带鉴权的 wss://): 在灰度推广期间,非回环地址的 WebSocket 监听默认允许未鉴权连接,且 codex app-server 的 WebSocket 监听地址只接受 ws://(详见 OpenAI app-server 文档)。向其他机器或 CI 构建节点暴露该服务前,务必在服务端启用 WebSocket 鉴权(优先使用 --ws-token-file,避免在命令行直接传入明文令牌),并在前端配置 TLS 终止代理,使客户端通过 wss:// 连接:
# On the app-server host (behind a TLS reverse proxy exposing wss://remote-host:4500)
codex app-server --listen ws://127.0.0.1:4500 \
--ws-auth capability-token \
--ws-token-file /absolute/path/to/app-server-token
在客户端或 CI 构建节点上,通过 --remote-auth-token-env 传入存放对应持有者令牌的环境变量名。在人类可读输出模式下,codex exec --remote 会向 stderr 打印 thread id: <UUID>;启用 --json 时,则会输出包含 thread_id 的 thread.started JSONL 事件("type": "thread.started")。后续恢复该线程时,将首次运行返回的 UUID 填入即可:
if IFS= read -rs CODEX_REMOTE_TOKEN && [ -n "$CODEX_REMOTE_TOKEN" ]; then
export CODEX_REMOTE_TOKEN
# Start a new noninteractive turn (capture thread_id from the thread.started JSONL event)
codex exec --remote wss://remote-host:4500 \
--remote-auth-token-env CODEX_REMOTE_TOKEN \
--json "Run the test suite and summarize failures"
# Resume syntax example: replace <THREAD_UUID> with the thread_id returned above
codex exec --remote wss://remote-host:4500 \
--remote-auth-token-env CODEX_REMOTE_TOKEN \
resume <THREAD_UUID> "Fix the failing parser test"
unset CODEX_REMOTE_TOKEN
else
echo "Remote token entry cancelled or empty." >&2
fi
--remote 和 --remote-auth-token-env 既可放在 exec 之前,也可放在 exec 之后;若两处传入冲突的端点地址,命令会报错 `codex exec` received conflicting remote server endpoints。0.171.0 源码(codex-rs/exec/src/remote.rs)中还有三项严格限制:
- 代理配置由服务端掌控: 在客户端传入代理覆盖参数(例如
-m/--model、-s/--sandbox、-C/--cd、-c覆盖项、-i/--image、-p/--profile、--add-dir、--output-schema、--ephemeral或--worktree)都会报错"--remote currently supports only prompt, resume by UUID, and output options; configure the agent on the server"。 - 仅支持按 UUID 恢复:
exec --remote resume拒绝--last、--all、--image或非 UUID 目标,并报错"remote resume requires a thread UUID"。 - 禁止并发回合: 如果目标线程当前已有正在运行的回合,请求会失败并报错
"remote thread already has an active turn"。
TUI 中的 /rc 与 /remote
PR #62121 在 TUI 内新增了 /rc(以及别名 /remote),用于开启或关闭受控本地后台服务的远程控制功能。开启时,菜单会校验 remoteControlEnabled 是否已成功写入 app-server-daemon/settings.json 以便下次重启生效,若保存失败会直接提示;选择 Add device 可显示手动配对码。即使当前正在查看云端会话,也可以打开 /rc,但其变更仅作用于本地会话。
使用 /rc 前请先确认三项前提条件:
- 受控本地后台服务必须正在运行,否则远程控制操作会报错
"Remote control requires the local background server."。 - 必须使用 ChatGPT 账号登录;API 密钥鉴权会被拒绝,并报错
"Sign in with ChatGPT to manage remote control."。 - 企业管理员可在受管
requirements.toml中设置allow_remote_control = false以全局禁用该功能,此时会报错"Remote control is disabled by managed requirements."。
在 TUI 之外(例如通过 SSH 操作服务器时),可按 OpenAI CLI 参考文档 使用 codex remote-control start、codex remote-control stop 和 codex remote-control pair 进行管理。
切换工作目录后的权限配置保留及其他 0.171.0 修复
在 0.171.0 中,切换工作目录后当前生效的权限配置会保持完整。此前在 rust-v0.170.0 里,如果仅变更工作目录且启用了可重绑定的项目根目录写入策略,Codex 可能会依据旧版沙箱策略重新生成旧式权限配置(见 codex-rs/core/src/session/session.rs)。
PR #61195 移除了该旧版重建分支,使当前权限配置、生效选择以及配置中的工作区根目录得以保留,同时将运行时工作区根目录更新到新目录。在该 PR 的工作区写入回归测试中,新工作区内的普通文件仍可正常写入,而对 .git/config 和原工作区的写入继续被拒绝;自定义命名配置也会继续按各自设定的根目录与规则生效。如果团队为依赖安装维护了受限网络或文件系统策略,可对照 Codex 沙箱权限配置指南 复核域名与写入规则。
rust-v0.171.0 还包含三项有助于减少日常 CLI 摩擦的修复: