手动配置 Codex

当一键安装、安装向导或 ccswitch 导入不可用时，再手动配置 Codex。推荐方式是：config.toml 写 Base URL，环境变量写 API Key。

不要把 Key 写进项目仓库

API Key 只应存在于你自己的用户目录或系统环境变量里，不要写进 README、截图、聊天记录或 Git 仓库。

适合谁看

• 安装向导生成的命令不适合你的机器。
• ccswitch 导入后 Codex 仍然走官方登录。
• 需要手动确认 config.toml、Key 和 Base URL。

你需要准备

项目	示例
API Key	sk-relay-xxxxxxxx
Base URL	https://hk.getelucid.com
配置文件	config.toml
推荐 Key 变量	ELUCID_RELAY_API_KEY

找到 Codex 配置目录

Windows：

%USERPROFILE%\.codex\config.toml

macOS / Linux：

~/.codex/config.toml

如果目录不存在，可以先启动一次 Codex，或者手动创建。

修改 config.toml

推荐模板：

model = "gpt-5-codex"
model_provider = "elucid-relay"
model_reasoning_effort = "high"

[model_providers.elucid-relay]
name = "Elucid Relay"
base_url = "https://hk.getelucid.com"
env_key = "ELUCID_RELAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false

如果控制台展示的 Base URL 不同，以控制台为准。不要手动追加路径；你当前能用什么，就写什么。

写入 API Key

Windows PowerShell：

[Environment]::SetEnvironmentVariable("ELUCID_RELAY_API_KEY", "sk-relay-xxxxxxxx", "User")
$env:ELUCID_RELAY_API_KEY = [Environment]::GetEnvironmentVariable("ELUCID_RELAY_API_KEY", "User")

macOS / Linux：

export ELUCID_RELAY_API_KEY="sk-relay-xxxxxxxx"

如需长期生效，写入 ~/.zshrc 或 ~/.bashrc。

auth.json 备用方式

部分旧配置示例会把 Key 写进 auth.json。如果你明确使用 requires_openai_auth = true 或某些兼容模式，路径通常是：

Windows：

%USERPROFILE%\.codex\auth.json

macOS / Linux：

~/.codex/auth.json

示例：

{
  "OPENAI_API_KEY": "sk-relay-xxxxxxxx"
}

默认推荐环境变量方式，因为它更容易避免把 Key 误提交到项目仓库。

保存并验证

先检查登录状态：

codex login status

再做最小探活：

codex exec --skip-git-repo-check "请回复“配置已生效”。"

或者进入任意项目目录：

codex

排错清单

现象	可能原因	处理方式
401	Key 错、过期或环境变量没生效	重新复制 Key，关闭终端后重开
404	Base URL 路径和服务端不匹配	回控制台复制完整 Base URL，不要自行补路径
仍跳官方登录	provider 配置未生效	检查 model_provider 和 [model_providers.*] 名称一致
修改了没变化	改错用户目录	确认当前终端用户和配置目录一致
TLS 报错	代理或证书拦截	检查公司网络、代理和本机证书