跳到教程正文
SHUN API · 使用指南

从零开始 · 第二篇

在 Windows 上安装
Codex

从打开 PowerShell,到让 AI 创建第一个文件。
照着 8 步做,把 Codex CLI 接入你的 SHUN API。

Windows 10 / 11不需要编程基础Node.js → Git → npm

核对日期: · 预留约 30–60 分钟,下载时间取决于网络。

开始第 1 步 ↓

开始前准备好

本篇使用 PowerShell → Node.js / npm → Git → Codex CLI。Codex 是 OpenAI 的终端编程工具,可按中文要求创建文件;不需要先装编辑器或 WSL。

推荐 Windows 11。近期更新的 Windows 10 1809+ 为尽力支持。按 Win + R,输入 winver 查看版本;在「设置 → 系统 → 关于」查看 x64 / ARM64 系统类型。[5]

先向管理员确认:个人用户 key、可用于 Codex 的模型,以及已启用的 Responses 渠道。

本篇使用 SHUN API 额度,不走 ChatGPT 登录。安装成功后,还要完成第 8 步的真实文件检查。

下载页使用官网真实截图;SHUN 截图使用本站界面和演示数据。点击图片可放大。

打开 PowerShell

按 Win 键,搜索 PowerShell,普通打开「Windows PowerShell」,不要选 ISE。看到 PS C:\Users\…> 后,后面的安装命令都粘贴到这里。

安装 Node.js 和 npm

npm 随 Node.js 一起安装,稍后用它下载 Codex。[4]

① 下载安装包

  1. 打开 Node.js 官方下载页,在图中 ① 版本框选 Node.js 24 LTS。LTS 表示长期支持版。[2]
  2. 向下滚过 Docker 命令框,找到 Or get a prebuilt Node.js® for。按图中 ② 选 Windows,③ 选电脑对应的 x64 或 ARM64。
  3. 点击 ④ Windows Installer (.msi) 下载安装包,不选旁边的 Standalone Binary (.zip)。
图 1 · 官网实拍(2026-10-19)。按 ①→②→③→④ 操作;下载按钮在命令框下方。点击图片可放大查看。

② 安装并重开终端

  1. 双击下载的 .msi,接受许可后点 Next,安装位置保持默认。
  2. Custom Setup 保留 npm package manager 和 Add to PATH;PATH 让终端找到程序。
  3. Tools for Native Modules 的额外工具无需勾选。点 Install → Finish;Windows 若询问权限,确认是刚下载的官网安装包。
  4. 关闭全部 PowerShell / Windows 终端窗口,从开始菜单重新打开,再运行:
新的 PowerShell · 检查 Node.js 与 npm
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]

  1. 打开 Git 官方 Windows 下载页,找到 Other Git for Windows downloads → Standalone Installer。
  2. 普通 Intel / AMD 电脑选图中 ① Git for Windows/x64 Setup;ARM 电脑选 ② ARM64 Setup。不选 Portable。
图 2 · 官网实拍(2026-10-19)。两条箭头对应两种电脑架构,选其中一项下载,随后再运行安装包。
  1. 双击下载的 .exe,阅读许可,目录和组件保持默认。
  2. 在 Adjusting your PATH environment 选择 Git from the command line and also from 3rd-party software,让 PowerShell 和 Codex 找到 Git。
  3. 其余默认,点 Install → Finish。关闭全部终端,重开 PowerShell 后运行:
新的 PowerShell · 检查 Git
git --version
应看到 git version …。

在开始菜单搜索 Git Bash,能打开即表示附带环境也已装好;检查后关闭。

用 npm 安装 Codex

运行下面一行。-g 表示全局安装,@latest 选择安装时的最新版。[1]

PowerShell · 安装 Codex
npm.cmd install -g @openai/codex@latest

等到重新出现 PS C:\…>。出现 npm error 时先看排错表;npm 自身的更新提醒不等于失败。关闭全部终端,重开后检查:

新的 PowerShell · 检查 Codex 版本
codex.cmd --version
应看到 codex-cli 和版本号。

这是终端工具,没有桌面图标也正常。先完成第 6 步配置,再首次启动聊天。

以前装过 Codex?

先用 Get-Command codex -All 核对安装位置,按原方式更新。保留原生版时,下文 codex.cmd 改为 codex。本篇采用当前独立 profile 语法;0.134.0 是 profile 变更点,不是整个模板的最低版本承诺。已有配置先按第 6 步说明核对,保留会话和认证文件。[6]

准备用户 key 和可用模型

向管理员领取个人用户 key,确认模型支持 Responses、流式回复和工具调用。不要填写管理员密钥、登录密码或「GPT」这样的品牌名。[7]

  1. 打开 SHUN API 控制台,粘贴用户 key,点「进入」,检查账号状态和额度。
  2. 进入模型价格,复制管理员确认可用的完整模型 ID。
图 3 · 本网站实际界面,演示账号数据,实拍于 2026-10-19。① 可从首页进入控制台;② 在登录框粘贴管理员给你的个人用户 key,点「进入」。首页 Base URL 保留完整的 /v1。
图 4 · 本网站实际模型价格页,演示账号数据,实拍于 2026-10-19。① 打开「模型价格」;② 找到模型完整 ID。模型、价格均为演示,不能据此判断自己的权限或额度。
价格目录不等于账号权限,也不保证 Codex 兼容。

本篇模板用于管理员确认当前 Codex 已识别、无需额外模型目录的模型。自定义别名须先由管理员提供配套 catalog 配置;单有 /v1/models 列表不够。[7]

准备好后回到 PowerShell。key 只在自己的终端输入,不要放进 Codex 聊天、截图或代码文件。

把 Codex 接到 SHUN API

以下用于尚未配置过 Codex 的电脑。已有配置、自定义目录或其他服务的 SHUN_API_KEY 时,先看下方「已有配置说明」。

两段分别完整复制到 PowerShell;按提示输入 key 和模型 ID,无需手动改代码。

① 保存用户 key

key 隐藏输入,粘贴一次后回车。它会保存到当前 Windows 用户的环境变量,并在本窗口生效。环境变量不是加密密码库。[9]

PowerShell · 完整复制,运行后按提示粘贴用户 key
& {
    $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]

PowerShell · 完整复制,运行后按提示粘贴模型 ID
& {
    $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。'
}
看到「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。目录操作失败就停止。

PowerShell · 建立练习目录并启动 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
}
  1. 信任目录:确认是自己的 Codex-Learning,再选择信任。
  2. Windows 沙箱:按提示完成设置。支持 MXC 的设备无需管理员安装;elevated 首次设置可能弹出 Windows 管理员确认。公司电脑受限时联系设备管理员,日常仍普通打开 PowerShell。[5]

若要求 ChatGPT 登录,先退出,检查 --profile shun 和第 6 步;不要把 SHUN key 填到 OpenAI 登录页。

进入 Codex 输入区后运行:

Codex 输入区 · 此时不再是 PowerShell 命令
/status

核对模型 ID、provider 为 shun / SHUN API、目录为 Codex-Learning,以及权限和沙箱。看到 Model metadata … not found 时先停止,请管理员核对模型目录。[7][10]

模型、provider 和目录正确后继续。

/status 只确认配置;下一步写出文件才验证实际使用。

让 Codex 创建第一个文件

在 Codex 聊天输入区发送下面任务。这一步会使用 SHUN API 额度。

Codex 输入区 · 复制这段中文任务
请只在当前 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]

PowerShell · 回到练习目录,使用 SHUN 配置启动
& {
    $ErrorActionPreference = 'Stop'
    Set-Location -LiteralPath (Join-Path $env:USERPROFILE 'Codex-Learning')
    codex.cmd --profile shun
}

进入后可用 /resume 继续旧会话,再用 /status 核对模型。更新时先退出全部 Codex,再运行:

PowerShell · 更新本篇 npm 版 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 / 403401 核对个人用户 key 和账号状态;403 请管理员检查模型权限。
404 / model metadata 警告核对完整地址 https://apivip.shun.team/v1 和模型 ID。元数据警告须由管理员核对匹配的 Codex 模型目录,不能仅凭有回复就忽略。
402 / 429 / 503402 查额度;429 等待限速恢复;503 请管理员检查该模型的 Responses 渠道是否已启用。
沙箱失败 / Windows error 1385按安装提示和设备策略排查;联系管理员检查 elevated 设置与登录权限,不改成完全访问。prefer_mxc 的 under-development 提醒本身不等于安装失败。
证书错误 / 有回复无文件证书错误先查系统时间和组织证书,不关闭 HTTPS 校验;无文件时核对当前目录、实际写入路径和权限。
PowerShell · 检查安装位置,不显示 key
npm.cmd list -g @openai/codex --depth=0
npm.cmd prefix -g
Get-Command codex.cmd -All
npm 已安装,但找不到 codex.cmd:检查 Path

打开 npm.cmd prefix -g 输出的目录,确认有 codex.cmd。若文件存在,在开始菜单搜索「编辑账户的环境变量」,将该目录新增到用户 Path,保留原有项目;全部确定后重开终端。文件不存在则先处理安装错误。

求助时提供 Windows 和工具版本、卡住的步骤、发生时间及脱敏报错;遮住 key、邮箱和个人路径,不发送环境变量清单或认证文件。

资料来源与版本说明

2026-10-19 核对。配置与命令已做隔离验证;本地模拟不等于真实模型调用。实际文件练习仍取决于账号、模型、渠道和设备沙箱。

  1. OpenAI Docs:Codex CLI 安装与更新
  2. Node.js:官方 LTS 与 Windows 安装包
  3. Git:Windows 官方下载
  4. npm:安装 Node.js 与 npm
  5. OpenAI Docs:Windows 版本支持与原生沙箱
  6. OpenAI Docs:独立 profile、自定义 provider 与环境过滤
  7. OpenAI Docs:使用网关凭据、模型目录与连接核对
  8. OpenAI Docs:配置字段参考
  9. Microsoft:用户与进程环境变量
  10. OpenAI Docs:/status、/resume 与 /exit

指南不读取 key、不执行命令;勾选进度只保存在当前浏览器。截图日期为拍摄日期。