Codex 设备安装

让 AI 直接参照本页，为工作区已连接设备完整安装并验证 Codex。

完整目标

安装 Codex 必须完成以下结果：

ChatGPT desktop app：在用户设备上安装官方 OpenAI 桌面应用，并在其中启用/打开 Codex。
Codex 终端：配置百积木路由、授权、本地终端能力、计费归属和本地认证文件。
验收验证：App 已安装、能启动、有可见窗口；终端、路由、账号状态和归属验证通过。

只完成 App、只写配置、只通过路由请求、只看到进程存在，都不能报告安装成功。

执行规则

AI 执行本流程时必须遵守：

本页和本页引用的 /scripts/codex-device-install/ 脚本是 Codex 设备安装的唯一执行规范。不要搜索、安装、加载或执行任何 Codex 设备安装市场技能；不要使用模型记忆里的旧安装步骤覆盖本页。
设备固定为运行百积木客户端的本机，工作区固定为客户端当前已授权工作区；不要向用户确认设备、工作区或平台项目。
先检查设备是否同时暴露本地命令执行能力 shell.exec、shell.startExecution 和 shell.queryExecution。缺少任一方法都停止，并明确提示用户授权对应能力。
默认使用百积木受控缓存，并校验 SHA256。Windows App 默认安装完整 MSIX 包，不默认走 winget / Microsoft Store，也不默认运行 Store bootstrap installer；只有在产品策略明确允许并设置 fallback 环境变量时，才尝试官方源。
默认模型使用 gpt-5.6-sol。不要使用裸 gpt-5.6 作为默认值；当前路由计费映射要求使用明确的模型键。需要切换 Sol/Terra/Luna 时，由平台在执行脚本时设置 CODEX_MODEL。
不向用户索要、展示、复制或输出 API Key。
长时间下载、安装或启动任务要用后台执行加轮询，不要依赖单次长阻塞命令。
Windows 多行 PowerShell 不要把完整脚本文本拼进 -Command。优先调用文档里的脚本 URL；确实需要临时多行脚本时，命令参数只放解释器，例如 ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "-"]，脚本文本通过 stdin 传入，避免 JSON/Relay/Windows 命令行转义和长度限制。
正文只作为流程索引；执行到具体平台或阶段时，再读取对应脚本文件。
百积木本地 CLI token 由客户端/bridge-agent 在设备授权阶段写入 ~/.config/baijimu/auth.json。标准流程由 Codex Connector 精确选择当前工作区授权并创建工作区级 LLM credential；脚本也保留通过内置 baijimu llm-credential create 创建凭证的独立执行兼容路径。不走旧的 Codex 专用 Partner API 或 workspace-agent.createUserApiKey。
Codex Connector 从客户端接收当前 CODEX_WORKSPACE_ID，在本机签发工作区级 LLM credential，并通过权限受限的临时文件传给安装脚本。平台 projectId 与安装无关，不得要求用户选择或输入；有旧调用方传入时仅作为可选兼容上下文。
Windows 设备走“一体化快速路径”：Codex Connector 后台运行 windows-configure-terminal-and-login.ps1，传入当前工作区和权限受限的 LLM credential 文件。该脚本会从百积木受控缓存安装缺失的 ChatGPT desktop app、写入 Codex 终端凭证、完成 App API Key 登录、执行 router/CLI/smoke/窗口验证，并输出一份脱敏 JSON 结果。
macOS 设备同样走一体化快速路径：Codex Connector 后台运行 macos-configure-terminal-and-login.sh，传入当前工作区和权限受限的 LLM credential 文件。该脚本会从百积木受控缓存安装缺失的 ChatGPT desktop app 和 Codex CLI、写入 Codex 终端凭证、执行 router/CLI/smoke/窗口验证，并输出一份脱敏 JSON 结果。
所有安装、启动、可见窗口、终端健康检查、路由账号和归属验证通过后，才能报告成功。

标准流程

用户在百积木客户端安装 Codex Connector。
Bridge Agent 启动连接器，把客户端当前已授权的 workspaceId 传给 setupRetry；不再询问设备、工作区或平台项目。
连接器验证本机授权必须精确包含该工作区，签发工作区级 LLM credential，并通过私有临时文件交给当前系统的一体化脚本。
连接器轮询脚本状态，完成 App、CLI、路由、账号、smoke test 和窗口验收后返回 succeeded。
任一环节失败则在 Codex Connector 页面显示具体错误并允许重试，不能把仅下载或仅写配置报告为安装完成。

脚本索引

脚本按平台和阶段拆分。不要在读取本页时一次性加载所有脚本；只在执行到对应平台和阶段时打开对应文件。

阶段	脚本
macOS 设备检测	https://docs.baijimu.com/scripts/codex-device-install/macos-detect.sh
macOS 一体化安装、配置与验收	https://docs.baijimu.com/scripts/codex-device-install/macos-configure-terminal-and-login.sh
Windows 设备检测	https://docs.baijimu.com/scripts/codex-device-install/windows-detect.ps1
Windows App-only 安装	https://docs.baijimu.com/scripts/codex-device-install/windows-install-app.ps1
Windows 一体化安装、配置、登录与验收	https://docs.baijimu.com/scripts/codex-device-install/windows-configure-terminal-and-login.ps1

以下 macOS 分段脚本仅用于排障或兼容旧流程，不作为标准安装入口：

阶段	脚本
macOS App-only 安装	https://docs.baijimu.com/scripts/codex-device-install/macos-install-app-from-baijimu-cache.sh
macOS 仅配置 Codex 终端	https://docs.baijimu.com/scripts/codex-device-install/macos-configure-terminal.sh
macOS 仅重启与窗口验证	https://docs.baijimu.com/scripts/codex-device-install/macos-restart-and-verify-window.sh

Linux 当前不能完成 ChatGPT desktop app 桌面安装。目标设备是 Linux 时，停止完整安装流程并报告“当前平台无法完成 ChatGPT desktop app 安装”，不要只做终端配置后报告成功。

受控缓存与下载源

百积木受控缓存 manifest：

https://lowcode-common.oss-cn-beijing.aliyuncs.com/codex-artifacts/latest.json

manifest 中的 mirror_url 是百积木 OSS 缓存下载地址，不是设备本地文件地址。AI 需要把文件下载到设备临时目录，校验 SHA256 后再安装。

macOS 和 Windows 安装脚本都会把缓存文件下载到用户设备本地临时目录后再安装；不要直接把 mirror_url 当成本地路径，也不要要求用户手工下载。下载、校验、安装、配置和验证过程会以脚本进度列表显示在 shell 中，平台/AI 侧以最终 JSON 作为判断依据。

使用缓存前必须检查 manifest 中的：

上游 URL
文件名
SHA256
文件大小
同步时间或版本信息

当前 manifest 已确认包含，后续同步也必须至少持续覆盖。历史 codex-app-* 资产名用于兼容已发布脚本；上游内容应是当前官方 ChatGPT desktop app：

macOS Apple Silicon App：codex-app-aarch64-apple-darwin.dmg
macOS Intel App：codex-app-x86_64-apple-darwin.dmg
Windows x64 App 完整包：codex-app-windows-x64.msix
Windows ARM64 App 完整包：codex-app-windows-arm64.msix
macOS Apple Silicon CLI：codex-aarch64-apple-darwin.tar.gz
macOS Intel CLI：codex-x86_64-apple-darwin.tar.gz
Windows x64 CLI：codex-x86_64-pc-windows-msvc.exe.zip
Windows arm64 CLI：codex-aarch64-pc-windows-msvc.exe.zip

当前 manifest 未包含目标平台资源时，不要编造缓存地址。没有受控缓存或校验失败时，报告“百积木缓存暂未包含当前平台安装包”或“缓存校验失败”，并给出平台、架构、资源名和错误信息。

官方源只作为缓存缺失或产品策略要求时的来源参考。Windows 默认不要使用 winget，因为 Microsoft Store 源在国内网络下容易长时间卡住；确需回退时必须显式设置 CODEX_ALLOW_OFFICIAL_WINDOWS_INSTALLER_FALLBACK=1 或 CODEX_ALLOW_WINGET_FALLBACK=1。

macOS Apple Silicon App：https://persistent.oaistatic.com/codex-app-prod/ChatGPT.dmg
macOS Intel App：https://persistent.oaistatic.com/codex-app-prod/ChatGPT-latest-x64.dmg
Windows 官方 Store bootstrap installer：https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi
Windows Store：winget install --id 9PLM9XGG6VKS -s msstore

Windows Store bootstrap installer 只是 Microsoft Store 引导器，不是完整离线安装包，不能作为默认缓存安装资产。完整 Windows App 缓存必须是 Microsoft Store MSIX/AppX 包，当前产品是 9PLM9XGG6VKS 的 ChatGPT desktop app；安装脚本下载 .msix 后使用 Add-AppxPackage 安装并验证对应包和开始菜单入口。

不要直接让用户设备依赖第三方镜像、社区仓库、重新打包安装器，或任何没有上游来源和 SHA256 记录的文件。第三方解析源只能用于百积木受控同步任务获取 Microsoft Store 原始包；进入百积木 OSS manifest 后必须记录上游 URL、SHA256、文件大小和同步时间，并在设备侧校验后再安装。

Codex 终端配置

安装 Codex 必须完成 Codex 终端配置，包括百积木路由、用户授权、计费归属和本地认证写入。

设备授权完成后，bridge-agent 客户端会把当前工作区的百积木本地 CLI token 写入：

~/.config/baijimu/auth.json

标准 Connector 流程先创建工作区级 LLM credential，再通过权限受限的 CODEX_LLM_CREDENTIAL_FILE 传给脚本。独立执行脚本时，也可以使用本地授权态调用内置 CLI：

baijimu --json llm-credential create --workspace-id <workspaceId> --show-secret

CLI 会为当前认证用户和工作区创建受限的 LLM 凭证。脚本只在设备本机内存和权限受控的临时文件中接收该凭证，随后写入 Codex 自己的配置：

~/.codex/auth.json
~/.codex/config.toml

脚本不申请、不轮换、不管理百积木本地 CLI token。标准流程由 Codex Connector 创建一次工作区级 LLM credential，并以 CODEX_LLM_CREDENTIAL_FILE 传入；独立执行兼容路径由脚本调用内置 CLI 创建。两种方式都不会要求用户查看、复制或粘贴凭证。参数要求是：

workspaceId 必传，由 CODEX_WORKSPACE_ID 或 BAIJIMU_WORKSPACE_ID 提供。
projectId 可选；标准连接器流程不传，凭证按工作区归属。
agentConfigId 有则传入。
agentSessionId 有则传入。
sessionId 有则传入。

不要让用户手动提供 userId、百积木本地 CLI token、LLM 凭证或 API Key。脚本只能在设备本机使用这些敏感值完成凭证创建、Codex 配置、router/App 登录验证；敏感值不能输出到聊天、日志、截图、状态文件或最终 JSON 中。

连接器找不到共享授权文件、缺少工作区上下文，或共享授权文件里没有当前工作区凭证时必须停止；不要回退到第一份凭证，不要要求用户粘贴 key，也不要改用默认账号。

脚本默认写入：

model = "gpt-5.6-sol"

如平台需要显式选择模型，可在同一脚本进程里设置：

CODEX_MODEL=gpt-5.6-sol

固定使用百积木路由：

https://router.baijimu.com/api/claudecode/v1

macOS 执行安装、终端配置和验收时读取同一个一体化脚本。该脚本是幂等的；ChatGPT desktop app 或 Codex CLI 不存在时会自动从百积木受控缓存安装，已存在时会跳过安装：

https://docs.baijimu.com/scripts/codex-device-install/macos-configure-terminal-and-login.sh

Windows 执行终端配置和桌面 App API Key 登录时读取。该脚本是幂等一体化脚本；ChatGPT desktop app 不存在时会自动安装，已存在时会跳过安装：

https://docs.baijimu.com/scripts/codex-device-install/windows-configure-terminal-and-login.ps1

配置文件里的根级字段必须写在任何 TOML 表之前。保留已有的 [marketplaces.*]、[desktop]、[projects.*] 等无关配置。

Windows App 登录验证

Windows 上写入 auth.json 和 config.toml 只能说明 CLI/router 可能可用，不能说明桌面 App 已登录。

配置百积木路由后，必须启动 codex app-server 并完成 API Key 登录。成功必须同时满足：

account/login/completed success=true
account/updated authMode=apikey
account/read account.type=apiKey

如果窗口仍显示 Get started with Codex、Sign in with ChatGPT 或 Sign in to ChatGPT，不要报告安装成功。

App 启动与窗口验证

安装文件存在不等于完成。安装和终端配置完成后，必须重启 ChatGPT desktop app 并验证可见窗口。

macOS 执行 App 启动和窗口验证时读取同一个一体化脚本，不要额外拆分调用：

https://docs.baijimu.com/scripts/codex-device-install/macos-configure-terminal-and-login.sh

Windows 执行 App 登录和窗口验证时读取同一个一体化脚本，不要额外拆分调用：

https://docs.baijimu.com/scripts/codex-device-install/windows-configure-terminal-and-login.ps1

成功需要同时满足：

ChatGPT desktop app 已安装，并可打开 Codex。
App 能启动。
App 有可见窗口，或用户明确确认看到了 Codex 窗口。
Windows 配置路由后，桌面 App 账号状态是 apiKey。

如果 macOS lsappinfo 显示 windows=[ NULL ]，说明没有可见窗口。可以按脚本尝试打开项目目录后重新激活；仍没有窗口时，报告“ChatGPT desktop app 已启动但没有创建可见窗口”，并收集日志，不要报告成功。

最终验收

按层验证：

App 层：ChatGPT desktop app 已安装，能启动，有可见窗口，并可进入 Codex。
Windows 账号层：配置路由时，account/read.account.type 必须是 apiKey。
终端层：codex --version 通过，并执行一次小型 smoke test。
路由层：使用生成的用户 Key 调用 POST /responses 返回 HTTP 200。
归属层：服务端日志或平台追踪能确认请求归属到正确 userId 和 workspaceId；标准连接器安装不绑定平台项目。

最终回复只包含：

已完成的验收项。
阻塞项和下一步需要用户做什么。
不包含 API Key、token、完整密钥片段或敏感日志。

本页内容