从零开始 · 第二篇
在 Windows 上安装
Codex
从打开 PowerShell,到让 AI 创建第一个文件。
照着 8 步做,把 Codex CLI 接入你的 SHUN API。
核对日期: · 预留约 30–60 分钟,下载时间取决于网络。
开始前准备好
本篇使用 PowerShell → Node.js / npm → Git → Codex CLI。Codex 是 OpenAI 的终端编程工具,可按中文要求创建文件;不需要先装编辑器或 WSL。
推荐 Windows 11。近期更新的 Windows 10 1809+ 为尽力支持。按 Win + R,输入 winver 查看版本;在「设置 → 系统 → 关于」查看 x64 / ARM64 系统类型。[5]
本篇使用 SHUN API 额度,不走 ChatGPT 登录。安装成功后,还要完成第 8 步的真实文件检查。
下载页使用官网真实截图;SHUN 截图使用本站界面和演示数据。点击图片可放大。
打开 PowerShell
按 Win 键,搜索 PowerShell,普通打开「Windows PowerShell」,不要选 ISE。看到 PS C:\Users\…> 后,后面的安装命令都粘贴到这里。
安装 Node.js 和 npm
npm 随 Node.js 一起安装,稍后用它下载 Codex。[4]
① 下载安装包
- 打开 Node.js 官方下载页,在图中 ① 版本框选 Node.js 24 LTS。LTS 表示长期支持版。[2]
- 向下滚过 Docker 命令框,找到 Or get a prebuilt Node.js® for。按图中 ② 选 Windows,③ 选电脑对应的 x64 或 ARM64。
- 点击 ④ Windows Installer (.msi) 下载安装包,不选旁边的 Standalone Binary (.zip)。
② 安装并重开终端
- 双击下载的
.msi,接受许可后点 Next,安装位置保持默认。 - Custom Setup 保留 npm package manager 和 Add to PATH;PATH 让终端找到程序。
- Tools for Native Modules 的额外工具无需勾选。点 Install → Finish;Windows 若询问权限,确认是刚下载的官网安装包。
- 关闭全部 PowerShell / Windows 终端窗口,从开始菜单重新打开,再运行:
node --version
npm.cmd --version例如 v24.x.x 和 11.x.x;两个版本号不需要相同。
为什么写 npm.cmd?
PowerShell 可能优先找到受脚本策略限制的 npm.ps1。本篇使用 npm.cmd 和 codex.cmd,无需修改执行策略。
安装 Git for Windows
Git 用来记录代码修改,Git Bash 是它附带的命令窗口;本篇仍在 PowerShell 操作,无需 GitHub 账号。[3]
- 打开 Git 官方 Windows 下载页,找到 Other Git for Windows downloads → Standalone Installer。
- 普通 Intel / AMD 电脑选图中 ① Git for Windows/x64 Setup;ARM 电脑选 ② ARM64 Setup。不选 Portable。
- 双击下载的
.exe,阅读许可,目录和组件保持默认。 - 在 Adjusting your PATH environment 选择 Git from the command line and also from 3rd-party software,让 PowerShell 和 Codex 找到 Git。
- 其余默认,点 Install → Finish。关闭全部终端,重开 PowerShell 后运行:
git --versiongit version …。在开始菜单搜索 Git Bash,能打开即表示附带环境也已装好;检查后关闭。
用 npm 安装 Codex
运行下面一行。-g 表示全局安装,@latest 选择安装时的最新版。[1]
npm.cmd install -g @openai/codex@latest等到重新出现 PS C:\…>。出现 npm error 时先看排错表;npm 自身的更新提醒不等于失败。关闭全部终端,重开后检查:
codex.cmd --versioncodex-cli 和版本号。这是终端工具,没有桌面图标也正常。先完成第 6 步配置,再首次启动聊天。
以前装过 Codex?
先用 Get-Command codex -All 核对安装位置,按原方式更新。保留原生版时,下文 codex.cmd 改为 codex。本篇采用当前独立 profile 语法;0.134.0 是 profile 变更点,不是整个模板的最低版本承诺。已有配置先按第 6 步说明核对,保留会话和认证文件。[6]
准备用户 key 和可用模型
向管理员领取个人用户 key,确认模型支持 Responses、流式回复和工具调用。不要填写管理员密钥、登录密码或「GPT」这样的品牌名。[7]
- 打开 SHUN API 控制台,粘贴用户 key,点「进入」,检查账号状态和额度。
- 进入模型价格,复制管理员确认可用的完整模型 ID。
本篇模板用于管理员确认当前 Codex 已识别、无需额外模型目录的模型。自定义别名须先由管理员提供配套 catalog 配置;单有 /v1/models 列表不够。[7]
准备好后回到 PowerShell。key 只在自己的终端输入,不要放进 Codex 聊天、截图或代码文件。
把 Codex 接到 SHUN API
以下用于尚未配置过 Codex 的电脑。已有配置、自定义目录或其他服务的 SHUN_API_KEY 时,先看下方「已有配置说明」。
两段分别完整复制到 PowerShell;按提示输入 key 和模型 ID,无需手动改代码。
① 保存用户 key
key 隐藏输入,粘贴一次后回车。它会保存到当前 Windows 用户的环境变量,并在本窗口生效。环境变量不是加密密码库。[9]
& {
$ErrorActionPreference = 'Stop'
$codexSecret = Read-Host '粘贴你的 SHUN 用户 key(输入会隐藏),然后回车' -AsSecureString
$codexPointer = [IntPtr]::Zero
try {
$codexPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($codexSecret)
$codexKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($codexPointer).Trim()
if ([string]::IsNullOrWhiteSpace($codexKey) -or $codexKey -match '\s') {
throw 'key 不能为空或包含空白,请重新复制完整的用户 key。'
}
[Environment]::SetEnvironmentVariable('SHUN_API_KEY', $codexKey, 'User')
[Environment]::SetEnvironmentVariable('SHUN_API_KEY', $codexKey, 'Process')
Write-Host 'SHUN 用户 key 已保存;这里不会显示它。'
} finally {
if ($codexPointer -ne [IntPtr]::Zero) {
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($codexPointer)
}
$codexKey = $null
$codexSecret.Dispose()
}
}② 创建 SHUN 配置
看到「SHUN 用户 key 已保存」后运行。它创建 %USERPROFILE%\.codex\shun.config.toml,不写入 key 正文;已有基础或同名配置时会停止。[6]
& {
$ErrorActionPreference = 'Stop'
if ($env:CODEX_HOME) {
throw '检测到自定义 CODEX_HOME。请先核对现有配置,不继续新机步骤。'
}
$codexConfigDir = Join-Path $env:USERPROFILE '.codex'
$codexProfilePath = Join-Path $codexConfigDir 'shun.config.toml'
if (Test-Path -LiteralPath (Join-Path $codexConfigDir 'config.toml')) {
throw '检测到已有 Codex 基础配置。请按已有配置说明先核对合并,不继续新机步骤。'
}
if (Test-Path -LiteralPath $codexProfilePath) {
throw 'SHUN 配置已经存在,本命令不会覆盖。请看下方的已有配置说明。'
}
$codexModel = (Read-Host '粘贴管理员确认可用于 Codex 的完整模型 ID,然后回车').Trim()
if ($codexModel -notmatch '^[A-Za-z0-9][A-Za-z0-9._:/+\[\]@-]*$') {
throw '模型 ID 不能为空、包含空格或引号;请核对后重新运行。'
}
$codexProfile = @"
model = "$codexModel"
model_provider = "shun"
approval_policy = "on-request"
approvals_reviewer = "user"
sandbox_mode = "workspace-write"
web_search = "disabled"
[model_providers.shun]
name = "SHUN API"
base_url = "https://apivip.shun.team/v1"
env_key = "SHUN_API_KEY"
wire_api = "responses"
requires_openai_auth = false
[features]
prefer_mxc = true
[windows]
sandbox = "elevated"
[shell_environment_policy.filters]
SHUN_API_KEY = "exclude"
"@
New-Item -ItemType Directory -Path $codexConfigDir -Force | Out-Null
$codexBytes = [Text.UTF8Encoding]::new($false).GetBytes($codexProfile)
$codexStream = [IO.File]::Open($codexProfilePath, [IO.FileMode]::CreateNew)
try { $codexStream.Write($codexBytes, 0, $codexBytes.Length) }
finally { $codexStream.Dispose() }
Write-Host 'SHUN 配置已创建。启动时请使用 codex.cmd --profile shun。'
}每次启动都带 --profile shun。地址保留 https://apivip.shun.team/v1,不要追加 /responses。
这份配置设置了什么?
Codex 从 SHUN_API_KEY 读取网关凭据,使用 Responses;首次关闭网页搜索。权限为 workspace-write,需要更多权限时由你确认。[8]
兼容设备优先使用 MXC,其余使用 elevated 沙箱。环境过滤从 Codex 启动的 shell 中排除 key,不影响 Codex 自己认证;不代表其他插件都使用该过滤规则。[5][6]
已有配置说明:基础配置、同名 profile 或自定义 CODEX_HOME
profile 是配置叠加层,不是完全隔离的安装。基础配置中的模型目录、provider 认证等设置仍可能生效;受信项目配置也可能覆盖部分设置。已有 config.toml、shun.config.toml、自定义 CODEX_HOME 或公司统一配置时,先备份并请维护者合并,不要删除整个 .codex。
如果提前启动过 Codex,它可能已创建基础配置;此时停止是保护提示。已有 SHUN profile 确认正确后,可直接到第 7 步。旧 [profiles.shun] 须按官方说明迁移。[6]
改模型时先退出 Codex,备份专用文件,再修改顶部 model = "…"。写入失败可能留下不完整文件,先核对权限、磁盘和文件内容,再修复;不要把 provider 放进项目配置。
进入练习文件夹,第一次启动
下面在 Windows 用户目录创建并进入 Codex-Learning,再启动 Codex。目录操作失败就停止。
& {
$ErrorActionPreference = 'Stop'
$codexPracticeDir = Join-Path $env:USERPROFILE 'Codex-Learning'
New-Item -ItemType Directory -Path $codexPracticeDir -Force | Out-Null
Set-Location -LiteralPath $codexPracticeDir
codex.cmd --profile shun
}- 信任目录:确认是自己的
Codex-Learning,再选择信任。 - Windows 沙箱:按提示完成设置。支持 MXC 的设备无需管理员安装;elevated 首次设置可能弹出 Windows 管理员确认。公司电脑受限时联系设备管理员,日常仍普通打开 PowerShell。[5]
若要求 ChatGPT 登录,先退出,检查 --profile shun 和第 6 步;不要把 SHUN key 填到 OpenAI 登录页。
进入 Codex 输入区后运行:
/status核对模型 ID、provider 为 shun / SHUN API、目录为 Codex-Learning,以及权限和沙箱。看到 Model metadata … not found 时先停止,请管理员核对模型目录。[7][10]
/status 只确认配置;下一步写出文件才验证实际使用。
让 Codex 创建第一个文件
在 Codex 聊天输入区发送下面任务。这一步会使用 SHUN API 额度。
请只在当前 Codex-Learning 文件夹中操作。
创建一个 UTF-8 编码的 hello.txt,内容为:
你好,Codex!这是我的第一次练习。
如果文件已经存在,请先告诉我,不要覆盖。
完成后请读取文件,确认内容,并告诉我文件保存在哪里。若询问权限,确认目标是练习目录和 hello.txt 再允许;不需要开启完全访问。
打开文件检查
按 Win + E 打开资源管理器,将下面地址粘贴到顶部地址栏后回车:
%USERPROFILE%\Codex-Learning双击 hello.txt。隐藏扩展名时可能显示为 hello;打开后应为「你好,Codex!这是我的第一次练习。」
- Codex 正常回复,无连接或认证报错。
- 目录中实际存在
hello.txt。 - 打开文件,中文内容正确。
有「已完成」但无文件时,让 Codex 检查写入路径和权限;以实际文件为准。
下次怎么用
结束时在 Codex 输入 /exit。下次打开 PowerShell,运行:[10]
& {
$ErrorActionPreference = 'Stop'
Set-Location -LiteralPath (Join-Path $env:USERPROFILE 'Codex-Learning')
codex.cmd --profile shun
}进入后可用 /resume 继续旧会话,再用 /status 核对模型。更新时先退出全部 Codex,再运行:
npm.cmd install -g @openai/codex@latest更新后用 codex.cmd --version 检查。换 key 只重做第 6 步第一段;新窗口仍读旧值时退出全部终端重开,必要时注销 Windows。[9]
卡住了?按报错检查
| 现象 | 处理 |
|---|---|
| node / npm.cmd / git / codex.cmd 无法识别 | 先关闭全部终端重开。Node 安装保留 npm 和 Add to PATH;Git 核对第 3 步 PATH 选项。Codex 用下方命令检查安装位置。 |
| npm.ps1 / codex.ps1 禁止运行 | 使用本文 npm.cmd / codex.cmd,无需改全局执行策略。 |
| npm 超时 / EBADENGINE / EPERM | 超时先检查网络;EBADENGINE 回第 2 步安装 Node.js 24 LTS;EPERM 先退出 Codex,再查目录权限和文件占用。 |
| native binary not found | 核对系统架构,重新安装完整 @openai/codex,不要跳过 optional 平台依赖。 |
| ChatGPT 登录 / Missing environment variable | 检查 --profile shun;重新保存第 6 步的 key,在同一终端启动。 |
| Profile not found / TOML parse error | 核对用户 .codex 中的 shun.config.toml。旧版先更新;已有基础配置、旧 [profiles.shun] 或重复字段按第 6 步说明处理。 |
| 401 / 403 | 401 核对个人用户 key 和账号状态;403 请管理员检查模型权限。 |
| 404 / model metadata 警告 | 核对完整地址 https://apivip.shun.team/v1 和模型 ID。元数据警告须由管理员核对匹配的 Codex 模型目录,不能仅凭有回复就忽略。 |
| 402 / 429 / 503 | 402 查额度;429 等待限速恢复;503 请管理员检查该模型的 Responses 渠道是否已启用。 |
| 沙箱失败 / Windows error 1385 | 按安装提示和设备策略排查;联系管理员检查 elevated 设置与登录权限,不改成完全访问。prefer_mxc 的 under-development 提醒本身不等于安装失败。 |
| 证书错误 / 有回复无文件 | 证书错误先查系统时间和组织证书,不关闭 HTTPS 校验;无文件时核对当前目录、实际写入路径和权限。 |
npm.cmd list -g @openai/codex --depth=0
npm.cmd prefix -g
Get-Command codex.cmd -Allnpm 已安装,但找不到 codex.cmd:检查 Path
打开 npm.cmd prefix -g 输出的目录,确认有 codex.cmd。若文件存在,在开始菜单搜索「编辑账户的环境变量」,将该目录新增到用户 Path,保留原有项目;全部确定后重开终端。文件不存在则先处理安装错误。
求助时提供 Windows 和工具版本、卡住的步骤、发生时间及脱敏报错;遮住 key、邮箱和个人路径,不发送环境变量清单或认证文件。
资料来源与版本说明
2026-10-19 核对。配置与命令已做隔离验证;本地模拟不等于真实模型调用。实际文件练习仍取决于账号、模型、渠道和设备沙箱。
- OpenAI Docs:Codex CLI 安装与更新
- Node.js:官方 LTS 与 Windows 安装包
- Git:Windows 官方下载
- npm:安装 Node.js 与 npm
- OpenAI Docs:Windows 版本支持与原生沙箱
- OpenAI Docs:独立 profile、自定义 provider 与环境过滤
- OpenAI Docs:使用网关凭据、模型目录与连接核对
- OpenAI Docs:配置字段参考
- Microsoft:用户与进程环境变量
- OpenAI Docs:/status、/resume 与 /exit
指南不读取 key、不执行命令;勾选进度只保存在当前浏览器。截图日期为拍摄日期。