> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> 在 Codex CLI 或支持本地配置的 Codex 环境中使用 Moxus AI 的 OpenAI 兼容接口。

Codex CLI 通过本地配置选择模型提供方。Moxus AI 的接入方式是：在 Codex 的 `config.toml` 中新增一个自定义 provider，并让 Codex 通过环境变量或 `auth.command` 读取 API 密钥。

<Warning>
  本页适用于支持 `config.toml` 和自定义 `model_providers` 的 Codex CLI / 本地 Codex 环境。不同 Codex 版本可能存在配置差异；如果你的版本提示字段不支持，请以当前 Codex 的报错和内置说明为准。
</Warning>

## 配置值

| 项            | 值                        |
| ------------ | ------------------------ |
| Base URL     | `https://moxus.cloud/v1` |
| API Key      | `你的密钥`                   |
| API Key 环境变量 | `MOXUS_API_KEY`          |
| Provider 名称  | `custom`                 |
| 默认请求方式       | Responses API            |
| 模型           | 在“模型广场”复制完整模型名称          |

## 安装 Codex CLI

先安装，再单独执行版本检查。不要把安装命令、更新命令、验证命令放在同一个代码块里一起复制运行。

<Tabs>
  <Tab title="macOS / Linux">
    安装：

    ```bash theme={null}
    curl -fsSL https://chatgpt.com/codex/install.sh | sh
    ```

    验证：

    ```bash theme={null}
    codex --version
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    安装：

    ```powershell theme={null}
    powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
    ```

    如果安装完成后当前窗口仍提示 `codex` 无法识别，先刷新当前 PowerShell 的 `PATH`：

    ```powershell theme={null}
    $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
    ```

    验证：

    ```powershell theme={null}
    codex --version
    ```
  </Tab>

  <Tab title="npm">
    安装：

    ```bash theme={null}
    npm install -g @openai/codex
    ```

    验证：

    ```bash theme={null}
    codex --version
    ```
  </Tab>

  <Tab title="Homebrew">
    安装：

    ```bash theme={null}
    brew install --cask codex
    ```

    验证：

    ```bash theme={null}
    codex --version
    ```
  </Tab>
</Tabs>

## 推荐方式：从 API 密钥导入配置

在 Moxus AI 的“API 密钥”页面，每个密钥的操作菜单里都有“导入配置”。选择 Codex 后，页面会生成适合当前密钥和当前站点地址的终端脚本。

<Steps>
  <Step title="打开 API 密钥页面">
    进入 Moxus AI 控制台的“API 密钥”页面，找到准备用于 Codex 的密钥。
  </Step>

  <Step title="打开导入配置">
    在该密钥所在行打开操作菜单，选择“导入配置”，然后切换到 `Codex`。
  </Step>

  <Step title="复制对应系统的脚本">
    macOS、Linux 使用 “macOS / Linux terminal” 脚本；Windows 使用 “Windows PowerShell” 脚本。
  </Step>

  <Step title="直接在终端执行脚本">
    打开终端，将刚复制的脚本直接粘贴到同一个终端窗口并按回车。脚本兼容 zsh 和 Bash；执行完成后，当前窗口立即可使用新配置。
  </Step>
</Steps>

导入配置脚本的行为如下：

| 系统                 | 写入内容                                                                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS / Linux      | 写入 `${CODEX_HOME:-$HOME/.codex}/config.toml`，创建 `${CODEX_HOME:-$HOME/.codex}/moxus-env.sh` 保存 `MOXUS_API_KEY`，并在 `~/.zshrc` 和 `~/.bashrc` 中加入自动加载配置                             |
| Windows PowerShell | 写入 `%USERPROFILE%\.codex\config.toml`，写入 `%USERPROFILE%\.codex\moxus-api-key.txt` 保存密钥，并在 `config.toml` 中使用 `auth.command` 读取该文件；同时把 `MOXUS_API_KEY` 写入当前 Windows 用户环境变量，兼容终端调用 |

<Warning>
  当前导入配置脚本会覆盖 Codex 的 `config.toml`。如果你已经配置过其他 provider、模型、沙箱或项目默认值，请先备份原文件，再执行导入脚本。
</Warning>

<Info>
  macOS、Linux 使用“macOS / Linux terminal”脚本；Windows 使用 PowerShell 脚本。两种脚本均可在对应终端中直接粘贴执行，不需要创建文件或运行额外命令。
</Info>

## Codex 配置文件位置

Codex 默认读取用户目录下的 `.codex/config.toml`。如果你设置过 `CODEX_HOME`，配置文件会改为 `$CODEX_HOME/config.toml`。

<Tabs>
  <Tab title="macOS">
    默认路径：`/Users/你的用户名/.codex/config.toml`

    创建目录：

    ```bash theme={null}
    mkdir -p ~/.codex
    ```

    打开目录：

    ```bash theme={null}
    open ~/.codex
    ```
  </Tab>

  <Tab title="Linux">
    默认路径：`/home/你的用户名/.codex/config.toml`

    创建目录：

    ```bash theme={null}
    mkdir -p ~/.codex
    ```

    查看文件：

    ```bash theme={null}
    ls ~/.codex/config.toml
    ```
  </Tab>

  <Tab title="Windows">
    默认路径：`C:\Users\你的用户名\.codex\config.toml`

    创建目录：

    ```powershell theme={null}
    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"
    ```

    打开目录：

    ```powershell theme={null}
    explorer $env:USERPROFILE\.codex
    ```
  </Tab>
</Tabs>

文件名必须是 `config.toml`。如果使用记事本创建，请确认它不是 `config.toml.txt`。

## 手动配置 config.toml

如果你不使用“导入配置”，可以手动创建或编辑 `config.toml`：

```toml theme={null}
model_provider = "custom"
model = "gpt-5.4"

[model_providers.custom]
name = "custom"
base_url = "https://moxus.cloud/v1"
env_key = "MOXUS_API_KEY"
requires_openai_auth = false
wire_api = "responses"
```

关键字段含义：

| 字段                     | 说明                                                    |
| ---------------------- | ----------------------------------------------------- |
| `model_provider`       | 当前默认使用的 provider 名称，要和 `[model_providers.custom]` 对应  |
| `model`                | Codex 默认使用的模型名称，可改成“模型广场”里的完整模型名                      |
| `base_url`             | Moxus AI 的 OpenAI 兼容地址，Codex 会通过它发起请求                 |
| `env_key`              | Codex 从 `MOXUS_API_KEY` 读取密钥，不需要把密钥直接写进 `config.toml` |
| `requires_openai_auth` | 设为 `false`，表示不走 OpenAI 官方登录鉴权                         |
| `wire_api`             | 设为 `responses`，表示按 Responses API 方式请求                 |

## 手动设置 API 密钥

### 仅当前终端

这种方式适合临时测试。macOS / Linux 只替换当前一次启动读取的密钥；Windows 会同时覆盖当前启动的 provider 配置，因为“导入配置”生成的 Windows `config.toml` 使用 `auth.command` 读取密钥文件。关闭终端后变量会失效。

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    MOXUS_API_KEY="你的密钥" codex \
      -c 'model_provider = "custom"' \
      -c 'model = "gpt-5.4"' \
      -c 'model_providers.custom = { name = "custom", base_url = "https://moxus.cloud/v1", env_key = "MOXUS_API_KEY", requires_openai_auth = false, wire_api = "responses" }'
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    复制整个代码块执行。它仅对这一次启动生效，不会改动现有 `config.toml` 或密钥文件：

    ```powershell theme={null}
    $env:MOXUS_API_KEY="你的密钥"
    codex `
      -c 'model_provider = "moxus_temp"' `
      -c 'model = "gpt-5.4"' `
      -c 'model_providers.moxus_temp.name = "moxus_temp"' `
      -c 'model_providers.moxus_temp.base_url = "https://moxus.cloud/v1"' `
      -c 'model_providers.moxus_temp.env_key = "MOXUS_API_KEY"' `
      -c 'model_providers.moxus_temp.requires_openai_auth = false' `
      -c 'model_providers.moxus_temp.wire_api = "responses"'
    ```
  </Tab>
</Tabs>

需要长期保存或在桌面端使用时，直接在“API 密钥”页面的“导入配置”中选择 Codex。脚本会同时写入 provider 配置和密钥，并处理对应系统的启动环境。

## 验证方式

先确认 Codex 能读取配置文件和环境变量，再运行一个小任务。

检查密钥变量：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    echo "$MOXUS_API_KEY"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    echo $env:MOXUS_API_KEY
    ```
  </Tab>
</Tabs>

运行测试任务：

```bash theme={null}
codex "hello"
```

如果调用成功，再到 [控制台与用量](/zh/platform/dashboard-and-usage) 查看 API 活动记录，确认请求来自对应密钥。

## 常见问题

<AccordionGroup>
  <Accordion title="可以把 API Key 直接写进 config.toml 吗？">
    不建议。当前 `/keys` 新生成的 Windows Codex 脚本不会把明文密钥写进 `config.toml`，而是写入 `%USERPROFILE%\.codex\moxus-api-key.txt`，再通过 `auth.command` 读取；macOS / Linux 仍通过环境变量读取。这样不会把明文密钥直接写入 `config.toml`，也更容易轮换密钥。
  </Accordion>

  <Accordion title="导入配置后原来的 Codex 配置没了">
    `/keys` 生成的 Codex 脚本会覆盖 `config.toml`。如果你已有自定义配置，先备份原文件，或手动把 `[model_providers.custom]` 合并进现有配置。
  </Accordion>

  <Accordion title="如何删除 Codex 的 Moxus AI 配置？">
    若 `config.toml` 是由“导入配置”脚本单独生成的，可使用以下命令删除 Moxus AI 配置、密钥和当前会话变量。若你已经在该文件中合并了其他 provider 或个人设置，请不要删除整个 `config.toml`，只移除其中的 `custom` provider 配置。

    macOS / Linux：

    ```bash theme={null}
    CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"

    rm -f "$CODEX_DIR/config.toml" "$CODEX_DIR/moxus-env.sh"

    for profile in "$HOME/.zshrc" "$HOME/.bashrc"; do
      [ -f "$profile" ] || continue
      sed -i.bak '/# Moxus AI Codex start/,/# Moxus AI Codex end/d' "$profile"
    done

    unset MOXUS_API_KEY
    if command -v launchctl >/dev/null 2>&1; then
      launchctl unsetenv MOXUS_API_KEY
    fi
    ```

    Windows PowerShell：

    ```powershell theme={null}
    $CodexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }

    Remove-Item (Join-Path $CodexDir "config.toml") -Force -ErrorAction SilentlyContinue
    Remove-Item (Join-Path $CodexDir "moxus-api-key.txt") -Force -ErrorAction SilentlyContinue

    [Environment]::SetEnvironmentVariable("MOXUS_API_KEY", $null, "User")
    Remove-Item Env:MOXUS_API_KEY -ErrorAction SilentlyContinue
    ```

    完全退出并重新打开 Codex；macOS 桌面端也需要重新启动应用。
  </Accordion>

  <Accordion title="提示认证失败">
    先区分你使用的是哪种配置方式：如果 `config.toml` 里使用 `env_key = "MOXUS_API_KEY"`，确认启动 Codex 的终端或图形环境能读取该变量；终端配置后需要重新打开终端，Windows 图形界面客户端可能还需要重新登录系统。如果你使用的是 `/keys` 页面最新生成的 Windows 脚本，确认 `%USERPROFILE%\.codex\moxus-api-key.txt` 存在，并确认 `config.toml` 中的 `[model_providers.custom.auth]` 没被旧配置覆盖；然后完全退出并重新打开 Codex。
  </Accordion>

  <Accordion title="Windows 安装后执行 codex --version 提示找不到命令">
    这通常不是安装失败，而是安装脚本刚写入了新的 `PATH`，但当前 PowerShell 窗口还没刷新。先执行：

    ```powershell theme={null}
    $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
    ```

    然后再执行 `codex --version`。如果仍不行，关闭当前 PowerShell，重新打开一个新窗口后再试。
  </Accordion>

  <Accordion title="提示模型不存在">
    把 `model` 改成“模型广场”里的完整模型名称。不要使用客户端内置展示名或简称。
  </Accordion>

  <Accordion title="提示 wire_api 或 provider 字段不支持">
    说明当前 Codex 版本的自定义 provider 格式不同。保留 `base_url` 和 API Key，按当前 Codex 的报错提示调整 `wire_api` 或 provider 字段。
  </Accordion>
</AccordionGroup>

## 相关文档

* [快速入门](/zh/overview/quickstart)
* [API 密钥](/zh/platform/account-and-keys)