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:默认 GPT-6.2 Sol、TUI 工作区与远程执行指南

升级到 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 IDGPT-6.2 Astra ID说明
OpenAI API(直连)gpt-6.2-solgpt-6.2-astra与 Codex 内置目录标识一致
BetterToken(https://www.bettertoken.ai/v1)gpt-6.2-solgpt-6.2-astra截至 2026-11-21 已验证支持 OpenAI Responses(openai-response),同时支持 openai 与 anthropic 端点类型
Amazon Bedrockopenai.gpt-6.2-solopenai.gpt-6.2-astra目录规范化逻辑同时识别 Bedrock Runtime 跨区域 ID global.openai.gpt-6.2-astra 与 us.openai.gpt-6.2-astra
Google Vertex AIgpt-6.2-solgpt-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)中还有三项严格限制:

  1. 代理配置由服务端掌控: 在客户端传入代理覆盖参数(例如 -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"。
  2. 仅支持按 UUID 恢复: exec --remote resume 拒绝 --last、--all、--image 或非 UUID 目标,并报错 "remote resume requires a thread UUID"。
  3. 禁止并发回合: 如果目标线程当前已有正在运行的回合,请求会失败并报错 "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 摩擦的修复:

  • 切换会话保留未发送内容(PR #61216):切换或恢复会话时,草稿、排队中的后续提示以及被中断的输入会继续保留在各自所属线程中。
  • 修复无刷新令牌的企业 MCP 登录(PR #62129):企业身份提供商签发 ID 令牌、但未同时签发刷新令牌时,MCP 鉴权会失败;0.171.0 已修复此问题。
  • 活跃回合引导与审批修复(PR #61820、PR #61801):在活跃回合中进行引导时,聚合差异视图会保留早先的修改;延迟到达的完成事件也不再取消新回合的审批。
BetterToken · 企业采购
企业专属价
支持开发票对公转账 / 支付宝 / 微信支付全系列文本 / 编程、图像、视频模型
文本 / 编程
图像
视频
专属技术支持领取企业折扣价目表 →