macOS 配置 Codex

使用 Windows 的用户请转到 Windows 教程。

1. 准备账户与接入信息

先按账户设置指南完成登录和API密钥创建。

并按充值与订阅指南确认密钥的计费分组。

2. 下载安装Codex CLI

从ChatGPT官网下载并安装客户端。

3. 找到并备份和替换配置文件

Codex 默认使用 ~/.codex；用户配置文件为 config.toml和auth.json。备份并修改这两个文件。

兼容模式（常规模式）

适用对象：大部分用户，需修改配置两个文件，配置文件为config.toml 和auth.json。

有生图需求的请按下面API Key Mode配置。

config.toml文件

1. 终端输入open .codex 找到config.toml文件所在目录。

2. 备份config.toml 文件

3. 回到算搭网站,点击【使用密钥】

4. 复制【使用密钥】中的config.toml文件内容

5. 全部粘贴到codex目录下的config.toml文件

auth.json文件

1. 终端输入open .codex 找到auth.json文件所在目录。

2. 备份auth.json 文件

3. 回到算搭网站,点击【使用密钥】

4. 复制【使用密钥】中的auth.json文件内容

5. 全部粘贴到codex目录下的auth.json文件

API Key Mode（生图模式）

适用对象：有生图需求的用户。目前仅需配置config.toml文件

1. 终端输入open .codex 找到config.toml文件所在目录。

2. 备份config.toml 文件

3. 回到算搭网站,点击【使用密钥】

4. 复制【使用密钥】中的config.toml文件内容

5. 全部粘贴到codex目录下的config.toml文件

6. ⚠️⚠️删除这一行代码后再进行下一步

   model_catalog_json = "~/.codex/codex-models.json

4. 重启验证（⚠️⚠️⚠️）

重启客户端（一定要重启！！！）

打开新的对话，能正常对话即可

恢复旧配置

如需恢复旧配置：

1. 退出正在运行的 Codex。
2. 在 Finder 中按 Command+Shift+G，输入第 3 步实际使用的配置目录路径并前往；默认路径是 ~/.codex。
3. 将当前 config.toml和auth.json 改名保留。找到修改前备份，复制一份并将副本命名为 config.toml和auth.json ；保留原备份。
4. 如果修改前没有配置文件，保留改名后的文件即可，不创建替代文件。
5. 清除本教程的环境变量，重新启动 Codex，检查是否恢复为原来的配置。

常见问题

现象	处理方法
提示 TOML 格式错误	对照报错行检查英文双引号、重复字段和表的位置；确认保存的是纯文本。
输入密钥时报 bad option 等语法错误	先运行 zsh，再执行第 5 步；这条 read 命令是 zsh 语法。
提示缺少 SUANDA_API_KEY	在启动 Codex 的同一个 zsh 会话重新执行第 5 步，输入后按回车。
仍要求 ChatGPT 登录或使用了其他模型	核对顶层 model_provider、自定义服务字段，以及可信项目内是否有覆盖设置的 .codex/config.toml。
返回 401、403 或密钥无效	核对密钥是否完整、是否有效，以及账户、分组和目标模型是否匹配；保留具体错误文字。
提示模型不存在、404 或接口不兼容	检查完整模型 ID、Base URL 和 Responses 支持情况，向客服确认准确值，不随机尝试路径。
返回 429、额度不足或服务繁忙	按错误文字区分限流、额度和服务状态，检查账户后联系客服；不要连续重试或直接重复充值。
超时、网络或证书错误	检查本机网络和已确认的接入地址，记录错误；不要通过关闭证书验证来连接。

项目配置可能覆盖用户配置，优先级见 Codex 配置基础。