# Codex 接入指南

下载预设配置：https://code.ai.xmyh.net.cn/downloads/xmyh.config.toml

三步：安装 Codex → 将配置放入用户目录的 .codex 文件夹 → 在项目终端输入 Key 并启动。配置文件不包含密钥；已有同名文件请先备份。

先配置一个工具，再完成第一个任务。本指南针对 Codex CLI（终端版）。

当前状态：新零售充值与 API Key 交付尚未开放；已有有效 Key 的用户按原服务权限使用。配置依据官方文档整理，尚未完成付费端到端验收。

## 1. 准备与安装

准备你自己的星贸云航 API Key，以及一个可以练习的项目目录。没有 Key 时请到 [客户中心](https://ai.xmyh.net.cn/account) 查看开通状态。注册不会自动获得 Key。

按 [Codex 官方安装说明](https://developers.openai.com/codex/cli) 安装终端版，运行以下命令查看版本。本页配置适用于 Codex 0.134.0 及以后版本；旧版本请先更新。

```bash
codex --version
```

## 2. 保存配置

在用户目录的 .codex 文件夹中创建 xmyh.config.toml。macOS / Linux 的完整路径是 ~/.codex/xmyh.config.toml；Windows 是 %USERPROFILE%\.codex\xmyh.config.toml。如果该文件已存在，先备份并合并配置，不覆盖原内容。

把下面内容保存到这个文件。API Key 不需要写在文件里。

```toml
model_provider = "xmyh"
model = "gpt-5.6-sol"
web_search = "disabled"

[model_providers.xmyh]
name = "星贸云航"
base_url = "https://api.xmyh.net.cn/v1"
env_key = "XMYH_API_KEY"
wire_api = "responses"
requires_openai_auth = false
```

模型必须在你的 Key 授权范围内。本页先使用一个默认模型，不需要新手逐个选择。新版 Codex 使用独立的 xmyh.config.toml，不要把这些内容放进旧的 [profiles.xmyh] 表。

## 3. 输入 Key，启动 Codex

先在终端进入你信任的项目目录，再选择与你电脑对应的一组命令。Key 输入时不会显示，也不会直接写进命令历史。不要把 Key 发到聊天、截图或项目仓库里。

macOS / Linux：先运行 bash，再执行：

```bash
read -r -s -p "请输入你的星贸云航 API Key: " XMYH_API_KEY
printf '\n'
export XMYH_API_KEY
codex --profile xmyh
```

Windows PowerShell：

```powershell
$secret = Read-Host "请输入你的星贸云航 API Key" -AsSecureString
$env:XMYH_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
codex --profile xmyh
```

必须从设置了 Key 的同一个终端启动。重新打开终端后需要重新设置；桌面图标或云端任务不会自动继承这套终端配置。已有项目或组织配置也可能覆盖部分设置。

## 4. 完成第一个任务

进入 Codex 后输入 /status，核对当前模型与提供商。首次请求会产生 API 消费，先确认余额和价格，再发送下面的小任务：

```text
先阅读当前项目，不修改文件、不执行安装或部署。
请用中文说明项目入口、运行方式和已有的测试命令。
不确定的地方明确标注，不要猜测。
```

确认回复正常，并查看调用记录。然后回到 [任务工作台](https://code.ai.xmyh.net.cn/#workbench)，生成一张目标、边界和验收条件明确的任务卡，把任务卡交给 Codex。每次只处理一个可验证的小任务，检查修改和测试结果后再继续。

## 遇到问题怎么办

401：检查 Key 是否有效，以及是否从设置了 Key 的同一个终端启动。

403 或无可用渠道：检查账户状态与模型权限；注册账户不等于模型已经开通。

404：检查 base_url 是否为 https://api.xmyh.net.cn/v1，不要填写产品站域名或重复添加 /v1。

配置未生效：检查文件名是否为 xmyh.config.toml、是否误存成 .txt，以及启动时是否使用 --profile xmyh。用 /status 核对实际生效的设置。

429、超时或服务错误：先查看调用记录与余额，记录时间、模型和请求 ID 后联系支持，避免连续盲目重试。截图不要包含密钥。

## 使用完后

退出 Codex 后，Bash 可执行 unset XMYH_API_KEY；PowerShell 可执行 Remove-Item Env:XMYH_API_KEY 并执行 Remove-Variable secret。关闭该终端也会结束本次终端变量的使用。不带 --profile xmyh 启动时使用原默认配置。

更新：2026-09-18。[官方自定义提供商与配置说明](https://learn.chatgpt.com/docs/config-file/config-advanced)。配置检查不等于所有工具功能已经通过本平台验收。