Codex 使用指南

推荐流程是：先用 Codex 自己的帐号完成授权登录，让 Codex 保留插件、MCP 与 Agent 能力；再用 Magick API 的 token 模式接管模型请求。Codex CLI 和桌面端共享同一套本地配置。

1. 安装并登录 Codex CLI

如果还没有安装 Codex CLI，先安装：

npm i -g @openai/codex

启动 Codex：

codex

第一次运行会引导你完成 Codex 帐号授权登录。建议先完成这一步，再配置 Magick API 的 token 模式，这样插件和本地工具能力更容易保持完整可用。

2. 配置 Magick API token 模式

Codex 支持 OpenAI 兼容协议，因此可以通过环境变量把模型请求指向 Magick API。

先在 API Key 管理页面 获取你的 Magick API Key。

macOS/Linux

当前终端临时生效：

export OPENAI_API_KEY="sk-你的 magickapi key"
export OPENAI_BASE_URL="https://api.magickapi.com/v1"

推荐写入 ~/.zshrc 或 ~/.bashrc，让配置长期生效：

echo 'export OPENAI_API_KEY="sk-你的 magickapi key"' >> ~/.zshrc
echo 'export OPENAI_BASE_URL="https://api.magickapi.com/v1"' >> ~/.zshrc
source ~/.zshrc

如果你使用 Bash，请把上面的 ~/.zshrc 换成 ~/.bashrc。

Windows PowerShell

setx OPENAI_API_KEY "sk-你的 magickapi key"
setx OPENAI_BASE_URL "https://api.magickapi.com/v1"

执行 setx 后，请重新打开终端窗口再启动 Codex。

3. 保持 Codex 插件可用

使用 API Key 或第三方 OpenAI 兼容地址时，部分 Codex 版本可能会隐藏或禁用某些插件能力，例如 GitHub、Chrome 控制、Browser 工具或 Agent 相关工具。可以在 Codex 配置文件中显式启用插件。

配置文件路径：

• macOS/Linux：~/.codex/config.toml
• Windows：%userprofile%\.codex\config.toml

在文件末尾加入以下内容：

[plugins."github@openai-curated"]
enabled = true

[plugins."chrome@openai-bundled"]
enabled = true

[plugins."browser@openai-bundled"]
enabled = true

如果你还使用其他插件，可以继续按插件名逐个启用。若当前 Codex 版本支持全局插件开关，也可以额外加入：

[plugins]
enabled = true

如果配置文件里已经有 MCP 或其他插件配置，请保留原有内容，只追加上面的启用项。

4. 重启并验证

保存配置后重启 Codex：

codex restart

也可以退出当前 Codex 会话后重新运行：

codex

进入 Codex 交互模式后，可以输入：

/plugins

确认 GitHub、Chrome、Browser、MCP 或 Agent 相关插件仍然可用。之后调用 GPT 模型时，Codex 会读取 OPENAI_API_KEY 和 OPENAI_BASE_URL，通过 https://api.magickapi.com/v1 请求 Magick API。

备用：写入 Codex provider 配置

如果你不想依赖环境变量，也可以把 Magick API 写进 Codex 的 provider 配置。

配置文件路径：

• macOS/Linux：~/.codex/config.toml
• Windows：%userprofile%\.codex\config.toml

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.magickapi.com/v1"
wire_api = "responses"
requires_openai_auth = true

然后在 auth 文件中写入 API Key。

auth 文件路径：

• macOS/Linux：~/.codex/auth.json
• Windows：%userprofile%\.codex\auth.json

{
  "OPENAI_API_KEY": "后台生成的KEY"
}

说明

• OPENAI_API_KEY 请填写 Magick API 后台生成的密钥
• OPENAI_BASE_URL 或 provider base_url 必须填写为 https://api.magickapi.com/v1
• token 模式只负责把模型请求转发到 Magick API；Codex 帐号授权登录用于保留 Codex 自身能力、插件和工具体验
• 当前文档中的 model 与 review_model 均使用 gpt-5.5，可自行切换【模型广场】中支持的模型