单元二和 AI 第一次合作 · 第 6 课

接入 API 与环境变量

这一课结束时，Codex 会第一次开口跟你说话。中间要学一个程序员天天用的概念：环境变量。

本课目标

注册账号，拿到 API Key。
理解环境变量，会临时设置和永久设置。
写好 Codex 的配置文件，完成第一次对话。

第一步：拿到 API Key

访问 m.zairouter.com 注册账号，按提示完成邮箱验证。
系统会把你的 API Key 发到注册邮箱，它是一串以 sk- 开头的长字符。
按账户页面的提示选择套餐或充值。

记住第 2 课说的：Key 就是钱包。先把它存在一个只有你能看到的地方，比如密码管理器。

先懂概念：环境变量

Codex 需要知道你的 Key。最直接的办法是把 Key 写进配置文件，但这样很危险：配置文件可能被你分享出去，或者被 AI 读到后写进别的地方。

程序员的做法是把 Key 放进环境变量。环境变量是电脑里贴着的“便利贴”，每张有一个名字和一个值，比如：

名字：XAI_API_KEY
值：  sk-xxxxxxxx

程序启动时会去看这些便利贴。配置文件里只写“去看名叫 XAI_API_KEY 的那张”，Key 本身不写进项目和配置文件。（永久设置时，系统会把它保存在你的用户设置里，下文会提到。）第 4 课的 PATH 其实也是一个环境变量。

环境变量有两种设法：

方式	效果	适合
临时设置	只在当前这个终端窗口有效，关掉就没了	试一试
永久设置	以后打开的每个终端都有效	日常使用

第二步：临时设置，试一试

把下面的 sk-你的Key 换成你自己的 Key。

$env:XAI_API_KEY = "sk-你的Key"

export XAI_API_KEY="sk-你的Key"

（第一行是 Windows PowerShell，第二行是 macOS，下同。）

检查有没有设上。下面的命令只显示 Key 的长度，不会把 Key 本身打在屏幕上，截图或共享屏幕时也安全：

$env:XAI_API_KEY.Length

echo ${#XAI_API_KEY}

显示一个数字（比如 51）就说明设好了；显示 0 或什么都没有，说明没设上。

第三步：永久设置

确认临时设置能用以后，再永久保存。

Windows：

setx XAI_API_KEY "sk-你的Key"

看到“成功: 指定的值已得到保存”即可。setx 只对之后新开的终端生效，所以接着关掉终端，重新打开一个。

macOS（终端默认使用的 Shell 叫 zsh，它每次启动时会读家目录里的 .zshrc 文件）：

echo 'export XAI_API_KEY="sk-你的Key"' >> ~/.zshrc

然后关掉终端，重新打开一个。

用第二步的命令再检查一次长度。

永久设置会把 Key 以明文存在你的电脑上：Windows 存在用户设置里，macOS 存在 ~/.zshrc 里。个人电脑这样做没问题，公用电脑不要这样做。另外，你输入过的命令会留在终端历史里，同样只适合个人电脑。

第四步：写 Codex 的配置文件

Codex 的配置文件在家目录下的 .codex/config.toml。名字以点开头的文件夹默认是隐藏的，不用管它，下面一段命令会帮你创建好。

如果你以前用过 Codex 并且有自己的配置，先把原来的 config.toml 复制一份备份，因为下面的命令会覆盖它。

Windows：把下面整段一次性复制粘贴到 PowerShell，回车。如果弹出“多行粘贴”的提示，选择“仍然粘贴”。

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
@'
model_provider = "xai"
model = "gpt-5.6-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
api_key_model_discovery = true

[model_providers.xai]
name = "xai"
base_url = "https://api.zairouter.com"
model_catalog_url = "https://api.zairouter.com/models"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"
supports_websockets = false
http_headers = { "x-codex-routing-hint" = "model=gpt-5.6-sol" }
'@ | Set-Content -Encoding ascii "$HOME\.codex\config.toml"

macOS：同样整段复制粘贴到终端，回车。

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model_provider = "xai"
model = "gpt-5.6-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
api_key_model_discovery = true

[model_providers.xai]
name = "xai"
base_url = "https://api.zairouter.com"
model_catalog_url = "https://api.zairouter.com/models"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"
supports_websockets = false
http_headers = { "x-codex-routing-hint" = "model=gpt-5.6-sol" }
EOF

用 cat 看一眼文件内容，确认写进去了：

cat "$HOME\.codex\config.toml"

cat ~/.codex/config.toml

这份配置里最重要的几行：

配置	意思
`base_url`	API 的地址，也就是第 2 课说的“窗口地址”
`env_key = "XAI_API_KEY"`	去名叫 `XAI_API_KEY` 的环境变量里取 Key
`model`	默认使用的模型
`approval_policy = "on-request"`	需要更大权限时先问你
`sandbox_mode = "workspace-write"`	只能改当前文件夹里的文件

最后两行是这门课推荐的安全设置，第 7 课会详细讲。

第五步：第一次对话

cd ~/ai-course
codex

第一次在某个文件夹里启动时，Codex 会问你是否信任这个文件夹（Trust this folder?）。ai-course 是你自己建的，用方向键选 Trust and continue，回车。

Windows 上第一次使用时，Codex 还可能请你设置“沙箱”（Set up the Codex agent sandbox）。沙箱是把 AI 的操作圈在一个范围里的保护措施。选 Set up default sandbox，Windows 会弹窗请求管理员权限，点“是”。如果你的账号没有管理员权限，选 Use non-admin sandbox。

然后在底部的输入框里输入：

你好，请用一句话介绍你自己。

你应该看到

几秒钟后，Codex 用中文回复你。输入 /status 回车，可以看到当前使用的模型和配置。

输入 /quit 回车，退出 Codex。

常见问题

报错提到 XAI_API_KEY 没有设置？ 说明 Codex 启动时没看到这个环境变量。用第二步的命令检查长度。如果是刚用 setx 或改了 .zshrc，记得重开终端。

报 401 或 Unauthorized？ Key 不对：多复制了空格、少复制了字符，或者 Key 已经失效。重新复制一遍，注意引号要成对。

报 429 或余额不足？ 账户额度用完了，或者请求太频繁，回账户页面看一看。

还是让我登录 ChatGPT？ 说明配置文件没有生效，用上面的 cat 命令确认文件内容和位置是否正确。

Key 不小心泄露了，或者要换 Key？ 立刻在账户后台更换 Key，然后把新 Key 设置好：

Windows：重新运行第三步的 setx XAI_API_KEY "sk-新Key"，再重开终端。
macOS：不要再追加一行，而是用 open -e ~/.zshrc 打开这个文件，找到原来那行 export XAI_API_KEY=...，把 Key 改成新的，保存后重开终端。如果在后面再追加一行，选修课里引用这个变量的设置会继续拿到旧 Key。

自检

我能用自己的话解释环境变量是什么、为什么要用它放 Key。
我会检查 XAI_API_KEY 的长度，而不是把它打印出来。
新开一个终端，XAI_API_KEY 依然存在。
Codex 能回复我的第一句话。

上一课安装 Codex 下一课第一个任务：只看不改