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

# Codex

> Codex 常见问题解答

## 安装与更新

<AccordionGroup>
  <Accordion title="命令未找到">
    **macOS Homebrew 安装**

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

    **NPM 安装**

    确保 npm 全局路径已添加到 PATH

    ```bash theme={null}
    npm config get prefix
    # 添加到 PATH
    echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Accordion>

  <Accordion title="如何更新 Codex">
    **Homebrew**

    ```bash theme={null}
    brew upgrade codex
    ```

    **NPM**

    ```bash theme={null}
    npm i -g @openai/codex --registry=https://registry.npmmirror.com
    ```
  </Accordion>

  <Accordion title="安装失败">
    **排查步骤**

    1. 检查网络连接
    2. 确保 Node.js 18+ 已安装（NPM 方式）
    3. Windows 用户确保在 WSL 环境中安装
    4. 使用镜像源：
       ```bash theme={null}
       npm i -g @openai/codex --registry=https://registry.npmmirror.com
       ```
  </Accordion>

  <Accordion title="Windows 必须使用 WSL">
    Codex 不支持原生 Windows，必须在 WSL 中运行

    **安装 WSL**

    ```powershell theme={null}
    wsl --install
    ```

    **在 WSL 中安装 Codex**

    ```bash theme={null}
    npm i -g @openai/codex --registry=https://registry.npmmirror.com
    ```
  </Accordion>
</AccordionGroup>

## 配置问题

<AccordionGroup>
  <Accordion title="配置文件在哪里">
    * **macOS/Linux**: `~/.codex/`
    * **Windows**: `C:\Users\你的用户名\.codex\`

    需要两个文件：`config.toml` 和 `auth.json`
  </Accordion>

  <Accordion title="API 端点配置">
    Codex 使用 OpenAI 兼容格式，端点**必须包含** `/v1` 路径

    ```toml theme={null}
    base_url = "https://code.rayinai.com/v1"
    ```
  </Accordion>

  <Accordion title="API Key 配置">
    `auth.json` 中应使用完整的 API Key，不是环境变量名

    **正确示例**

    ```json theme={null}
    {
      "OPENAI_API_KEY": "sk_xxxxxxxxxx"
    }
    ```

    **错误示例**

    ```json theme={null}
    {
      "OPENAI_API_KEY": "CODEX_API_KEY"
    }
    ```
  </Accordion>

  <Accordion title="Windows 特殊配置">
    Windows 用户需要在 `config.toml` 中添加

    ```toml theme={null}
    windows_wsl_setup_acknowledged = true
    ```
  </Accordion>

  <Accordion title="开启网络搜索">
    在 `config.toml` 中添加

    ```toml theme={null}
    [features]
    web_search_request = true
    ```
  </Accordion>

  <Accordion title="配置全局提示词">
    在 `~/.codex` 目录创建 `AGENTS.md` 文件，写入自定义提示词后重启生效
  </Accordion>
</AccordionGroup>

## 模型使用

<AccordionGroup>
  <Accordion title="如何使用最新模型">
    **方法一：修改配置文件（推荐）**

    1. 打开 `config.toml`，找到 `model = "gpt-5.2"`
    2. 改为 `model = "gpt-5.3-codex"`
    3. 保存后重启客户端

    <Warning>
      启用后不要在会话中切换模型
    </Warning>

    **方法二：CLI 启动参数**

    ```bash theme={null}
    codex -m gpt-5.3-codex -c model_reasoning_effort="xhigh"
    ```

    **方法三：VSCode 插件（v0.5.72）**

    1. 确保使用预发布版本
    2. 找到插件目录：
       * **Windows**: `%userprofile%\.vscode\extensions`
       * **macOS**: `~/.vscode/extensions`
    3. 找到 `openai.chatgpt-0.5.72-*` 文件夹
    4. 进入 `webview\assets` 目录
    5. 替换对应的 js 文件
    6. 重启 VSCode
  </Accordion>

  <Accordion title="常用命令">
    | 命令         | 说明        |
    | ---------- | --------- |
    | `/model`   | 选择模型      |
    | `/review`  | 审查变更      |
    | `/resume`  | 继续历史会话    |
    | `/compact` | 压缩上下文     |
    | `/undo`    | 撤销操作      |
    | `/mcp`     | 查看 MCP 工具 |
  </Accordion>
</AccordionGroup>

## 错误排查

<AccordionGroup>
  <Accordion title="Connection failed">
    **排查步骤**

    1. 检查本机网络是否通畅
    2. 关闭代理工具
    3. 在 CLI 中测试是否为 VS Code 插件问题
    4. 重启 VS Code
  </Accordion>

  <Accordion title="401 错误">
    **检查环境变量冲突**

    ```bash theme={null}
    # Windows
    echo %OPENAI_API_KEY%
    echo %OPENAI_BASE_URL%
    ```

    如果有输出，清除环境变量

    ```bash theme={null}
    setx OPENAI_API_KEY ""
    setx OPENAI_BASE_URL ""
    ```

    **检查配置文件**

    * `~/.codex/auth.json` 中的 API Key 是否正确
    * `~/.codex/config.toml` 中的 base\_url 是否包含 `/v1`
  </Accordion>

  <Accordion title="403 错误">
    通常是号池账号问题

    1. 停止当前对话（Ctrl+C）
    2. 重新发起对话
    3. 如果重试 3 次以上无效，联系技术支持
  </Accordion>

  <Accordion title="Windows 乱码问题">
    **解决步骤**

    1. 按 `Win + R`，输入 `intl.cpl` 回车
    2. 点击「管理」选项卡
    3. 点击「更改系统区域设置」
    4. 勾选「Beta: 使用 Unicode UTF-8 提供全球语言支持」
    5. 确定后重启电脑
  </Accordion>
</AccordionGroup>

## 其他问题

<Card title="联系技术支持" icon="headset" href="mailto:support@rayinai.com">
  如果以上方法无法解决问题，请联系技术支持
</Card>