这份教程使用 Windows 原生 PowerShell。星驰和 FreeGG 可以同时配置,启动时选择其中一家。使用 OpenAI 官方 API 的步骤见文末。
1. 安装 Codex CLI
打开 PowerShell,执行 OpenAI 官方安装命令。
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
安装完成后,新开一个 PowerShell 窗口,检查是否能看到版本号。
codex --version
2. 配置星驰和 FreeGG
运行下面的命令,用记事本打开 Codex 的配置文件。默认位置是 %USERPROFILE%\.codex\config.toml,如果设置过 CODEX_HOME,则使用那个目录。
$codexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
New-Item -ItemType Directory -Path $codexDir -Force | Out-Null
$codexConfig = Join-Path $codexDir 'config.toml'
if (-not (Test-Path -LiteralPath $codexConfig)) {
New-Item -ItemType File -Path $codexConfig | Out-Null
}
notepad.exe $codexConfig
新文件可以直接粘贴下面整段配置。已有配置时,把 model_provider 和 model 放在第一个 [表名] 前,已有同名设置就修改原行。两个 [model_providers.…] 表也各保留一份。保存时选择 UTF-8 编码。
model_provider = "xingchi"
model = "gpt-6.1-sol"
[model_providers.xingchi]
name = "Xingchi"
base_url = "https://api.xingchiapi.com/v1"
wire_api = "responses"
requires_openai_auth = false
env_key = "XINGCHI_API_KEY"
[model_providers.freegg]
name = "FreeGG"
base_url = "https://freegg.app/v1"
wire_api = "responses"
requires_openai_auth = false
env_key = "FREEGG_API_KEY"
gpt-6.1-sol 是示例模型。请以所选服务商实际提供的模型 ID 为准。Codex CLI 使用 Responses API,服务商需要支持 POST /v1/responses。
3. 输入密钥并启动
先设置默认的星驰密钥。运行命令后,在提示处粘贴星驰发给你的 API Key 并按回车。PowerShell 会隐藏输入。密钥只在当前窗口及其启动的程序中可用。
$env:XINGCHI_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host '输入星驰 API Key' -AsSecureString)).Password
在同一个 PowerShell 窗口进入项目目录,运行 codex。首次启动如果提示配置 Windows 沙盒,按界面完成设置。在会话中输入「请只回复 OK」,收到回复就说明 API 可以使用。
也可以在 PowerShell 中用一条命令检查连通性。
codex exec --skip-git-repo-check --ephemeral --sandbox read-only '请只回复 OK,不要运行命令。'
使用这两个第三方服务商时,密钥由 env_key 提供,可以直接启动 Codex。
4. 切换到 FreeGG
在 PowerShell 中输入 FreeGG 的密钥,然后启动一个使用 FreeGG 的新会话。
$env:FREEGG_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host '输入 FreeGG API Key' -AsSecureString)).Password
codex -c model_provider=freegg
如果 FreeGG 提供的模型 ID 不同,在同一条命令里加上 -m '服务商提供的模型ID'。要把 FreeGG 设成默认值,把配置文件开头改成 model_provider = "freegg",然后按需更新 model。下次打开 PowerShell 后,重新输入所选服务商的密钥即可。
5. 常见问题
- PowerShell 找不到
codex。关掉终端后重新打开,再运行 Get-Command codex。如果仍然找不到,检查安装命令的输出。
- 提示缺少
XINGCHI_API_KEY 或 FREEGG_API_KEY。在启动 Codex 的同一个 PowerShell 窗口输入对应的密钥,检查配置里的 env_key 拼写。
401 Unauthorized。核对 API 地址和密钥是否来自同一家服务商,并检查密钥是否有效。
404 或 model_not_found。核对模型 ID 和 base_url,确认服务商支持 /v1/responses。配置文件中的 base_url 写到 /v1。
429。根据返回信息检查余额、用量额度或请求频率。
使用 OpenAI 官方 API
如果你持有 OpenAI 平台签发的 API Key,使用 Codex 内置的 openai 提供商。新安装可以直接保留默认配置。已有配置时,把开头的 model_provider 改为 "openai",并将 model 改为自己有权使用的模型,或删掉 model 设置使用默认模型。
$apiKey = [System.Net.NetworkCredential]::new('', (Read-Host '输入 OpenAI API Key' -AsSecureString)).Password
$apiKey | codex login --with-api-key
Remove-Variable apiKey
codex
官方资料可查阅 Codex CLI 安装、Codex 配置说明和认证方式。