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

# Codex 常见问题

> 使用吉吉API 配置 Codex 时的常见问题。

## 安装与更新

<AccordionGroup>
  <Accordion title="提示命令未找到">
    安装完成后需要**打开一个新的终端窗口**再运行 `codex`。

    使用官方安装脚本或 Homebrew 安装的，重新运行一次安装命令即可。

    使用 npm 安装的，确认 npm 全局目录已加入 PATH：

    ```bash theme={null}
    npm config get prefix
    # 把输出目录下的 bin 加入 PATH，例如：
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Accordion>

  <Accordion title="如何更新 Codex">
    * **官方安装脚本**：重新运行安装命令即可更新到最新版
    * **Homebrew**：`brew upgrade --cask codex`
    * **npm**：`npm i -g @openai/codex@latest --registry=https://registry.npmmirror.com`
  </Accordion>

  <Accordion title="安装失败">
    1. 官方安装脚本需要访问 `chatgpt.com`，无法访问时改用 npm 国内镜像
    2. npm 方式需要 Node.js 18 或更高版本，参考 [Node.js 环境配置](/environment/setup)
  </Accordion>
</AccordionGroup>

## 配置问题

<AccordionGroup>
  <Accordion title="配置文件在哪里">
    * **macOS/Linux**：`~/.codex/`
    * **Windows**：`C:\Users\你的用户名\.codex\`（在 WSL 中使用时为 WSL 内的 `~/.codex/`）

    需要 `config.toml` 和 `auth.json` 两个文件。

    <Warning>
      Windows 下用记事本新建文件时，注意文件名不要变成 `config.toml.txt`。
    </Warning>
  </Accordion>

  <Accordion title="请求地址要不要加 /v1">
    要。Codex 使用 OpenAI 格式，请求地址**必须**以 `/v1` 结尾，且只写一次：

    ```toml theme={null}
    base_url = "https://www.jiji.cc/v1"
    ```

    报错中出现 `/v1/v1/responses`，说明 `/v1` 写了两次。
  </Accordion>

  <Accordion title="auth.json 怎么写">
    `auth.json` 中填写完整的 API Key，不是环境变量名：

    ```json theme={null}
    {
      "OPENAI_API_KEY": "your-api-key-here"
    }
    ```
  </Accordion>

  <Accordion title="修改配置后不生效">
    * `model_provider`、`model` 等顶层配置必须写在 `[model_providers.jiji]` 这一行**之前**，写在后面会被当作 `jiji` 的子配置
    * `model_provider` 的值必须和 `[model_providers.xxx]` 中的名称完全一致
    * 服务商配置只在用户目录的 `~/.codex/config.toml` 中生效，写在项目目录 `.codex/config.toml` 中会被忽略
    * 修改后需要退出并重新启动 Codex
  </Accordion>

  <Accordion title="开启联网搜索">
    在 `config.toml` 开头加入：

    ```toml theme={null}
    web_search = "live"
    ```

    可选值：`"live"`（实时联网搜索）、`"cached"`（默认，使用缓存索引）、`"disabled"`（关闭搜索）。
  </Accordion>

  <Accordion title="配置全局提示词">
    在 `~/.codex/` 目录下新建 `AGENTS.md`，写入你的提示词，重启 Codex 后生效。
  </Accordion>
</AccordionGroup>

## 模型使用

<AccordionGroup>
  <Accordion title="如何切换模型">
    * **修改配置文件**：修改 `config.toml` 中 `model` 的值，保存后重启 Codex
    * **启动时指定**：`codex -m gpt-6.1-sol -c model_reasoning_effort="high"`
    * **会话中切换**：在对话界面输入 `/model`

    可用的模型 ID 以 [模型广场](https://www.jiji.cc/extension/models) 为准。
  </Accordion>

  <Accordion title="常用命令">
    | 命令 | 说明 |
    | - | - |
    | `/model` | 切换模型和思考强度 |
    | `/review` | 审查当前改动 |
    | `/resume` | 继续历史会话 |
    | `/compact` | 压缩上下文 |
    | `/mcp` | 查看 MCP 工具 |
  </Accordion>
</AccordionGroup>

## 错误排查

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

    系统中已有的 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 环境变量可能覆盖配置文件。

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      env | grep OPENAI
      ```

      ```bat Windows CMD theme={null}
      echo %OPENAI_API_KEY%
      echo %OPENAI_BASE_URL%
      ```
    </CodeGroup>

    如有输出，macOS/Linux 从 `~/.zshrc` 或 `~/.bashrc` 中删除对应的 `export` 行；Windows 运行 `setx OPENAI_API_KEY ""` 和 `setx OPENAI_BASE_URL ""` 清除。然后重新打开终端。

    **检查配置文件**

    * `auth.json` 中的 API Key 是否完整、没有多余空格
    * Key 所在分组是否包含当前使用的模型
  </Accordion>

  <Accordion title="提示模型不存在">
    `model` 填写的模型 ID 不在 Key 所在分组中。到 [模型广场](https://www.jiji.cc/extension/models) 核对准确的模型 ID 和可用分组。
  </Accordion>

  <Accordion title="Connection failed 或 stream disconnected">
    1. 检查本机网络是否通畅
    2. 关闭代理工具后重试
    3. 只在 VS Code 扩展中出错时，先在命令行中测试，再重启 VS Code
  </Accordion>

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

## 仍未解决？

<Card title="提交工单" icon="headset" href="https://www.jiji.cc/extension/tickets">
  以上方法都无法解决时，请提交工单联系我们
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.