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

# 常见问题

> ruoli 使用中的常见问题

<AccordionGroup>
  <Accordion title="如何在 Codex 中调用 gpt-image-2？">
    你不需要把 Codex 的模型切换成 `gpt-image-2`。

    <Warning>
      <strong>不要单独使用 <code>gpt-image-2</code> 作为 Codex 主模型。</strong>它是专门负责画图的模型，不能代替 Codex 正常使用的对话和编程模型。
    </Warning>

    Codex 的主模型继续使用 `gpt-5.6`，也可以使用其他支持对话和编程的模型。当你让 Codex 生成图片时，Codex 会在后台调用 `gpt-image-2`。

    ### 第一步：正常配置 Codex

    先按照 [Codex 接入教程](/tools/codex) 配置 ruoli。下面这些内容保持正常即可：

    | 配置      | 填写内容                   |
    | ------- | ---------------------- |
    | 主模型     | `gpt-5.6` 或其他对话/编程模型   |
    | API 地址  | `https://ruoli.dev/v1` |
    | API Key | 你在 ruoli 控制台创建的令牌      |

    ### 第二步：开启 Codex 生图能力

    打开 CC Switch，依次进入 **Codex → 编辑供应商 → 配置 JSON**。

    找到当前使用的 `[model_providers.你的供应商名称]`，在下面加入这两行：

    ```toml theme={null}
    requires_openai_auth = false
    http_headers = { "x-openai-actor-authorization" = "local-image-extension" }
    ```

    配置位置可以参考下图红框中的内容：

    <Frame>
      <img src="https://mintcdn.com/yibinuniversity/Y85HGlqkhsyhjf72/images/codex/image-generation-config.png?fit=max&auto=format&n=Y85HGlqkhsyhjf72&q=85&s=5bc899824fcd8558d7f9176416ad1788" alt="在 Codex 供应商配置中开启 gpt-image-2 生图能力" width="1800" height="1200" data-path="images/codex/image-generation-config.png" />
    </Frame>

    保存配置，然后重启 Codex。

    ### 第三步：直接告诉 Codex 你想画什么

    不需要输入 API 命令，也不需要手动切换模型。直接对 Codex 说：

    ```text theme={null}
    帮我生成一张赛博朋克风格的上海夜景，画面比例 16:9。
    ```

    Codex 会理解你的要求，并自行调用 `gpt-image-2` 生成图片。

    <Info>
      令牌需要选择 `gpt-pro` 分组。如果提示“没有可用渠道”，请先检查令牌是否选对了分组。
    </Info>
  </Accordion>

  <Accordion title="如何调用生图模型 API？">
    如果你要在自己的程序、脚本或网站中生成图片，可以直接调用生图 API。这种方式不经过 Codex。

    调用前准备好下面三项：

    | 项目      | 填写内容                                      |
    | ------- | ----------------------------------------- |
    | API 地址  | `https://ruoli.dev/v1/images/generations` |
    | API Key | 你在 ruoli 控制台创建的令牌                         |
    | 模型名称    | `gpt-image-2`                             |

    ### 直接调用示例

    把下面的 `sk-你的KEY` 换成自己的令牌，然后运行：

    ```bash theme={null}
    curl https://ruoli.dev/v1/images/generations \
      -H "Authorization: Bearer sk-你的KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-image-2",
        "prompt": "一只戴着宇航员头盔的橘猫，坐在月球上，电影感光影"
      }'
    ```

    `prompt` 后面的文字就是你想生成的画面，可以直接替换成自己的描述。

    ### 不会写代码？交给 Agent 配置

    把下面这段话复制给 Codex 或其他编程 Agent。将 `sk-你的KEY` 替换成自己的令牌即可：

    ```text theme={null}
    请帮我创建一个调用生图模型的 Skill，并测试它能否正常生成图片。

    API 地址：https://ruoli.dev/v1/images/generations
    API Key：sk-你的KEY
    模型名称：gpt-image-2

    请使用 OpenAI 兼容的 Images API，通过 Authorization: Bearer 传递密钥。
    不要把 API Key 写进 Skill 文件或提交到 Git，请将它保存到 RUOLI_API_KEY 环境变量中。
    Skill 需要让我输入画面描述，然后调用接口生成并保存图片。
    完成后，请用通俗的步骤告诉我以后怎样使用这个 Skill。
    ```

    <Warning>不要把真实 API Key 发给陌生人，也不要上传到公开仓库。</Warning>
  </Accordion>

  <Accordion title="如何在 Codex 中开启 Fast 模式？">
    Fast 模式可以理解成给 Codex 走“优先通道”。开启后，请求会使用 `priority` 服务等级。

    <Steps>
      <Step title="打开 Codex 配置 JSON">
        打开 CC Switch，依次进入 **Codex → 编辑供应商 → 配置 JSON**。
      </Step>

      <Step title="加入 Fast 模式配置">
        在配置顶部找到 `model`、`model_reasoning_effort` 等通用设置，在同一区域加入下面这一行：

        ```toml theme={null}
        service_tier = "priority"
        ```

        配置位置可以参考下图红框：

        <Frame>
          <img src="https://mintcdn.com/yibinuniversity/Y85HGlqkhsyhjf72/images/codex/fast-mode-config.png?fit=max&auto=format&n=Y85HGlqkhsyhjf72&q=85&s=ce324b5e1c10dcf834e1f6214476d9d4" alt="在 Codex 配置 JSON 中设置 service_tier 为 priority" width="1800" height="1200" data-path="images/codex/fast-mode-config.png" />
        </Frame>

        <Warning>
          `service_tier` 要放在顶部的通用配置区域，不要放进 `[model_providers]` 或某个供应商配置里面。
        </Warning>
      </Step>

      <Step title="保存并重启 Codex">
        点击 **保存**，然后完全退出并重新打开 Codex。重启后，Fast 模式就会生效。
      </Step>
    </Steps>

    如果以后不想使用 Fast 模式，删除 `service_tier = "priority"` 这一行，再重启 Codex 即可。
  </Accordion>

  <Accordion title="出现 Stream disconnected before completion 怎么办？">
    这句报错的意思是：Codex 还没回答完，连接就提前断开了。它不一定是中转服务的问题，可以按下面四步依次排查。

    <Steps>
      <Step title="检查自己的网络">
        网络不稳定是最常见的原因。连接就像通话，网络中途抖了一下，Codex 的回答也会跟着中断。

        你可以尝试：

        * 关闭再重新打开代理工具（梯子）
        * 切换代理节点
        * 在 Wi-Fi 和手机热点之间切换
        * 网络恢复后，重新发送刚才的问题

        如果重试后可以正常回答，通常就是本地网络临时波动。
      </Step>

      <Step title="检查对话是不是太长了">
        聊得越久，Codex 需要携带的上下文越多。当内容超过模型的上下文上限时，请求可能无法正常完成。

        最简单的处理方法是：**新建一个对话，再重新提问。**

        如果新对话可以正常回答，原来的对话大概率已经太长。需要保留之前的信息时，可以先让 Codex 总结重点，再把总结复制到新对话。
      </Step>

      <Step title="检查问题是否触发安全拒答">
        如果问题涉及违法操作、恶意攻击、危险行为或其他高风险内容，OpenAI 可能拒绝继续回答，连接也可能提前结束。

        请检查自己的问题是否容易被理解成危险用途，并换成合法、安全、说明真实目的的问法。不要尝试绕过模型的安全限制。
      </Step>

      <Step title="检查中转服务是否异常">
        如果网络正常、换了新对话、问题也没有风险，但仍然连续报错，可能是中转渠道临时异常。

        这时先查看群消息，确认是否有故障通知或维护公告。如果群里已经有人反馈同样的问题，等待服务恢复后再试即可。
      </Step>
    </Steps>

    <Info>建议按顺序排查。不要一看到报错就认定是中转炸了，前三种情况也很常见。</Info>
  </Accordion>

  <Accordion title="Claude Code 缓存命中率低、费用偏高？">
    八成是 Claude Code 默认开启的归属 header 在作祟 —— 每次请求携带动态会话 ID，会直接击穿上游 prompt cache。

    在 CC Switch「编辑供应商 → 配置 JSON」的 `env` 里加一行：

    ```json theme={null}
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
    ```

    不论用 Claude 官方还是第三方模型都建议关闭。详见 [关闭归属 Header](/tools/claude-code#关闭归属-header)。
  </Accordion>
</AccordionGroup>