𝐘𝐀𝐈 为 AI 行业的开拓者提供坚如磐石的基础设施支撑 [支持私有化部署] Zola 2026-07-08T00:00:00+00:00 https://xaicontrol.com/atom.xml 进阶能力 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/advanced/ <h2 id="goals">Goals</h2> <p>Goal 适合长时间、多步骤、需要持续推进的任务。它比普通“继续做”更清楚，因为目标、预算和完成条件更明确。</p> <p>继续阅读：<a href="/blog/codex-goals-guide/">Codex Goals 使用指南：为什么 <code>/goal</code> 比“继续做”更强</a></p> <h2 id="skills">Skills</h2> <p>Skill 是可复用的任务能力，通常包含说明、参考资料和脚本。它适合把重复工作沉淀成稳定流程。</p> <p>继续阅读：<a href="/blog/codex-skills/">从 imagegen 开始认识 Codex Skill：普通用户快速上手</a></p> <h2 id="plugins">Plugins</h2> <p>Plugin 是更完整的扩展包，可以包含 skills、命令、MCP 配置、hooks、资源文件和 marketplace 元数据。</p> <p>继续阅读：</p> <ul> <li><a href="/blog/codex-plugins-guide/">OpenAI Codex Plugins 导读：插件目录、安装方式与本地打包入门</a></li> <li><a href="/blog/xai-router-codex-plugins-enable/">XAI Router 启用 Codex App 插件</a></li> </ul> <h2 id="subagents">Subagents</h2> <p>Subagents 适合把复杂任务交给不同角色的代理并行处理，例如代码审查、测试补全、安全检查。</p> <p>继续阅读：<a href="/blog/codex-subagents-xai-router/">Codex Subagents 使用说明：跑多代理工作流</a></p> <h2 id="mcp">MCP</h2> <p>MCP 用来把外部工具、数据源或内部系统接入 Codex。普通用户不需要一开始就学 MCP；当你需要 Codex 访问公司系统、私有工具或结构化数据时再考虑。</p> <h2 id="wen-zhang-suo-yin">文章索引</h2> <ul> <li><a href="/blog/codex-app-install-config-guide/">OpenAI Codex App 安装与配置上手指南（macOS / Windows）</a></li> <li><a href="/blog/how-openai-uses-codex/">OpenAI 如何在内部使用 Codex：7 个工程场景与实践方法</a></li> <li><a href="/blog/codex-cloud/">XAI Router Codex 包月服务：Codex / OpenClaw / OpenCode 接入</a></li> <li><a href="/blog/codex-gpt-5-5-xai-router/">在 Codex 中使用 GPT-5.5：升级到最新版即可开启</a></li> </ul> 配置与登录 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/config/ <h2 id="pei-zhi-wen-jian-zai-na-li">配置文件在哪里</h2> <p>常见位置：</p> <table><thead><tr><th>环境</th><th>配置文件</th></tr></thead><tbody> <tr><td>macOS / Linux</td><td><code>~/.codex/config.toml</code></td></tr> <tr><td>Windows 原生</td><td><code>%USERPROFILE%\.codex\config.toml</code></td></tr> <tr><td>WSL2</td><td>WSL 内的 <code>~/.codex/config.toml</code></td></tr> </tbody></table> <p>Windows 原生和 WSL2 是两个环境。你在 Windows 里改 <code>%USERPROFILE%\.codex\config.toml</code>，不会自动影响 WSL 内运行的 <code>codex</code>。</p> <h2 id="codex-home">CODEX_HOME</h2> <p>如果设置了 <code>CODEX_HOME</code>，Codex 会使用这个目录作为配置和状态目录。</p> <p>Linux / macOS：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> CODEX_HOME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$HOME</span><span style="color: #9ECBFF;">/.codex&quot;</span></span></code></pre> <p>PowerShell：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="powershell"><span class="giallo-l"><span>$</span><span style="color: #79B8FF;">env:</span><span>CODEX_HOME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">$HOME</span><span style="color: #9ECBFF;">\.codex&quot;</span></span></code></pre> <p>普通用户不需要主动设置 <code>CODEX_HOME</code>。只有当你想共享配置、切换多套环境或把 WSL 指向 Windows 配置目录时才需要。</p> <h2 id="deng-lu-fang-shi">登录方式</h2> <p>Codex 常见登录方式：</p> <ol> <li>ChatGPT 账号登录。</li> <li>OpenAI API Key 登录。</li> <li>自定义 provider，例如 XAI Router。</li> </ol> <p>如果你已经有 ChatGPT Plus / Pro / Business / Edu / Enterprise，通常优先使用 ChatGPT 登录。需要企业统一管理、模型路由或包月额度时，再配置 XAI Router。</p> <h2 id="chang-yong-pei-zhi-shi-li">常用配置示例</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;on-request&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;workspace-write&quot;</span></span> <span class="giallo-l"><span>preferred_auth_method =</span><span style="color: #9ECBFF;"> &quot;apikey&quot;</span></span></code></pre> <p>这表示 Codex 默认在工作区内写文件，需要更高权限时请求确认，并优先使用 API Key 方式。</p> <h2 id="pai-cha-shun-xu">排查顺序</h2> <p>配置不生效时，按这个顺序检查：</p> <ol> <li>当前 <code>codex</code> 是在 Windows、WSL、macOS 还是 Linux 里运行。</li> <li>你改的是不是该环境里的 <code>config.toml</code>。</li> <li>环境变量是否在当前 shell 中生效。</li> <li>是否用 CLI 参数或 profile 覆盖了配置。</li> <li>是否需要重启 App 或重新打开终端。</li> </ol> 第一次使用 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/first-task/ <h2 id="da-kai-xiang-mu">打开项目</h2> <p>在终端中进入项目目录：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> your-project</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>如果你使用 App，打开 App 后选择项目目录。</p> <h2 id="di-yi-ge-ti-shi-ci">第一个提示词</h2> <p>建议从只读任务开始：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请先不要修改文件。帮我解释这个项目的目录结构、启动方式和测试方式。</span></span></code></pre> <p>这个任务能让你观察 Codex 如何读项目、如何总结信息，以及它是否理解当前仓库。</p> <h2 id="di-er-ge-ren-wu">第二个任务</h2> <p>让 Codex 做一个小修改：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请找一个最小的可改进点，先说明方案，等我确认后再修改。</span></span></code></pre> <p>确认后再让它执行：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>可以按方案修改。改完后运行相关测试，并告诉我修改了哪些文件。</span></span></code></pre><h2 id="hao-ren-wu-de-ge-shi">好任务的格式</h2> <p>一个清晰任务通常包含：</p> <ul> <li>目标：你希望完成什么。</li> <li>范围：只改哪些文件或模块。</li> <li>限制：不要做什么。</li> <li>验证：如何确认结果正确。</li> </ul> <p>例子：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>修复登录页按钮在移动端换行的问题。只改前端样式，不改接口逻辑。完成后运行前端 lint，并说明影响范围。</span></span></code></pre><h2 id="xin-shou-chang-jian-cuo-wu">新手常见错误</h2> <ul> <li>一上来就要求“完整重构整个项目”。</li> <li>没说是否允许改文件。</li> <li>没给验证方式。</li> <li>没有检查 Codex 的 diff 就继续让它改下一轮。</li> </ul> <p>把任务拆小，Codex 的结果通常更稳定。</p> 下载与安装 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/install/ <h2 id="macos">macOS</h2> <p>安装 CLI：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://chatgpt.com/codex/install.sh</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sh</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>也可以使用 Homebrew：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">brew</span><span style="color: #9ECBFF;"> install</span><span style="color: #79B8FF;"> --cask</span><span style="color: #9ECBFF;"> codex</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>打开桌面 App：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #9ECBFF;"> app</span></span></code></pre> <p>也可以访问官方 Codex App 页面：<a rel="external" href="https://chatgpt.com/codex?app-landing-page=true">https://chatgpt.com/codex?app-landing-page=true</a></p> <h2 id="windows-yuan-sheng">Windows 原生</h2> <p>如果你主要使用 Windows、PowerShell、VS Code，并且项目在 Windows 磁盘中，优先用原生方式：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="powershell"><span class="giallo-l"><span>powershell </span><span style="color: #F97583;">-</span><span>ExecutionPolicy ByPass </span><span style="color: #F97583;">-</span><span>c </span><span style="color: #9ECBFF;">&quot;irm https://chatgpt.com/codex/install.ps1 | iex&quot;</span></span> <span class="giallo-l"><span>codex</span></span></code></pre> <p>打开桌面 App：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="powershell"><span class="giallo-l"><span>codex app</span></span></code></pre> <p>建议先准备常见开发工具：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="powershell"><span class="giallo-l"><span>winget install </span><span style="color: #F97583;">--</span><span>id Git.Git</span></span> <span class="giallo-l"><span>winget install </span><span style="color: #F97583;">--</span><span>id OpenJS.NodeJS.LTS</span></span> <span class="giallo-l"><span>winget install </span><span style="color: #F97583;">--</span><span>id Python.Python.</span><span style="color: #79B8FF;">3</span></span> <span class="giallo-l"><span>winget install </span><span style="color: #F97583;">--</span><span>id GitHub.cli</span></span></code></pre><h2 id="windows-wsl2">Windows + WSL2</h2> <p>如果你的项目依赖 Linux 工具链，或者你本来就在 WSL 里开发，先安装 WSL2：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="powershell"><span class="giallo-l"><span>wsl </span><span style="color: #F97583;">--</span><span>install</span></span> <span class="giallo-l"><span>wsl</span></span></code></pre> <p>进入 WSL 后安装 Codex：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://chatgpt.com/codex/install.sh</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sh</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>推荐把项目放在 WSL 的 Linux home 目录中：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/code</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> ~/code</span></span></code></pre><h2 id="linux">Linux</h2> <p>Linux 用户直接安装 CLI：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://chatgpt.com/codex/install.sh</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sh</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>也可以通过 npm 安装：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">npm</span><span style="color: #9ECBFF;"> install</span><span style="color: #79B8FF;"> -g</span><span style="color: #9ECBFF;"> @openai/codex</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre><h2 id="jian-cha-an-zhuang">检查安装</h2> <p>运行：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #79B8FF;"> --version</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>如果 <code>codex</code> 能进入交互界面，说明 CLI 已可用。之后你可以继续配置登录方式、模型和权限策略。</p> 权限与安全 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/security/ <h2 id="liang-ge-guan-jian-ci">两个关键词</h2> <p><strong>Sandbox</strong> 控制 Codex 能访问和写入哪里。</p> <p><strong>Approval</strong> 控制 Codex 执行某些命令或越界操作前是否需要你确认。</p> <h2 id="xin-shou-tui-jian">新手推荐</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #79B8FF;"> --sandbox</span><span style="color: #9ECBFF;"> workspace-write</span><span style="color: #79B8FF;"> --ask-for-approval</span><span style="color: #9ECBFF;"> on-request</span></span></code></pre> <p>含义：</p> <ul> <li>Codex 可以在当前工作区内写文件。</li> <li>需要更高权限时会请求确认。</li> <li>你可以在执行前看到命令和理由。</li> </ul> <h2 id="jin-shen-shi-yong-quan-quan-xian">谨慎使用全权限</h2> <p><code>--yolo</code> 或 <code>danger-full-access</code> 会显著放宽限制。只建议在这些场景使用：</p> <ul> <li>临时容器。</li> <li>可丢弃虚拟机。</li> <li>只包含测试代码的目录。</li> <li>你已经有明确回滚方案。</li> </ul> <p>不要在生产机器、含敏感凭据的目录、个人主目录或重要数据盘里随意使用全权限。</p> <h2 id="cao-zuo-xi-guan">操作习惯</h2> <ul> <li>先让 Codex 说明计划，再允许修改。</li> <li>每轮修改后查看 diff。</li> <li>让 Codex 运行相关测试。</li> <li>对涉及删除、迁移、覆盖、权限提升的命令保持警惕。</li> <li>把密钥放在环境变量或密钥管理中，不要让 Codex 把密钥写进仓库。</li> </ul> <p>安全不是为了限制 Codex，而是为了让它在清晰边界内稳定工作。</p> 选择使用入口 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/surfaces/ <table><thead><tr><th>入口</th><th>适合场景</th><th>推荐人群</th></tr></thead><tbody> <tr><td>CLI</td><td>在终端中读写本地项目、运行命令</td><td>熟悉命令行的开发者</td></tr> <tr><td>App</td><td>桌面图形界面、多线程、项目管理</td><td>普通用户和希望少碰命令行的人</td></tr> <tr><td>IDE Extension</td><td>在 VS Code、Cursor、Windsurf 等编辑器中使用</td><td>编辑器优先的开发者</td></tr> <tr><td>Web / Cloud</td><td>云端执行任务、生成 PR、并行处理</td><td>团队协作和远程任务</td></tr> </tbody></table> <h2 id="xin-shou-zen-me-xuan">新手怎么选</h2> <p>如果你只是想体验 Codex，先用 <strong>Codex App</strong>。它更直观，也更容易看到项目、线程和任务。</p> <p>如果你是开发者，建议同时使用 <strong>Codex CLI</strong>。CLI 能让你更清楚地理解当前目录、权限、配置和命令执行结果。</p> <h2 id="shen-me-shi-hou-yong-cli">什么时候用 CLI</h2> <p>适合：</p> <ul> <li>你已经熟悉终端。</li> <li>你想让 Codex 直接在当前项目里工作。</li> <li>你需要明确控制 sandbox、approval、model、profile。</li> <li>你想把 Codex 接入脚本或自动化流程。</li> </ul> <p>启动方式：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> your-project</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre><h2 id="shen-me-shi-hou-yong-app">什么时候用 App</h2> <p>适合：</p> <ul> <li>你想用桌面界面选择项目。</li> <li>你想并行开多个 Codex 线程。</li> <li>你想更直观看到修改、预览和 Git 状态。</li> <li>你是非纯开发角色，但需要让 Codex 帮你处理项目。</li> </ul> <p>启动方式：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #9ECBFF;"> app</span></span></code></pre><h2 id="shen-me-shi-hou-yong-ide-kuo-zhan">什么时候用 IDE 扩展</h2> <p>适合你正在编辑器里写代码，希望 Codex 在旁边辅助解释、修改和 review。</p> <p>如果你使用 VS Code、Cursor 或 Windsurf，这通常是日常开发中最自然的入口。</p> <h2 id="shen-me-shi-hou-yong-web-cloud">什么时候用 Web / Cloud</h2> <p>适合把任务交给云端处理，例如：</p> <ul> <li>为一个 GitHub 仓库生成 PR。</li> <li>同时尝试多个修复方向。</li> <li>让 Codex 在你离开电脑时继续处理任务。</li> </ul> <p>云端工作更适合边界清晰、仓库已连接、任务描述明确的场景。</p> Codex 是什么 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/what-is-codex/ <p>Codex 是 OpenAI 面向软件开发的编码代理。它能理解你的项目文件、执行命令、修改代码、补测试、解释错误，也能在桌面 App、终端、编辑器或云端环境里协助完成开发任务。</p> <p>你可以把它理解成一个会使用开发工具的助手：你给出目标，它会先查看项目，再给出计划，必要时修改文件并运行验证命令。</p> <h2 id="ta-gua-he-zuo-shen-me">它适合做什么</h2> <p>Codex 适合处理这些任务：</p> <ul> <li>解释陌生项目的目录结构和启动方式。</li> <li>找出 bug 的可能原因并给出修复方案。</li> <li>修改代码、补充测试、更新文档。</li> <li>做代码审查，指出风险和遗漏。</li> <li>把一个较大的需求拆成多个可验证步骤。</li> <li>在云端或本地并行尝试不同方案。</li> </ul> <h2 id="ta-bu-gua-he-zuo-shen-me">它不适合做什么</h2> <p>Codex 不应该被当成不受限制的自动执行器。它能运行命令和写文件，所以你需要给它明确范围，并理解权限设置。</p> <p>不建议一上来就让 Codex 做这些事：</p> <ul> <li>在不理解项目的情况下大范围重构。</li> <li>直接操作生产数据库、生产服务器或重要凭据。</li> <li>在没有测试和回滚方案的情况下批量改文件。</li> <li>使用全权限模式处理你不熟悉的仓库。</li> </ul> <h2 id="pu-tong-yong-hu-ying-gai-xian-ji-zhu-shen-me">普通用户应该先记住什么</h2> <p>先记住三个概念就够了：</p> <ol> <li><strong>入口</strong>：CLI、App、IDE 扩展、Web/Cloud。</li> <li><strong>环境</strong>：Codex 在哪个系统和哪个目录里工作。</li> <li><strong>权限</strong>：Codex 能读写哪里，执行命令前是否需要确认。</li> </ol> <p>后面的章节会按这三个问题展开。</p> 常用工作流 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/workflows/ <h2 id="jie-shi-xiang-mu">解释项目</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请先不要改文件。阅读这个仓库，说明目录结构、主要模块、启动命令、测试命令和最重要的配置文件。</span></span></code></pre><h2 id="xiu-fu-bug">修复 bug</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>这个问题是：用户点击保存后页面没有提示成功。请先定位原因，不要直接改。找到原因后给出修复方案和验证方式。</span></span></code></pre> <p>确认后：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>按方案修改，只改必要文件。完成后运行相关测试，并总结 diff。</span></span></code></pre><h2 id="bu-ce-shi">补测试</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请为这个模块补充单元测试。优先覆盖边界条件，不改变生产逻辑。完成后运行测试。</span></span></code></pre><h2 id="dai-ma-shen-cha">代码审查</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请 review 当前未提交改动。优先指出 bug、回归风险、安全问题和缺失测试。不要改文件，先给我 findings。</span></span></code></pre><h2 id="wen-dang-geng-xin">文档更新</h2> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请根据当前实现更新 README。不要写营销文案，只补充安装、配置、运行和常见错误。</span></span></code></pre><h2 id="chang-ren-wu">长任务</h2> <p>长任务需要更明确：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>目标：把旧的支付回调处理迁移到新的 handler。</span></span> <span class="giallo-l"><span>范围：只改 api/handler/payment* 和相关测试。</span></span> <span class="giallo-l"><span>限制：不改数据库结构，不改外部接口字段。</span></span> <span class="giallo-l"><span>验证：运行 payment 相关测试，并说明没有覆盖的风险。</span></span></code></pre> <p>越明确，Codex 越容易给出可验证结果。</p> 接入 XAI Router 2026-07-08T00:00:00+00:00 2026-07-08T00:00:00+00:00 Unknown https://xaicontrol.com/codex/xai-router/ <h2 id="ji-chu-pei-zhi">基础配置</h2> <p>在 <code>~/.codex/config.toml</code> 中加入：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;gpt-5.3-codex&quot;</span></span> <span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;on-request&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;workspace-write&quot;</span></span> <span class="giallo-l"><span>preferred_auth_method =</span><span style="color: #9ECBFF;"> &quot;apikey&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">xai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"><span>env_key =</span><span style="color: #9ECBFF;"> &quot;XAI_API_KEY&quot;</span></span></code></pre> <p>设置 Key：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> XAI_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;sk-Xvs...&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>PowerShell：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="powershell"><span class="giallo-l"><span>$</span><span style="color: #79B8FF;">env:</span><span>XAI_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;sk-Xvs...&quot;</span></span> <span class="giallo-l"><span>codex</span></span></code></pre><h2 id="responses-yu-chat">responses 与 chat</h2> <p>Codex 原生模型优先使用：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span></code></pre> <p>如果你要接入 OpenAI Chat 形态的模型，可以使用独立 profile：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">xai-chat</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;xai-chat&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;chat&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"><span>env_key =</span><span style="color: #9ECBFF;"> &quot;XAI_API_KEY&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">profiles</span><span>.</span><span style="color: #B392F0;">minimax</span><span>]</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;MiniMax-M2.5&quot;</span></span> <span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;xai-chat&quot;</span></span></code></pre> <p>启动：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #79B8FF;"> --profile</span><span style="color: #9ECBFF;"> minimax</span></span></code></pre><h2 id="ji-xu-yue-du">继续阅读</h2> <ul> <li><a href="/docs/tools/codex/">Codex CLI / App（API Key 接入）</a></li> <li><a href="/blog/codex-cloud/">XAI Router Codex 包月服务：Codex / OpenClaw / OpenCode 接入</a></li> <li><a href="/blog/xai-router-codex-cache/">XAI Router 让你告别 Codex tokens 余量不足的焦虑</a></li> </ul> XAI 企业独立部署套餐：6000 元/月起，AI Coding、企业 API 与生图修图一次交付 2026-07-04T08:00:00+00:00 2026-07-04T08:00:00+00:00 Unknown https://xaicontrol.com/blog/xai-enterprise-codex-plan/ <figure class="content-image"> <img src="&#x2F;images&#x2F;xai-ui.png" alt="" decoding="async" loading="lazy" > </figure> <p>企业引入 AI，最怕的不是“买不到账号”，而是买完之后没人管、管不住、分不清、扩不动。</p> <p>研发团队要用 <code>Codex</code>，内部工具要用统一 AI API，运营和设计团队还需要生图、修图；管理员又希望知道谁在用、用了多少、能不能继续加人、能不能控制额度。靠几个零散账号和微信群发 Key，很快就会变成新的管理成本。</p> <p>所以我们把 XAI 企业服务重新整理成一个更直接的商业方案：</p> <div class="infobox"> XAI 企业独立部署套餐： <br>• `6000 元/月`：交付一套独立 XAI 系统，包含 `2 个 20x Pro` 资源，支持企业自主管理、继续加号扩容、全球主流 LLM 接入与内部 API 资源分发 <br>• 同时交付一套独立 `XABCIMG` 系统，与 XAI 搭配，满足企业内部生图 / 修图需求 <br>• `10000 元/月`：在基础套餐上增加技术完全托管，由我们负责日常技术配置、账户接入、资源治理与问题处理 <br>• 每家企业客户独立部署 XAI + XABCIMG 双系统，不与其他企业混用同一套业务系统 </div> <p>一句话：<strong>企业买到的不是几个账号，而是一套可以自己管理、可以继续扩容、可以长期沉淀的企业 AI 资源系统。</strong></p> <p>如果你希望先了解产品细节和实际使用方式，欢迎先注册体验：<a rel="external" href="https://m.xairouter.com">m.xairouter.com</a>。通过管理端，你可以更直观地了解 XAI 的账户体系、资源分发、用量统计和服务形态。</p> <hr /> <h2 id="liang-chong-tao-can-bian-jie-qing-chu">两种套餐，边界清楚</h2> <p>我们把企业交付分成两个版本，方便企业按自己的管理能力选择。</p> <table><thead><tr><th>套餐</th><th style="text-align: right">价格</th><th>适合客户</th><th>我们交付什么</th><th>企业负责什么</th></tr></thead><tbody> <tr><td>XAI 企业基础套餐</td><td style="text-align: right"><code>6000 元/月</code></td><td>有技术管理员，希望自己日常管理</td><td>独立 XAI 系统、独立 XABCIMG 系统、2 个 20x Pro 资源、Codex 接入、全球主流 LLM API 分发、管理员账号、基础配置与交付说明</td><td>自行添加成员、分配子账户、日常管理额度与使用规范</td></tr> <tr><td>XAI 技术完全托管套餐</td><td style="text-align: right"><code>10000 元/月</code></td><td>希望少操心，由我们持续代管技术侧</td><td>基础套餐全部内容 + 技术托管服务</td><td>只需提出成员、权限、扩容和使用需求</td></tr> </tbody></table> <p>基础套餐的核心是“系统交付 + AI 资源交付”。我们把一套独立 XAI 环境搭好，把初始 <code>20x Pro</code> 资源接入进去，同时交付独立的 XABCIMG 图片系统，再把管理员权限交给企业。</p> <p>之后，企业可以自己做这些事情：</p> <ul> <li>给研发、产品、运营、数据团队创建子账户</li> <li>给不同团队分配不同模型权限和使用额度</li> <li>把 <code>Codex CLI / App</code>、Claude Code、OpenAI 兼容 API 等工具统一接到 XAI</li> <li>把几乎所有全球主流 LLM 纳入统一入口，按部门、项目和员工分发 API 资源</li> <li>通过 XABCIMG 满足企业内部作图、修图、设计辅助和内容生产需求</li> <li>查看成员用量和资源消耗</li> <li>按团队增长继续加号扩容</li> </ul> <p>如果企业希望我们把技术侧全部接过去，就选择 <code>10000 元/月</code> 的完全托管套餐。你们只需要告诉我们“哪些人要用、要给多少额度、哪些工具要接入”，剩下的配置、调整、巡检和问题处理由我们负责。</p> <h2 id="wei-shen-me-qi-ye-bu-gua-he-zhi-mai-ji-ge-zhang-hao">为什么企业不适合只买几个账号</h2> <p>单独买账号适合个人试用，但不适合组织长期使用。</p> <p>一旦进入企业场景，问题会迅速出现：</p> <ul> <li>员工各自保存账号和 Key，离职交接困难</li> <li>不同团队用不同配置，出了问题难定位</li> <li>老板只看到总成本，看不到部门和个人用量</li> <li>研发工具、内部脚本、业务系统和图片工具缺少统一入口</li> <li>企业已经采购或计划采购的全球主流 LLM 资源无法统一分发</li> <li>想增加员工时，又要重新整理账号、权限和配置</li> </ul> <p>XAI 的做法是把这些能力统一收口。</p> <p>企业内部不再直接围绕单个账号组织使用，而是围绕一套自己的 XAI 系统来组织 AI 能力：主账户负责资源池，子账户分发给团队和员工，Codex、全球主流 LLM API 与业务系统请求通过统一入口转发、统计和治理。图片生成与图片编辑，则通过配套的 XABCIMG 独立系统承接。</p> <p>这也是我们一直强调的：<strong>企业需要的不是“账号共享”，而是“能力分发”。</strong></p> <h2 id="mei-jia-qi-ye-yi-tao-du-li-xai-xabcimg">每家企业一套独立 XAI + XABCIMG</h2> <p>这次套餐最重要的变化，是每家企业客户都独立部署一套 XAI，同时配套一套独立 XABCIMG。</p> <p>这意味着：</p> <ul> <li>你的企业有自己的 XAI 管理入口</li> <li>你的成员、子账户、用量统计、配置策略独立存在</li> <li>你的 Codex 资源、全球主流 LLM 资源和后续加配资源独立纳管</li> <li>你的 XABCIMG 图片系统独立部署，可单独服务企业内部生图 / 修图场景</li> <li>你可以根据自己的组织结构来分配权限和额度</li> <li>后续如果要升级为更深度的私有化部署，也有连续演进路径</li> </ul> <p>对管理层来说，这解决的是控制权问题。</p> <p>对技术负责人来说，这解决的是落地问题。</p> <p>对一线员工来说，这解决的是可用性问题：大家不需要反复问“今天用哪个账号”“Key 在哪里”“这个工具怎么配”，企业只需要给成员发放 XAI 的接入方式即可。</p> <h2 id="6000-yuan-yue-ji-chu-tao-can-bao-han-shen-me">6000 元/月基础套餐包含什么</h2> <p><code>6000 元/月</code> 的基础套餐适合有基本技术管理能力的企业。</p> <p>我们负责把系统搭好、资源接好、入口交付清楚；企业自己负责后续成员管理和日常运营。</p> <p>基础交付内容包括：</p> <ul> <li><strong>一套独立 XAI 系统</strong>：每家企业独立部署，配置和数据边界清晰</li> <li><strong>一套独立 XABCIMG 系统</strong>：与 XAI 搭配，满足企业内部生图 / 修图需求</li> <li><strong>2 个 20x Pro 资源</strong>：作为初始 Codex 能力供给，可按企业规模继续加号</li> <li><strong>Codex 接入能力</strong>：支持研发团队通过统一入口使用 Codex</li> <li><strong>全球主流 LLM 接入能力</strong>：支持将 OpenAI、Claude、Gemini、DeepSeek、Qwen、Kimi、MiniMax、智谱，以及火山方舟、阿里云、百度千帆、腾讯云等国内外主流模型资源纳入统一管理</li> <li><strong>主/子账户体系</strong>：企业管理员可以继续向下创建团队和员工账号</li> <li><strong>模型与额度治理</strong>：可控制成员能用什么模型、每天能用多少、哪些资源只能给特定团队使用</li> <li><strong>统一 API 入口</strong>：内部工具、脚本、Agent 或业务系统可以逐步接入，企业可以把 AI API 像云资源一样分配给员工和项目</li> <li><strong>用量统计</strong>：帮助管理者看清成员、团队和模型维度的使用情况</li> </ul> <p>这个版本适合这样的企业：你们有自己的 IT、研发负责人或技术管理员，希望系统由自己掌握，日常加人、减人、分配额度都在内部完成。</p> <h2 id="bu-zhi-shi-ai-coding-ye-shi-yi-tao-qi-ye-ai-api-zi-yuan-chi">不只是 AI Coding，也是一套企业 AI API 资源池</h2> <p><code>Codex</code> 是企业最容易落地、最容易看到效率提升的入口，但 XAI 的边界不止 AI Coding。</p> <p>企业可以把几乎所有全球主流 LLM 资源接入 XAI，再通过主/子账户体系发给员工、团队、项目和内部系统：</p> <ul> <li>研发团队使用 Codex、Claude Code、OpenAI 兼容工具</li> <li>运营团队使用文本生成、摘要、改写、分类、分析能力</li> <li>客服和销售系统通过统一 API 接入模型能力</li> <li>数据分析、知识库、Agent 和自动化脚本走统一认证与统计</li> <li>不同团队使用不同模型、不同额度、不同速率限制</li> </ul> <p>这样一来，企业内部的 AI API 不再是散落在个人电脑和脚本里的 Key，而是一套可分配、可审计、可扩容的资源池。</p> <h2 id="pei-tao-xabcimg-bu-qi-qi-ye-sheng-tu-he-xiu-tu-xu-qiu">配套 XABCIMG，补齐企业生图和修图需求</h2> <p>除了文本、代码和 API 调用，企业内部还会有大量图片需求：产品配图、营销素材、活动海报、社媒内容、内部知识库插图、原图修复和局部修改。</p> <p>因此，基础套餐会同时配套交付一套独立 <code>XABCIMG</code> 系统，与 XAI 搭配使用。</p> <p>XABCIMG 的定位很清楚：它是独立图片服务，不依赖 XAI 的用户系统，也不依赖 Cloudflare。企业可以把它作为内部图片工作台使用：</p> <ul> <li>支持作图 / 修图两个核心入口</li> <li>支持上传原图和蒙版进行图片编辑</li> <li>图片请求由服务端统一调用上游，员工不接触上游图片模型 Key</li> <li>使用图点方式计费和分配，便于企业内部控制图片资源消耗</li> <li>生成和修图任务在后台执行，页面切换不影响任务继续处理</li> <li>请求失败会返还预扣图点，管理员可以维护套餐、图点额度和用户资源</li> </ul> <p>这让企业不只解决“研发怎么用 AI”，也能解决“内容、设计、运营怎么用 AI 图片能力”。</p> <h2 id="10000-yuan-yue-wan-quan-tuo-guan-gua-he-shen-me-qing-kuang">10000 元/月完全托管适合什么情况</h2> <p>如果企业不想把时间花在技术配置、账号接入、模型映射和日常问题处理上，可以选择完全托管。</p> <p>完全托管是在基础套餐上增加 <code>4000 元/月</code>，总计 <code>10000 元/月</code>。</p> <p>托管服务主要包括：</p> <ul> <li>初始部署和后续版本维护</li> <li>Codex 资源接入、加号和配置调整</li> <li>全球主流 LLM Provider 接入、模型映射和 API 资源分配</li> <li>XABCIMG 图片系统部署、上游图片模型接入和图点策略配置</li> <li>员工或团队子账户创建协助</li> <li>额度策略、速率限制和团队使用边界配置</li> <li>日常使用问题定位</li> <li>用量异常和资源消耗巡检</li> <li>根据企业反馈持续优化使用结构</li> </ul> <p>这个版本适合两类客户：</p> <p>一类是老板和管理层已经确定要把 AI Coding 推进下去，但不希望内部团队被配置细节拖住。</p> <p>另一类是企业有研发团队，但希望把 XAI 作为外部技术基础设施来采购，由我们持续维护底层能力，企业只关注使用效果和团队产出。</p> <h2 id="zhe-tao-fang-an-neng-gei-qi-ye-dai-lai-shen-me">这套方案能给企业带来什么</h2> <h3 id="1-geng-kuai-luo-di-codex-he-ai-coding">1. 更快落地 Codex 和 AI Coding</h3> <p>企业不需要从零研究账号、接口、客户端配置和分发方式。我们直接交付一套可运行的 XAI 系统，把 Codex 能力纳入企业统一入口。</p> <p>研发团队拿到企业分配的接入方式后，就可以围绕现有工作流开始使用。</p> <h3 id="2-qi-ye-api-zi-yuan-neng-fa-dao-yuan-gong-he-xi-tong-shou-li">2. 企业 API 资源能发到员工和系统手里</h3> <p>XAI 支持几乎所有全球主流 LLM，不只是给研发团队开通 Codex，也可以把企业内部 AI API 资源正式分发给员工、项目和业务系统。</p> <p>这意味着企业可以把不同上游、不同模型、不同额度都收口到同一套治理体系里，不再让 Key 分散在个人、脚本和部门工具中。</p> <h3 id="3-sheng-tu-xiu-tu-you-du-li-xi-tong-cheng-jie">3. 生图 / 修图有独立系统承接</h3> <p>配套交付的 XABCIMG 可以作为企业内部图片工作台，满足营销、运营、产品、设计和内容团队的日常生图 / 修图需求。</p> <p>文本、代码、API 走 XAI；图片生成和图片编辑走 XABCIMG。两套系统独立部署，能力边界清楚，但采购和交付可以放在同一套企业方案里完成。</p> <h3 id="4-guan-li-yuan-neng-zhen-zheng-guan-qi-lai">4. 管理员能真正管起来</h3> <p>企业管理员不再面对一堆分散账号，而是通过 XAI 管理主账户：</p> <ul> <li>谁能用</li> <li>能用什么</li> <li>每天多少额度</li> <li>哪些团队消耗最多</li> <li>后续要不要继续加号扩容</li> </ul> <p>这些问题都可以在同一套系统里处理。</p> <h3 id="5-cheng-ben-jie-gou-geng-qing-chu">5. 成本结构更清楚</h3> <p>基础套餐和托管套餐都按月明确报价。</p> <p>企业可以先从 <code>6000 元/月</code> 起步，如果内部自己能管，就保持轻量交付；如果希望我们完全托管，再升级到 <code>10000 元/月</code>。后续加号扩容也围绕实际团队规模和使用强度来确认。</p> <p>这比零散采购、临时补账号、人工协调权限更容易做预算。</p> <h3 id="6-wei-lai-ke-yi-ji-xu-kuo-zhan">6. 未来可以继续扩展</h3> <p>XAI 不只服务 Codex，XABCIMG 也不只是一个演示页面。</p> <p>随着企业使用深入，后续还可以把更多国内外模型资源、OpenAI 兼容 API、Claude 兼容入口、内部 Agent、业务系统调用接到同一套 XAI 里；图片侧也可以根据企业需求继续调整上游、图点规则和使用边界。</p> <p>今天先解决 AI Coding 和图片生产，明天可以继续解决统一 API、团队治理、成本归因和业务系统接入。</p> <h2 id="tui-jian-luo-di-fang-shi">推荐落地方式</h2> <p>对大多数企业，我们建议这样开始：</p> <ol> <li>先确认核心使用团队，比如研发组、技术支持组或 AI 项目组</li> <li>选择基础套餐或完全托管套餐</li> <li>我们独立部署 XAI 和 XABCIMG，并接入初始 2 个 20x Pro 资源</li> <li>企业管理员拿到主账户，创建团队和员工子账户</li> <li>核心成员先跑通 Codex、统一 API 和生图 / 修图流程</li> <li>根据真实用量决定是否加号、接入更多 LLM、扩容图片资源或转为完全托管</li> </ol> <p>这条路径的好处是：<strong>先让团队用起来，再根据真实使用强度扩容。</strong></p> <p>企业不需要一开始就设计很复杂的 AI 战略，也不需要一次性投入很重的私有化项目。先交付系统，先让核心团队获得稳定的 AI Coding、统一 API 和图片生产能力，再把治理和扩展逐步补上。</p> <h2 id="gua-he-na-xie-qi-ye">适合哪些企业</h2> <p>如果你们符合下面任意一种情况，这套套餐通常就值得评估：</p> <ul> <li>希望给研发团队正式开通 Codex，而不是让员工各自想办法</li> <li>已经有多人使用 AI Coding，但账号和配置比较混乱</li> <li>希望把 OpenAI、Claude、Gemini、DeepSeek、Qwen、Kimi 等全球主流 LLM 统一纳入企业入口</li> <li>希望把 AI 能力按部门、团队、项目分发</li> <li>希望把企业内部 AI API 资源发给员工和业务系统，同时保留额度、权限和统计</li> <li>希望给运营、设计、产品、市场团队提供内部生图 / 修图入口</li> <li>希望有一套自己的企业管理入口，而不是只拿几个账号</li> <li>想控制成本、查看用量、规划后续扩容</li> <li>想先轻量落地，未来再逐步升级私有化或更完整的 AI 基础设施</li> </ul> <p>我们尤其建议 10 人以上的研发团队尽早用系统化方式管理 AI Coding。人数越多，零散账号模式带来的管理成本越明显。</p> <h2 id="chang-jian-wen-ti">常见问题</h2> <h3 id="6000-yuan-yue-shi-bu-shi-zhi-mai-zhang-hao">6000 元/月是不是只买账号？</h3> <p>不是。<code>6000 元/月</code> 交付的是一套独立 XAI 系统 + 独立 XABCIMG 系统 + 初始 2 个 20x Pro 资源 + Codex 接入能力 + 企业 AI API 资源分发治理能力。账号只是资源供给的一部分，真正的价值是企业获得自己的管理入口和分发体系。</p> <h3 id="qi-ye-neng-bu-neng-zi-ji-tian-jia-yuan-gong">企业能不能自己添加员工？</h3> <p>可以。基础套餐就是为企业自主管理设计的。我们完成系统和初始资源交付后，企业管理员可以自行创建子账户、分配额度、调整成员使用方式。</p> <h3 id="ru-guo-qi-ye-bu-hui-pei-zhi-zen-me-ban">如果企业不会配置怎么办？</h3> <p>可以选择 <code>10000 元/月</code> 的技术完全托管套餐。我们负责技术侧的部署、配置、接入、维护和日常问题处理。</p> <h3 id="2-ge-20x-pro-bu-gou-zen-me-ban">2 个 20x Pro 不够怎么办？</h3> <p>可以继续加号扩容。具体扩容方式会根据企业人数、并发强度和实际使用量确认。</p> <h3 id="hou-xu-neng-bu-neng-jie-geng-duo-mo-xing-huo-ye-wu-xi-tong">后续能不能接更多模型或业务系统？</h3> <p>可以。XAI Router 本身就是面向多模型、多账户、多团队、多入口治理设计的系统。企业可以先从 Codex 开始，后续再逐步接入统一 AI API、内部系统和更多模型资源。</p> <h3 id="xabcimg-shi-shen-me-he-xai-shi-yi-tao-xi-tong-ma">XABCIMG 是什么，和 XAI 是一套系统吗？</h3> <p>XABCIMG 是配套交付的独立图片服务，用来满足企业内部作图 / 修图需求。它和 XAI 是两套独立部署的系统：XAI 负责 LLM、Codex、企业 API 和账户治理；XABCIMG 负责图片生成、图片编辑、图点扣减和图片任务管理。</p> <h3 id="xiang-xian-liao-jie-xi-jie-ke-yi-cong-na-li-kai-shi">想先了解细节，可以从哪里开始？</h3> <p>可以先注册体验 <a rel="external" href="https://m.xairouter.com">m.xairouter.com</a>。如果你还在评估是否适合企业团队使用，建议先从管理端了解账户、额度、API 资源和用量统计，再决定是否进入企业独立部署套餐。</p> <h2 id="jie-yu">结语</h2> <p>企业真正需要的不是“再买几个 AI 账号”，而是把 AI Coding、企业 API 资源和图片生产能力变成一套可以交付、可以分发、可以管理、可以扩容的组织能力。</p> <p>XAI 企业独立部署套餐把这件事变得很直接：</p> <ul> <li>想自己管理，选择 <code>6000 元/月</code> 基础套餐</li> <li>想省心托管，选择 <code>10000 元/月</code> 完全托管套餐</li> <li>需要更多资源，继续加号扩容</li> <li>需要更多模型，把全球主流 LLM 逐步纳入统一入口</li> <li>需要图片能力，使用配套 XABCIMG 承接企业内部生图 / 修图</li> <li>需要更深控制，后续升级私有化和统一 AI 基础设施</li> </ul> <p>如果你希望企业团队尽快、稳定、可控地用上 Codex、全球主流 LLM API 和企业内部生图 / 修图能力，这会是比零散账号更清晰的起点。</p> <p>想进一步了解服务细节，欢迎先注册体验：<a rel="external" href="https://m.xairouter.com">m.xairouter.com</a>。</p> <h2 id="yan-shen-yue-du">延伸阅读</h2> <ul> <li><a href="/blog/enterprise-xai-router/">企业 AI Coding 服务：Codex 分发、多模型接入、子账户治理与私有化部署</a></li> <li><a href="/blog/xai-router-architecture/">认识 XAI Router</a></li> <li><a href="/blog/codex-cloud/">XAI Router Codex 包月服务：Codex / OpenClaw / OpenCode 接入</a></li> <li><a href="/docs/products/xai-router/">XAI Router 私有化</a></li> </ul> CC Switch 配置 XAI / YAI / ZAI Router 指南（Codex） 2026-06-16T02:25:00+00:00 2026-06-16T02:25:00+00:00 Unknown https://xaicontrol.com/blog/ccswitch-xairouter-guide/ <figure class="content-image"> <img src="&#x2F;images&#x2F;ccs.png" alt="" decoding="async" loading="lazy" > </figure> <p>本文用于指导 Windows 和 macOS 用户通过 CC Switch 配置 Codex，使 Codex 使用 XAI Router、YAI Router 或 ZAI Router 的统一模型入口。</p> <h2 id="xian-shuo-ming-you-xian-tui-jian-zhi-jie-pei-zhi-codex">先说明：优先推荐直接配置 Codex</h2> <p>一般情况下，我们不推荐通过第三方客户端或第三方配置工具间接连接 Router。多一层工具可能带来版本差异、配置覆盖、状态同步和排障成本，在部分场景下也可能影响连接速度与整体体验。</p> <p>Codex CLI / App 的优先接入方式，仍然是直接配置 Codex 官方配置文件，例如 <code>~/.codex/config.toml</code> 或 <code>%USERPROFILE%\.codex\config.toml</code>，并让 Codex 直接连接 Router 的原生 Responses 路径。</p> <p>不过，考虑到很多用户已经习惯使用 CC Switch 这类工具统一管理客户端配置，本文给出对应设置方法。使用前请重点确认三件事：</p> <ol> <li>当前启用的 Provider ID 是否正确。</li> <li>Base URL 是否属于你实际使用的站点。</li> <li>API Key 是否来自同一个站点，不要跨站混用。</li> </ol> <h2 id="san-ge-zhan-dian-de-pei-zhi-qu-bie">三个站点的配置区别</h2> <p>XAI Router、YAI Router、ZAI Router 的配置方法相同，但账号、API Key、额度和 Base URL 不互通。配置时不要只改名字，必须同时核对 Base URL 与 API Key 来源。</p> <table><thead><tr><th>使用服务</th><th>Base URL</th><th>CC Switch / Codex Provider ID 建议</th><th>API Key 来源</th></tr></thead><tbody> <tr><td>XAI Router</td><td><code>https://api.xairouter.com</code></td><td><code>xai</code></td><td>XAI Router 控制台生成的 Key</td></tr> <tr><td>YAI Router</td><td><code>https://api.yairouter.com</code></td><td><code>yai</code></td><td>YAI Router 控制台生成的 Key</td></tr> <tr><td>ZAI Router</td><td><code>https://api.zairouter.com</code></td><td><code>zai</code></td><td>ZAI Router 控制台生成的 Key</td></tr> </tbody></table> <p>说明：</p> <ol> <li>XAI Router 的 Key 只配 <code>https://api.xairouter.com</code>。</li> <li>YAI Router 的 Key 只配 <code>https://api.yairouter.com</code>。</li> <li>ZAI Router 的 Key 只配 <code>https://api.zairouter.com</code>。</li> <li>Provider ID 是本地配置里的名字，可以自定义；本文为了排查方便，统一使用 <code>xai</code>、<code>yai</code>、<code>zai</code>。</li> <li>API endpoint 直接在浏览器打开可能返回 <code>401</code>，这是未携带鉴权信息时的正常表现。</li> </ol> <h2 id="pei-zhi-mu-biao">配置目标</h2> <p>目标是让 Codex 使用 Router 的 Responses 兼容路径。以 XAI Router 为例：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span></span> <span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;never&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;danger-full-access&quot;</span></span> <span class="giallo-l"><span>network_access =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>preferred_auth_method =</span><span style="color: #9ECBFF;"> &quot;apikey&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">xai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span></code></pre> <p>如果你使用 YAI Router，只需要把 Provider ID 和 Base URL 换成：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;yai&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">yai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;yai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.yairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span></code></pre> <p>如果你使用 ZAI Router，则换成：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;zai&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">zai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;zai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.zairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span></code></pre> <p>CC Switch 通常会把 API Key 写入 Codex 的认证文件，例如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;OPENAI_API_KEY&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;sk-xxxx&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>请不要把真实 API Key 写入公开文档、Git 仓库、截图或聊天群。如果 API Key 已经暴露，建议立即到对应 Router 后台撤销并重新生成。</p> <h2 id="qian-zhi-zhun-bei">前置准备</h2> <p>在开始配置前，请确认已经准备好：</p> <ol> <li>已安装 Codex CLI 或 Codex App。</li> <li>已安装 CC Switch。</li> <li>已拥有 XAI Router、YAI Router 或 ZAI Router 的 API Key。</li> <li>已确认当前账号可用的模型 ID，例如 <code>gpt-5.5</code>。</li> </ol> <p>如果 <code>gpt-5.5</code> 在你的账号中不可用，请将配置中的模型名替换为控制台实际支持的模型。</p> <h2 id="windows-an-zhuang-cc-switch">Windows 安装 CC Switch</h2> <h3 id="xia-zai-an-zhuang-bao">下载安装包</h3> <p>打开 CC Switch Releases 页面：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://github.com/farion1231/cc-switch/releases</span></span></code></pre> <p>下载 Windows 安装包：</p> <ul> <li>推荐安装包：<code>CC-Switch-v{version}-Windows.msi</code></li> <li>免安装版本：<code>Windows-Portable.zip</code></li> </ul> <h3 id="an-zhuang-bing-qi-dong">安装并启动</h3> <ol> <li>双击 <code>.msi</code> 安装包并完成安装。</li> <li>打开 CC Switch。</li> <li>在应用列表中选择 <code>Codex</code>。</li> </ol> <p>如果使用免安装版本，请解压 <code>Windows-Portable.zip</code> 后直接运行 CC Switch 程序。</p> <h2 id="macos-an-zhuang-cc-switch">macOS 安装 CC Switch</h2> <h3 id="shi-yong-homebrew-an-zhuang">使用 Homebrew 安装</h3> <p>推荐使用 Homebrew 安装：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">brew</span><span style="color: #9ECBFF;"> install</span><span style="color: #79B8FF;"> --cask</span><span style="color: #9ECBFF;"> cc-switch</span></span></code></pre> <p>升级 CC Switch：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">brew</span><span style="color: #9ECBFF;"> upgrade</span><span style="color: #79B8FF;"> --cask</span><span style="color: #9ECBFF;"> cc-switch</span></span></code></pre><h3 id="shi-yong-dmg-an-zhuang">使用 DMG 安装</h3> <p>也可以从 Releases 页面下载 macOS 安装包：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://github.com/farion1231/cc-switch/releases</span></span></code></pre> <p>下载 <code>.dmg</code> 文件后，按 macOS 常规方式拖入 Applications 目录即可。</p> <h2 id="zai-cc-switch-zhong-tian-jia-router-gong-ying-shang">在 CC Switch 中添加 Router 供应商</h2> <ol> <li>打开 CC Switch。</li> <li>切换到 <code>Codex</code> 面板。</li> <li>点击右上角 <code>+</code> 添加供应商。</li> <li>选择 <code>应用专属供应商</code>。</li> <li>如果预设中存在对应 Router，可直接选择预设。</li> <li>如果没有预设，选择 <code>自定义</code>。</li> </ol> <p>按你实际使用的站点填写：</p> <table><thead><tr><th>配置项</th><th>XAI Router</th><th>YAI Router</th><th>ZAI Router</th></tr></thead><tbody> <tr><td>名称</td><td><code>xai</code></td><td><code>yai</code></td><td><code>zai</code></td></tr> <tr><td>Provider ID</td><td><code>xai</code></td><td><code>yai</code></td><td><code>zai</code></td></tr> <tr><td>Base URL</td><td><code>https://api.xairouter.com</code></td><td><code>https://api.yairouter.com</code></td><td><code>https://api.zairouter.com</code></td></tr> <tr><td>API Key</td><td>XAI Router Key</td><td>YAI Router Key</td><td>ZAI Router Key</td></tr> <tr><td>Model</td><td>例如 <code>gpt-5.5</code></td><td>例如 <code>gpt-5.5</code></td><td>例如 <code>gpt-5.5</code></td></tr> <tr><td>Wire API</td><td><code>responses</code></td><td><code>responses</code></td><td><code>responses</code></td></tr> </tbody></table> <p>填写完成后保存。保存前再核对一次：<strong>Base URL 和 API Key 必须属于同一个站点</strong>。</p> <h2 id="sheng-cheng-de-codex-pei-zhi-wen-jian">生成的 Codex 配置文件</h2> <p>CC Switch 启用供应商后，通常会写入 Codex 的配置目录。</p> <h3 id="windows-pei-zhi-lu-jing">Windows 配置路径</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>%USERPROFILE%\.codex\config.toml</span></span> <span class="giallo-l"><span>%USERPROFILE%\.codex\auth.json</span></span></code></pre> <p>可在资源管理器地址栏输入以下路径打开：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>%USERPROFILE%\.codex</span></span></code></pre><h3 id="macos-pei-zhi-lu-jing">macOS 配置路径</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>~/.codex/config.toml</span></span> <span class="giallo-l"><span>~/.codex/auth.json</span></span></code></pre> <p>可在终端中运行以下命令打开：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">open</span><span style="color: #9ECBFF;"> ~/.codex</span></span></code></pre><h3 id="xai-router-config-toml-shi-li">XAI Router config.toml 示例</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span></span> <span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;never&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;danger-full-access&quot;</span></span> <span class="giallo-l"><span>network_access =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>preferred_auth_method =</span><span style="color: #9ECBFF;"> &quot;apikey&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">xai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span></code></pre><h3 id="yai-router-config-toml-shi-li">YAI Router config.toml 示例</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;yai&quot;</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span></span> <span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;never&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;danger-full-access&quot;</span></span> <span class="giallo-l"><span>network_access =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>preferred_auth_method =</span><span style="color: #9ECBFF;"> &quot;apikey&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">yai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;yai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.yairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span></code></pre><h3 id="zai-router-config-toml-shi-li">ZAI Router config.toml 示例</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;zai&quot;</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span></span> <span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;never&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;danger-full-access&quot;</span></span> <span class="giallo-l"><span>network_access =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>preferred_auth_method =</span><span style="color: #9ECBFF;"> &quot;apikey&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">zai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;zai&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.zairouter.com&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span></code></pre><h3 id="auth-json-shi-li">auth.json 示例</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;OPENAI_API_KEY&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;sk-xxxx&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>请将 <code>sk-xxxx</code> 替换为对应站点生成的真实 API Key。不要用 XAI Router 的 Key 调 YAI Router 或 ZAI Router 的 Base URL。</p> <h2 id="qi-yong-router-gong-ying-shang">启用 Router 供应商</h2> <ol> <li>回到 CC Switch 的 Codex 供应商列表。</li> <li>找到你刚刚创建的供应商，例如 <code>xai</code>、<code>yai</code> 或 <code>zai</code>。</li> <li>点击 <code>Enable</code> 或 <code>启用</code>。</li> <li>关闭当前 Codex 终端。</li> <li>重新打开终端或重启 Codex App。</li> <li>再次启动 Codex。</li> </ol> <p>多数情况下，切换供应商后需要重启终端或 Codex App 才会生效。</p> <h2 id="yan-zheng-pei-zhi-shi-fou-sheng-xiao">验证配置是否生效</h2> <h3 id="jian-cha-codex-shi-fou-ke-qi-dong">检查 Codex 是否可启动</h3> <p>在终端运行：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #79B8FF;"> --version</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre><h3 id="fa-song-ce-shi-qing-qiu">发送测试请求</h3> <p>进入 Codex 后输入：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请用一句话回复：当前模型连接是否正常？</span></span></code></pre> <p>如果模型正常返回内容，说明 Router 配置已经生效。</p> <p>也可以尝试输入：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/model</span></span></code></pre> <p>查看当前模型信息。</p> <h2 id="chang-jian-wen-ti-pai-cha">常见问题排查</h2> <h3 id="401-huo-403-ren-zheng-shi-bai">401 或 403 认证失败</h3> <p>可能原因：</p> <ul> <li>API Key 错误。</li> <li>API Key 已过期或已撤销。</li> <li>复制 API Key 时多了空格。</li> <li>API Key 和 Base URL 不是同一个站点。</li> <li>Router 账户余额不足或权限不足。</li> </ul> <p>处理方式：</p> <ol> <li>到对应 Router 后台重新复制 API Key。</li> <li>确认 <code>config.toml</code> 中的 <code>base_url</code> 属于同一个站点。</li> <li>检查 <code>auth.json</code> 中是否为：</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;OPENAI_API_KEY&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;sk-xxxx&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="4"> <li>保存后重启终端或 Codex App。</li> </ol> <h3 id="mo-xing-bu-cun-zai-huo-mo-xing-bu-ke-yong">模型不存在或模型不可用</h3> <p>可能原因：</p> <ul> <li><code>gpt-5.5</code> 不是当前账号可用模型。</li> <li>模型名称填写错误。</li> <li>当前 Router 后台暂未开放该模型。</li> </ul> <p>处理方式：</p> <ol> <li>登录对应 Router 控制台。</li> <li>查看当前可用模型 ID。</li> <li>将 <code>config.toml</code> 中的模型名改为实际可用模型。</li> </ol> <p>示例：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;实际可用模型名&quot;</span></span></code></pre><h3 id="pei-zhi-xiu-gai-hou-mei-you-sheng-xiao">配置修改后没有生效</h3> <p>处理方式：</p> <ol> <li>在 CC Switch 中重新点击 <code>Enable</code>。</li> <li>关闭当前终端。</li> <li>重新打开终端。</li> <li>重新启动 Codex。</li> </ol> <p>如果仍不生效，直接打开 <code>.codex/config.toml</code> 和 <code>.codex/auth.json</code> 检查文件内容，确认没有被其他工具覆盖。</p> <h3 id="windows-zhao-bu-dao-pei-zhi-mu-lu">Windows 找不到配置目录</h3> <p>在资源管理器地址栏输入：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>%USERPROFILE%\.codex</span></span></code></pre> <p>如果目录不存在，可以先启动一次 Codex，或让 CC Switch 启用一次 Codex 供应商后再检查。</p> <h3 id="macos-zhao-bu-dao-pei-zhi-mu-lu">macOS 找不到配置目录</h3> <p>在终端中运行：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ls</span><span style="color: #79B8FF;"> -la</span><span style="color: #9ECBFF;"> ~/.codex</span></span> <span class="giallo-l"><span style="color: #B392F0;">open</span><span style="color: #9ECBFF;"> ~/.codex</span></span></code></pre> <p>如果目录不存在，可以先启动一次 Codex，或让 CC Switch 启用一次 Codex 供应商后再检查。</p> <h2 id="xiang-guan-lian-jie">相关链接</h2> <ul> <li>Codex CLI / App 直接配置指南：<a href="/docs/tools/codex/">/docs/tools/codex/</a></li> <li>CC Switch Releases：<a rel="external" href="https://github.com/farion1231/cc-switch/releases">https://github.com/farion1231/cc-switch/releases</a></li> </ul> LightVela 接入 XAI / YAI / ZAI Router 指南 2026-06-16T01:01:00+00:00 2026-06-16T01:01:00+00:00 Unknown https://xaicontrol.com/blog/lightvela-xairouter-integration/ <figure class="content-image"> <img src="&#x2F;images&#x2F;lightvela.png" alt="" decoding="async" loading="lazy" > </figure> <p>本文介绍如何在 LightVela 中通过 Router API 接入 XAI Router、YAI Router 或 ZAI Router，让 LightVela 的云端智能体使用统一模型入口。</p> <h2 id="gua-yong-chang-jing">适用场景</h2> <p>如果你希望在 LightVela 中统一使用 OpenAI、Claude、Gemini、DeepSeek、Grok 等模型，可以把 XAI Router、YAI Router 或 ZAI Router 作为 LightVela 的自定义模型服务商来配置。配置完成后，LightVela 只需要保存一个 Router API Key 和一个模型入口，后续模型请求由对应 Router 路由到目标模型。</p> <p>XAI Router 官方文档说明其提供统一 Base URL：<code>https://api.xairouter.com</code>，并支持 OpenAI、Claude、Gemini 等兼容协议。YAI Router 的接入点为 <code>https://api.yairouter.com</code>，ZAI Router 的接入点为 <code>https://api.zairouter.com</code>。LightVela 的模型配置页支持自定义 <code>Provider</code>、<code>Base URL</code>、<code>兼容协议</code>、<code>API Key</code> 和模型信息，因此可以直接接入。</p> <h2 id="xuan-ze-jie-ru-dian">选择接入点</h2> <p>请根据你实际使用的账号和 API Key 选择对应接入点。不要混用不同站点的 API Key 和 Base URL。</p> <table><thead><tr><th>使用的服务</th><th>Base URL</th><th>Provider 建议填写</th></tr></thead><tbody> <tr><td>XAI Router</td><td><code>https://api.xairouter.com</code></td><td><code>xairouter</code></td></tr> <tr><td>YAI Router</td><td><code>https://api.yairouter.com</code></td><td><code>yairouter</code></td></tr> <tr><td>ZAI Router</td><td><code>https://api.zairouter.com</code></td><td><code>zairouter</code></td></tr> </tbody></table> <p>说明：<code>https://api.xairouter.com</code> 已兼容 Base URL 带 <code>/v1</code> 或不带 <code>/v1</code> 的写法。为了减少配置差异，本文统一使用不带 <code>/v1</code> 的 Base URL。若你的后台、客服或团队配置给出了特定地址，请以实际接入点为准。</p> <h2 id="zhun-bei-gong-zuo">准备工作</h2> <ol> <li> <p>注册 Router 账号 根据你使用的服务，打开对应后台注册并完成账号激活。XAI Router 可打开 <a rel="external" href="https://m.xairouter.com">m.xairouter.com</a>。</p> </li> <li> <p>获取 Router API Key 注册完成后，在对应 Router 后台或系统邮件中获取 API Key。后续在 LightVela 中填写这个 Key。</p> </li> <li> <p>确认要使用的模型 ID 不同接入点的模型权限可能不同，请以你实际使用的 Router 后台或团队给出的模型列表为准。常见示例：</p> <ul> <li><code>gpt-5.4-mini</code></li> <li><code>gpt-5.4</code></li> <li><code>gpt-5.5</code></li> </ul> </li> </ol> <h2 id="tui-jian-pei-zhi-openai-completions-jian-rong">推荐配置：OpenAI Completions 兼容</h2> <p>这是最推荐的接入方式，适合大多数 LightVela 场景。</p> <p>进入 LightVela 控制台后，打开你的智能体，进入：</p> <p><code>模型</code> → <code>自定义模型</code> 或 <code>添加自定义模型</code></p> <p>按下面填写：</p> <table><thead><tr><th>字段</th><th>填写内容</th></tr></thead><tbody> <tr><td>Provider</td><td>使用 XAI Router 填 <code>xairouter</code>；使用 YAI Router 填 <code>yairouter</code>；使用 ZAI Router 填 <code>zairouter</code></td></tr> <tr><td>Base URL</td><td>使用 XAI Router 填 <code>https://api.xairouter.com</code>；使用 YAI Router 填 <code>https://api.yairouter.com</code>；使用 ZAI Router 填 <code>https://api.zairouter.com</code></td></tr> <tr><td>兼容协议</td><td><code>OpenAI Completions</code></td></tr> <tr><td>API Key</td><td>你的 Router API Key，例如 <code>sk-xxx</code></td></tr> <tr><td>模型 ID</td><td>例如 <code>gpt-5.4-mini</code></td></tr> <tr><td>模型名称</td><td>可填写便于识别的名称，例如 <code>gpt-5.4-mini</code></td></tr> </tbody></table> <p>保存后，将当前模型切换到刚刚创建的模型配置。</p> <h2 id="claude-jian-rong-mo-xing-pei-zhi">Claude 兼容模型配置</h2> <p>如果你要接入 Claude 模型，也可以使用 Anthropic Messages 兼容协议：</p> <table><thead><tr><th>字段</th><th>填写内容</th></tr></thead><tbody> <tr><td>Provider</td><td>使用 XAI Router 可填 <code>xairouter-claude</code>；使用 YAI Router 可填 <code>yairouter-claude</code>；使用 ZAI Router 可填 <code>zairouter-claude</code></td></tr> <tr><td>Base URL</td><td>使用 XAI Router 填 <code>https://api.xairouter.com</code>；使用 YAI Router 填 <code>https://api.yairouter.com</code>；使用 ZAI Router 填 <code>https://api.zairouter.com</code></td></tr> <tr><td>兼容协议</td><td><code>Anthropic Messages</code></td></tr> <tr><td>API Key</td><td>你的 Router API Key</td></tr> <tr><td>模型 ID</td><td>例如 <code>claude-opus-4-6</code></td></tr> <tr><td>模型名称</td><td>例如 <code>claude-opus-4-6</code></td></tr> </tbody></table> <p>说明：这里推荐填写不带 <code>/v1</code> 的 Base URL。XAI Router 已兼容 <code>/v1</code> 有或没有的情况；如果你使用的是 YAI Router 或 ZAI Router，则把示例中的 XAI 接入点替换成对应接入点即可。</p> <h2 id="yan-zheng-shi-fou-jie-ru-cheng-gong">验证是否接入成功</h2> <p>保存模型配置后，回到 LightVela 的对话或测试工作台，发送一条简单消息：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>你好，请用一句话介绍你自己。</span></span></code></pre> <p>如果模型正常回复，说明接入成功。</p> <p>也可以在对应 Router 后台查看用量记录，确认请求已经通过正确的接入点发出。</p> <h2 id="chang-jian-wen-ti">常见问题</h2> <h3 id="1-base-url-ying-gai-tian-na-ge">1. Base URL 应该填哪个？</h3> <p>请根据自己的接入点填写：</p> <table><thead><tr><th>使用的服务</th><th>推荐 Base URL</th></tr></thead><tbody> <tr><td>XAI Router</td><td><code>https://api.xairouter.com</code></td></tr> <tr><td>YAI Router</td><td><code>https://api.yairouter.com</code></td></tr> <tr><td>ZAI Router</td><td><code>https://api.zairouter.com</code></td></tr> </tbody></table> <p><code>/v1</code> 可以不写。<code>https://api.xairouter.com</code> 已经兼容带 <code>/v1</code> 和不带 <code>/v1</code> 的写法；为了便于排查问题，建议文档和团队配置统一使用不带 <code>/v1</code> 的形式。</p> <h3 id="2-api-key-tian-shui-de">2. API Key 填谁的？</h3> <p>填写对应 Router 分配给你的 API Key，不是 OpenAI、Anthropic 或 Gemini 原厂 Key。使用 XAI Router 的 Key 就配 <code>https://api.xairouter.com</code>；使用 YAI Router 的 Key 就配 <code>https://api.yairouter.com</code>；使用 ZAI Router 的 Key 就配 <code>https://api.zairouter.com</code>。</p> <h3 id="3-mo-xing-id-tian-cuo-hui-zen-yang">3. 模型 ID 填错会怎样？</h3> <p>如果模型 ID 不存在或当前账号无权使用，LightVela 可能会提示模型调用失败。请到对应 Router 的模型列表确认模型 ID。</p> <h3 id="4-bao-cun-hou-reng-ran-bu-ke-yong-zen-me-ban">4. 保存后仍然不可用怎么办？</h3> <p>依次检查：</p> <ol> <li>API Key 是否完整，没有多余空格。</li> <li>Base URL 是否和你的 API Key 属于同一个接入点。</li> <li>模型 ID 是否在对应 Router 中可用。</li> <li>Router 账号是否有余额或有效套餐。</li> <li>LightVela 当前智能体是否已经切换到新建的模型配置。</li> </ol> <h2 id="can-kao-lian-jie">参考链接</h2> <ul> <li>LightVela 官网：<a rel="external" href="https://lightvela.com">https://lightvela.com</a></li> <li>XAI Router 快速开始：<a rel="external" href="https://xairouter.com/docs/getting-started/quick-start/">https://xairouter.com/docs/getting-started/quick-start/</a></li> <li>XAI Router 接口：<a rel="external" href="https://xairouter.com/docs/api-reference/proxy/">https://xairouter.com/docs/api-reference/proxy/</a></li> <li>XAI Router 支持的模型服务商：<a rel="external" href="https://xairouter.com/docs/getting-started/supported-providers/">https://xairouter.com/docs/getting-started/supported-providers/</a></li> <li>XAI Router BYOK 说明：<a rel="external" href="https://xairouter.com/docs/concepts/byok/">https://xairouter.com/docs/concepts/byok/</a></li> <li>YAI Router API 接入点：<code>https://api.yairouter.com</code></li> <li>ZAI Router API 接入点：<code>https://api.zairouter.com</code></li> </ul> XAI Router 与 YAI Router：同源官网，独立账号与核心 API 2026-06-10T08:00:00+00:00 2026-06-10T08:00:00+00:00 Unknown https://xaicontrol.com/blog/xai-yai-router-independent-api/ <figure class="content-image"> <img src="&#x2F;images&#x2F;xaixapi.svg" alt="" decoding="async" loading="lazy" > </figure> <p>很多用户第一次看到 <code>xairouter.com</code> 和 <code>yairouter.com</code> 时，会自然产生几个问题：</p> <ul> <li>这两个站是什么关系？</li> <li>官网内容为什么看起来一致？</li> <li>两个站的账号是否互通？</li> <li>企业系统到底应该接哪个 API？</li> <li>如果要做高可用，两个入口应该怎么理解？</li> </ul> <p>这篇文章专门把这件事讲清楚。</p> <p>一句话说明：<strong>XAI Router 与 YAI Router 是同源架构下的兄弟站点；官网内容保持一致，但账号系统、服务入口与核心 API 分别独立运行。</strong></p> <hr /> <h2 id="xian-kan-jie-lun">先看结论</h2> <p>面向用户访问和企业接入，可以把两站理解为四层关系：</p> <table><thead><tr><th>层级</th><th>XAI Router</th><th>YAI Router</th><th>说明</th></tr></thead><tbody> <tr><td>官网内容</td><td><code>https://xairouter.com</code></td><td><code>https://yairouter.com</code></td><td>展示同一套官网、文档入口和产品说明，方便用户从不同站点了解服务</td></tr> <tr><td>账号系统</td><td>XAI Router 账号</td><td>YAI Router 账号</td><td>完全独立，账号、API Key 与额度按站点分别管理</td></tr> <tr><td>服务入口</td><td><code>https://m.xairouter.com</code></td><td><code>https://m.yairouter.com</code></td><td>用户登录、套餐、控制台等服务入口分别存在</td></tr> <tr><td>核心 API</td><td><code>https://api.xairouter.com</code></td><td><code>https://api.yairouter.com</code></td><td>两个核心 API 入口独立运行，可分别用于企业接入规划</td></tr> </tbody></table> <p>所以，<code>yairouter.com</code> 不是一个完全无关的新产品，也不是简单的页面复制。它与 XAI Router 使用同源架构和同一套产品表达，但在账号系统和核心 API 层面具备独立边界。</p> <p>对普通用户来说，理解为“两个兄弟站点”就足够了。对企业用户来说，更重要的是后半句：<strong>账号系统与核心 API 独立运行。</strong></p> <hr /> <h2 id="wei-shen-me-guan-wang-nei-rong-bao-chi-yi-zhi">为什么官网内容保持一致</h2> <p>XAI Router 和 YAI Router 面向的是同一类服务能力：AI API 路由、模型接入、AI Coding 工具支持、额度治理、用量统计和企业接入。</p> <p>因此，两站展示同一套官网内容有三个好处：</p> <ol> <li><strong>信息一致</strong>：用户不需要判断“哪个站文档更新、哪个站说明过期”，核心产品说明保持统一。</li> <li><strong>认知简单</strong>：XAI Router 与 YAI Router 是兄弟站，不是两套互相竞争、互不相干的产品线。</li> <li><strong>接入清晰</strong>：官网负责解释产品，账号系统、服务入口和核心 API 负责承载实际业务。</li> </ol> <p>换句话说，官网内容一致，是为了降低理解成本；账号系统和核心 API 独立，是为了给业务接入留下更清晰的边界和更稳的工程空间。</p> <hr /> <h2 id="zhang-hao-xi-tong-wan-quan-du-li-shi-shen-me-yi-si">账号系统完全独立是什么意思</h2> <p>这是企业用户最需要提前理解的一点：</p> <p><strong>XAI Router 与 YAI Router 的账号系统完全独立。</strong></p> <p>这意味着：</p> <ul> <li>在 <code>m.xairouter.com</code> 注册或登录的是 XAI Router 账号</li> <li>在 <code>m.yairouter.com</code> 注册或登录的是 YAI Router 账号</li> <li>XAI Router 生成的 API Key 应用于 <code>api.xairouter.com</code></li> <li>YAI Router 生成的 API Key 应用于 <code>api.yairouter.com</code></li> <li>两站账号、API Key、额度和控制台配置需要按站点分别管理</li> </ul> <p>不要默认认为一个站的账号可以直接登录另一个站，也不要默认认为一个站的 API Key 可以直接调用另一个站的核心 API。</p> <p>对企业来说，这个边界非常重要。它让不同入口的账户、额度、权限和审计可以分开规划，也避免在主备或双入口接入时产生“入口切了，Key 没切”的隐性故障。</p> <p>如果企业希望两个站点在采购、额度、账单或权限策略上形成统一安排，应在企业合作阶段提前确认具体配置方式，而不是依赖默认互通。</p> <hr /> <h2 id="wei-shen-me-he-xin-api-yao-du-li">为什么核心 API 要独立</h2> <p>企业把 AI API 接入内部系统后，关心的就不只是“今天能不能调用成功”，而是更长期的问题：</p> <ul> <li>研发团队、自动化任务和内部系统是否有稳定入口？</li> <li>某个入口出现网络、线路、限流或维护问题时，有没有备用路径？</li> <li>API Base URL 能不能在配置层切换，而不是散落在代码里？</li> <li>日志、告警、健康检查和故障演练能不能覆盖不同入口？</li> </ul> <p>这就是独立核心 API 的意义。</p> <p><code>https://api.xairouter.com</code> 与 <code>https://api.yairouter.com</code> 分别作为两个独立 API 入口存在。企业可以根据自己的可用性要求，在客户端、内部网关、服务发现或配置中心里规划主备接入、双入口接入或业务连续性方案。</p> <p>这里需要特别说明：<strong>两站账号系统完全独立，独立 API 也不等于账号、账单和额度自动互通。</strong> 具体账户体系、额度归属、结算方式和企业策略，应以实际后台配置和企业合作约定为准。</p> <p>这也是更稳妥的企业级表达：API 入口独立，是基础设施能力；是否做主备、如何切换、哪些业务走哪个入口，是企业可以按自身要求设计的接入方案。</p> <hr /> <h2 id="qi-ye-yong-hu-ying-gai-zen-me-jie">企业用户应该怎么接</h2> <p>最重要的一条建议是：<strong>不要把 Base URL 写死在业务代码里。</strong></p> <p>建议至少把 API 入口做成环境变量或配置中心参数：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>XAI_ROUTER_BASE_URL</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">https://api.xairouter.com/v1</span></span> <span class="giallo-l"><span>XAI_ROUTER_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">sk-xai-...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>YAI_ROUTER_BASE_URL</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">https://api.yairouter.com/v1</span></span> <span class="giallo-l"><span>YAI_ROUTER_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">sk-yai-...</span></span></code></pre> <p>应用侧保持 OpenAI 兼容 SDK 的常规写法，把 <code>baseURL</code> 和对应站点的 API Key 一起交给配置：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> client</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>({</span></span> <span class="giallo-l"><span> apiKey: process.env.</span><span style="color: #79B8FF;">AI_API_KEY</span><span>,</span></span> <span class="giallo-l"><span> baseURL: process.env.</span><span style="color: #79B8FF;">AI_BASE_URL</span><span style="color: #F97583;"> ||</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> response</span><span style="color: #F97583;"> = await</span><span> client.chat.completions.</span><span style="color: #B392F0;">create</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-5-nano&quot;</span><span>,</span></span> <span class="giallo-l"><span> messages: [{ role:</span><span style="color: #9ECBFF;"> &quot;user&quot;</span><span>, content:</span><span style="color: #9ECBFF;"> &quot;hello&quot;</span><span> }],</span></span> <span class="giallo-l"><span>});</span></span></code></pre> <p>如果企业希望做主备，可以在配置中心维护当前主入口：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>AI_BASE_URL</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">https://api.xairouter.com/v1</span></span> <span class="giallo-l"><span>AI_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">sk-xai-...</span></span></code></pre> <p>当需要切换时，将 Base URL 和 API Key 一起调整为对应站点：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>AI_BASE_URL</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">https://api.yairouter.com/v1</span></span> <span class="giallo-l"><span>AI_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">sk-yai-...</span></span></code></pre> <p>更成熟的团队可以在内部 API Gateway、服务发现或业务 SDK 层加入健康检查和切换策略，但不建议把切换逻辑散落在每个业务函数里。</p> <hr /> <h2 id="tui-jian-de-qi-ye-jie-ru-qing-dan">推荐的企业接入清单</h2> <p>如果你是企业管理员、平台工程负责人或研发负责人，可以按下面的清单规划：</p> <ol> <li> <p><strong>配置化 Base URL</strong><br /> 所有应用统一从环境变量、配置中心或内部网关读取 API Base URL。</p> </li> <li> <p><strong>同时纳入网络白名单</strong><br /> 企业出口、防火墙、代理、零信任网关和日志系统中，同时登记 <code>api.xairouter.com</code> 与 <code>api.yairouter.com</code>。</p> </li> <li> <p><strong>区分观测标签</strong><br /> 日志和监控中保留 <code>xai</code> / <code>yai</code> 或 endpoint 标签，方便排查具体入口的延迟、错误率和调用量。</p> </li> <li> <p><strong>建立切换预案</strong><br /> 明确什么情况下切换、由谁确认、切换后如何验证，以及是否需要回切。</p> </li> <li> <p><strong>定期做小流量演练</strong><br /> 企业不要等到故障当天才第一次使用备用入口。可以定期用测试任务或低风险业务验证备用入口可用性。</p> </li> <li> <p><strong>确认账号和额度边界</strong><br /> 两站账号系统完全独立。企业如果需要两个入口在采购、额度、账单、策略和权限上形成统一安排，应提前与服务团队确认配置方式。</p> </li> </ol> <p>这套清单的目标不是把接入复杂化，而是让企业在真正需要高可用时，不会临时发现所有配置都写死在代码里。</p> <hr /> <h2 id="chang-jian-wen-ti">常见问题</h2> <h3 id="1-xairouter-com-he-yairouter-com-de-guan-wang-nei-rong-yi-yang-ma">1. <code>xairouter.com</code> 和 <code>yairouter.com</code> 的官网内容一样吗？</h3> <p>是的。两站展示同一套官网内容和产品说明，方便用户从任一站点了解 XAI Router 服务。</p> <h3 id="2-liang-ge-fu-wu-ru-kou-fen-bie-shi-shen-me">2. 两个服务入口分别是什么？</h3> <p>XAI Router 的服务入口是：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://m.xairouter.com</span></span></code></pre> <p>YAI Router 的服务入口是：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://m.yairouter.com</span></span></code></pre><h3 id="3-liang-ge-zhan-de-zhang-hao-hu-tong-ma">3. 两个站的账号互通吗？</h3> <p>不互通。XAI Router 与 YAI Router 的账号系统完全独立，账号、API Key、额度和控制台配置需要按站点分别管理。</p> <h3 id="4-liang-ge-he-xin-api-fen-bie-shi-shen-me">4. 两个核心 API 分别是什么？</h3> <p>XAI Router 核心 API：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://api.xairouter.com</span></span></code></pre> <p>YAI Router 核心 API：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://api.yairouter.com</span></span></code></pre> <p>如果你使用 OpenAI 兼容 SDK，通常会配置为：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>https://api.xairouter.com/v1</span></span> <span class="giallo-l"><span>https://api.yairouter.com/v1</span></span></code></pre><h3 id="5-shi-yong-yai-router-xu-yao-geng-huan-sdk-ma">5. 使用 YAI Router 需要更换 SDK 吗？</h3> <p>通常不需要。对于 OpenAI 兼容调用，核心变化是 <code>baseURL</code> 和对应站点的 API Key。只要业务代码已经把 Base URL 与 API Key 配置化，就可以更容易地在两个入口之间切换。</p> <h3 id="6-liang-ge-api-shi-zi-dong-hu-xiang-qie-huan-de-ma">6. 两个 API 是自动互相切换的吗？</h3> <p>不要默认这样理解。两站核心 API 独立运行，企业可以按需在自己的客户端、内部网关或配置中心设计主备、双入口和业务连续性方案。自动切换策略是否启用、如何启用，应以企业自己的接入设计和服务配置为准。</p> <h3 id="7-zhe-shi-fou-deng-tong-yu-si-you-hua-bu-shu">7. 这是否等同于私有化部署？</h3> <p>不是。双站 API 是云上独立入口的接入能力；私有化部署是把 XAI Router 部署到企业自己的环境或专属环境中。两者可以服务于不同阶段的可用性、控制权和合规需求。</p> <hr /> <h2 id="zong-jie">总结</h2> <p>XAI Router 与 YAI Router 的关系可以概括为：</p> <ul> <li><strong>同源架构</strong>：两者是兄弟站点，产品能力和官网表达保持一致。</li> <li><strong>账号独立</strong>：两站账号系统完全独立，账号、API Key 与额度按站点分别管理。</li> <li><strong>入口清晰</strong>：服务入口分别是 <code>m.xairouter.com</code> 与 <code>m.yairouter.com</code>。</li> <li><strong>API 独立</strong>：核心 API 分别是 <code>api.xairouter.com</code> 与 <code>api.yairouter.com</code>。</li> <li><strong>面向企业高可用</strong>：企业可按需规划主备接入、双入口接入和业务连续性方案。</li> </ul> <p>对个人用户来说，选择任一明确入口使用即可。对企业用户来说，建议从第一天就把 Base URL、网络白名单、监控标签和切换预案设计好，让 AI API 真正成为可治理、可演练、可持续运行的基础设施。</p> <p>相关入口：</p> <ul> <li><a rel="external" href="https://m.xairouter.com">XAI Router 服务入口</a></li> <li><a rel="external" href="https://m.yairouter.com">YAI Router 服务入口</a></li> <li><a href="/contact/">企业合作</a></li> <li><a href="/docs/products/xai-router/">XAI Router 私有化</a></li> </ul> ChatGPT Memory Dreaming：它到底记住了什么，又该怎么用？ 2026-06-07T00:00:00+00:00 2026-06-07T00:00:00+00:00 Unknown https://xaicontrol.com/blog/chatgpt-memory-dreaming/ <figure class="content-image"> <img src="&#x2F;images&#x2F;openai-logo-email-header.png" alt="" decoding="async" loading="lazy" > </figure> <p>OpenAI 在 <strong>2026 年 6 月 4 日</strong>发布了文章 <a rel="external" href="https://openai.com/index/chatgpt-memory-dreaming/">Dreaming: Better memory for a more helpful ChatGPT</a>，介绍了 ChatGPT 记忆系统的一次重要升级：它不再只是像“便签本”一样记几条你明确要求它记住的内容，而是开始用一种叫 <strong>dreaming</strong> 的方式，在后台把过往对话里有用的信息整理成更及时、更连贯、更相关的上下文。</p> <p>这篇文章不按技术论文的方式讲，而是站在普通用户角度回答几个问题：ChatGPT 的 memory 到底是什么？Dreaming 又是什么？它会带来什么变化？如果你不希望它记住某些内容，该怎么管理？</p> <blockquote> <p>说明：本文基于 OpenAI 官方原文和 <a rel="external" href="https://help.openai.com/en/articles/8590148-memory-faq">Memory FAQ</a> 的中文整理与解释，不是逐字翻译。不同账号、地区和订阅计划的实际入口可能会随灰度发布节奏略有差异。</p> </blockquote> <hr /> <h2 id="yi-ju-hua-xian-jiang-qing-chu">一句话先讲清楚</h2> <p>ChatGPT 的新 memory 不是“把你每句话都背下来”，更像是：它会从你的聊天、文件和已连接应用中提炼出对未来回答有帮助的背景信息，例如你的偏好、正在做的项目、长期约束、常用工作方式、已经结束的计划等，然后在相关问题出现时拿出来使用。</p> <p>对用户来说，目标很简单：</p> <ul> <li>少重复自我介绍</li> <li>让回答更贴合你的习惯和处境</li> <li>长期项目能接着之前的上下文继续</li> <li>已经过期的信息不要一直误导回答</li> <li>你可以查看、纠正、关闭或删除相关记忆</li> </ul> <h2 id="yi-qian-de-memory-geng-xiang-shou-dong-bian-qian">以前的 Memory：更像手动便签</h2> <p>ChatGPT 的 memory 最早在 2024 年 4 月推出，当时更接近“保存记忆”。你可以对 ChatGPT 说：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请记住我不吃牛肉。</span></span></code></pre> <p>或者：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>以后给我写邮件时，语气正式一点。</span></span></code></pre> <p>这种方式很好理解，但问题也明显：它很依赖你主动说“记住”。如果你只是在自然聊天里提到某个长期偏好，系统未必会抓住；如果一条记忆过期了，例如“我下个月去新加坡出差”，过了几个月它还被当成当前状态，回答就会变得别扭甚至错误。</p> <p>所以旧方式像一个会记笔记的助手，但笔记容易不完整，也容易变旧。</p> <h2 id="dreaming-shi-shen-me-bu-shi-zuo-meng-shi-hou-tai-zheng-li-shang-xia-wen">Dreaming 是什么：不是做梦，是后台整理上下文</h2> <p>OpenAI 把这套新方法叫 <strong>dreaming</strong>。这个词容易让人误会，但放到 ChatGPT memory 里，可以把它理解成“后台整理记忆”。</p> <p>它做的不是在你聊天时机械地追加一条条记录，而是在后台综合多轮对话，把有用的信息整理成一种更适合未来使用的 memory 状态。比如：</p> <ul> <li>你经常让 ChatGPT 帮你改中文产品文案，它可能记住你偏好短句、少形容词、直接给可发布版本。</li> <li>你多次讨论某个创业项目，它可能记住项目方向、目标用户、当前阶段和你不想采用的方案。</li> <li>你曾经计划 7 月去新加坡，但旅行已经结束，它应该逐渐把“即将去新加坡”更新成“曾在 2026 年 7 月去过新加坡”，而不是继续把你当成旅途中。</li> </ul> <p>这就是 OpenAI 原文反复强调的三个目标：<strong>延续有用上下文、遵守偏好与限制、随着时间保持更新</strong>。</p> <h2 id="zhe-ci-sheng-ji-wei-shen-me-zhong-yao">这次升级为什么重要</h2> <p>对普通用户来说，这次升级最直接的价值不是“ChatGPT 更懂技术”，而是它更像一个能长期协作的助手。</p> <h3 id="1-bu-yong-mei-ci-cong-ling-kai-shi">1. 不用每次从零开始</h3> <p>如果你长期用 ChatGPT 做同一类事情，例如学习英语、整理周报、规划旅行、做健身饮食、写产品文案、管理一个项目，过去每次开新对话都要重新说明背景。</p> <p>有了更好的 memory 后，你可以直接说：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>按我平时的风格，帮我改一下这段介绍。</span></span></code></pre> <p>或者：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>继续按我们之前那个项目定位，写一个给投资人的版本。</span></span></code></pre> <p>ChatGPT 如果能正确拿到相关上下文，就不需要你重复解释“平时的风格”或“之前那个项目定位”。</p> <h3 id="2-hui-da-geng-fu-he-ni-de-pian-hao">2. 回答更符合你的偏好</h3> <p>OpenAI 原文举了旅行规划的例子：如果 ChatGPT 已经知道你喜欢野生动物摄影、偏好安静晚餐、睡觉时很在意空调，那么它给你的新加坡行程就不该只是普通景点清单，而应该围绕这些偏好安排。</p> <p>换成日常场景也是一样：</p> <ul> <li>你是素食者，餐厅和食谱推荐应避开不合适的选项。</li> <li>你住在某个城市，周末建议应优先考虑本地距离。</li> <li>你偏好简洁输出，回答就不该每次写成大段说明。</li> <li>你正在备考，学习建议应结合你的目标和剩余时间。</li> </ul> <p>好的 memory 不只是“记住一个事实”，而是能在合适的时候用它改善答案。</p> <h3 id="3-guo-qi-xin-xi-geng-shao-gan-rao-hui-da">3. 过期信息更少干扰回答</h3> <p>很多信息有时间性：旅行、会议、考试、搬家、项目阶段、临时饮食计划、短期目标。旧记忆系统最大的问题之一，就是它可能把过期状态继续当成当前状态。</p> <p>Dreaming 的目标之一，就是让 memory 能理解时间变化。比如你 6 月说“我 7 月去新加坡”，到 8 月就不应该继续推荐新加坡当地外卖；更合理的是知道那段旅行已经结束，并回到你的常住地、当前时间和新的需求上。</p> <p>这对普通用户很重要，因为真正影响体验的往往不是 ChatGPT 会不会记住，而是它会不会在正确时间记住正确的东西。</p> <h2 id="memory-summary-ni-ke-yi-kan-dao-ta-da-gai-zhi-dao-shen-me">Memory Summary：你可以看到它大概知道什么</h2> <p>这次更新里，一个很实用的变化是 <strong>Memory Summary</strong>。你可以把它理解成 ChatGPT 对“我知道哪些和你有关的信息”的摘要页。</p> <p>根据 OpenAI 的说明，Memory Summary 会展示 ChatGPT 认为重要的记忆重点，并会随着你继续使用而更新。你可以在这里快速检查：</p> <ul> <li>它对你的职业、兴趣、项目、偏好理解是否正确</li> <li>有没有过期、错误或你不希望再提的内容</li> <li>是否需要补充更明确的信息</li> <li>是否要要求它以后避开某些话题</li> </ul> <p>但要注意：Memory Summary 不是完整日志。它不一定展示 ChatGPT 可用于个性化的每个细节，只是给用户一个更容易理解和管理的高层视图。如果你想确认它是否记住某件事，最直接的方法仍然是问：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>你现在记得哪些和我有关的信息？</span></span></code></pre> <p>或者：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>你刚才这个回答用到了我的哪些记忆？</span></span></code></pre><h2 id="ta-hui-bu-hui-luan-yong-wo-de-yin-si">它会不会乱用我的隐私？</h2> <p>Memory 带来便利，也必然带来隐私问题。普通用户需要记住几条原则。</p> <p>第一，<strong>不要把你不希望长期影响回答的信息随便告诉 ChatGPT</strong>。如果只是一次性敏感问题，可以使用 Temporary Chat，或者先关闭 memory。</p> <p>第二，<strong>你可以管理 memory</strong>。OpenAI 的 FAQ 提到，memory 控制入口在 Settings 里的 Memory 或 Personalization 相关页面。你可以开启、关闭、查看摘要、纠正内容，也可以让 ChatGPT 忘记某些信息。</p> <p>第三，<strong>删除要分清来源</strong>。如果某个信息出现在 saved memories、历史聊天、文件库或连接应用里，仅仅改掉摘要不一定等于彻底删除。要完整移除，通常需要把相关记忆、原始聊天、相关文件或连接应用里的来源都处理掉。</p> <p>第四，<strong>Temporary Chat 更适合临时内容</strong>。如果你只是想问一个一次性问题，不希望它影响以后回答，用临时聊天更稳妥。</p> <h2 id="pu-tong-yong-hu-ying-gai-zen-me-yong">普通用户应该怎么用</h2> <p>你不需要学习“提示词工程”才能用好 memory。更实际的做法是把 ChatGPT 当成一个会整理长期偏好的助手，主动告诉它什么应该稳定保留，什么只是临时上下文。</p> <p>可以这样用：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请记住：以后帮我写中文内容时，优先使用短句，少用夸张表达。</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>这只是一次临时讨论，不要把它作为我的长期偏好。</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>请忘记我之前说的那个旅行计划，它已经结束了。</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>检查一下你关于我的记忆，把过期或不确定的内容列出来。</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>以后不要再主动提起这个话题，除非我明确问到。</span></span></code></pre> <p>如果你经常用 ChatGPT 处理工作、学习和生活安排，建议隔一段时间主动检查一次 Memory Summary。它就像个人资料页：准不准，直接影响个性化质量。</p> <h2 id="custom-instructions-he-memory-you-shen-me-qu-bie">Custom Instructions 和 Memory 有什么区别</h2> <p>很多人会把 Custom Instructions 和 Memory 混在一起。简单区分：</p> <ul> <li><strong>Custom Instructions</strong>：适合写明确、稳定、你希望长期生效的规则。例如“回答默认用中文”“我是一名产品经理”“示例尽量贴近 B2B SaaS 场景”。</li> <li><strong>Memory</strong>：更适合 ChatGPT 在日常对话中逐步整理出来的背景。例如你正在做的项目、最近反复提到的偏好、已经变化的计划、常见工作方式。</li> </ul> <p>如果一个要求非常重要，最好直接写进 Custom Instructions 或明确告诉 ChatGPT 记住；如果只是自然聊天中出现的信息，memory 可能会在合适的时候吸收，但不要把它当成绝对可靠的记录系统。</p> <h2 id="shui-xian-zai-neng-yong-dao">谁现在能用到</h2> <p>按照 OpenAI 2026 年 6 月 4 日原文，这次更新先向美国的 Plus 和 Pro 用户推出，随后会扩展到更多国家，以及 Free 和 Go 用户。Memory FAQ 也提到，新系统正在按计划和地区逐步发布。</p> <p>所以如果你现在没有看到完全一样的入口，不一定是设置错误，可能只是账号、地区、客户端或订阅计划还没轮到。建议以 ChatGPT 设置页里实际展示的 Memory / Personalization 选项为准。</p> <h2 id="zhe-dai-biao-chatgpt-zheng-zai-bian-cheng-shen-me">这代表 ChatGPT 正在变成什么</h2> <p>这次 memory 升级的意义，不只是“更会记东西”。更大的变化是：ChatGPT 正在从一次一答的聊天工具，变成能跨时间理解用户的长期助手。</p> <p>一次性聊天里，AI 只需要回答当前问题；长期助手则必须知道哪些信息值得延续，哪些偏好应该遵守，哪些状态已经过期，哪些内容不该再提。Dreaming 解决的正是这个问题：让 ChatGPT 不只是保存零散记忆，而是持续整理一份更有用的个人上下文。</p> <p>普通用户真正需要关心的也很简单：让它记住能提升效率的稳定信息，及时纠正错误记忆，对敏感内容使用临时聊天或关闭 memory。这样，ChatGPT 才会越来越像一个了解你工作和生活习惯的助手，而不是每次都重新认识你的陌生人。</p> 从 imagegen 开始认识 Codex Skill：普通用户快速上手 2026-05-29T08:00:00+00:00 2026-05-29T08:00:00+00:00 Unknown https://xaicontrol.com/blog/codex-skills/ <figure class="content-image"> <img src="&#x2F;images&#x2F;gpt-5-5-gpt-image-2-cover.png" alt="" decoding="async" loading="lazy" > </figure> <p>很多人第一次看到 <code>SKILL.md</code>，会以为它是给开发者看的配置文件。其实对普通用户来说，skill 更像是 <strong>给 Codex 装上的专门能力包</strong>。</p> <p>你不需要先理解复杂的插件系统，也不需要自己写代码。先从一个最直观的例子开始：<code>imagegen</code>。</p> <p><code>imagegen</code> 是 Codex 内置的系统 skill，用来生成或编辑图片。比如你可以让 Codex 生成博客封面、产品概念图、网站 hero 背景、游戏素材、UI mockup，或者根据参考图做视觉变体。</p> <p>一句话理解：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>普通 prompt 是临时说一遍怎么做。</span></span> <span class="giallo-l"><span>skill 是把一类任务的做法长期保存下来，需要时直接调用。</span></span></code></pre> <hr /> <h2 id="xian-kan-yi-ge-zui-xiao-li-zi">先看一个最小例子</h2> <p>打开 Codex 后，在对话里输入：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $imagegen 生成一张 16:9 博客封面图，主题是 Codex Skills，风格干净、科技感、适合文档站首页。</span></span></code></pre> <p>这不是在终端里执行命令，而是在 <strong>Codex 对话框里输入</strong>。</p> <p>如果当前 Codex 环境支持这个内置 skill，Codex 会加载 <code>imagegen</code> 的 <code>SKILL.md</code>，理解它应该如何处理图片生成任务。它不仅知道“要作图”，也知道生成图片后应该如何保存、什么时候需要放进项目目录、什么时候只是预览。</p> <p>这就是 skill 和普通 prompt 的区别。</p> <hr /> <h2 id="skill-md-dao-di-shi-shen-me">SKILL.md 到底是什么</h2> <p>一个 skill 通常是一个文件夹，核心文件叫 <code>SKILL.md</code>。最小结构类似这样：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>imagegen/</span></span> <span class="giallo-l"><span> SKILL.md</span></span> <span class="giallo-l"><span> scripts/</span></span> <span class="giallo-l"><span> references/</span></span> <span class="giallo-l"><span> assets/</span></span></code></pre> <p>其中 <code>SKILL.md</code> 会告诉 Codex：</p> <ul> <li>这个 skill 适合什么任务</li> <li>什么时候不该用它</li> <li>具体工作流程是什么</li> <li>是否需要脚本、参考资料或素材</li> <li>结果应该如何交付</li> </ul> <p>所以 <code>SKILL.md</code> 不是普通说明文档。它更像是 Codex 可读取的工作手册。</p> <p>以 <code>imagegen</code> 为例，它会告诉 Codex：图片生成默认走内置作图工具；如果用户只是普通生成或编辑图片，不需要单独配置 <code>OPENAI_API_KEY</code>；只有用户明确选择 CLI/API fallback 时，才会进入需要 API Key 的路径。</p> <hr /> <h2 id="imagegen-gua-he-zuo-shen-me">imagegen 适合做什么</h2> <p>普通用户最容易理解的场景有这些：</p> <h3 id="1-sheng-cheng-bo-ke-feng-mian">1. 生成博客封面</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $imagegen 生成一张适合博客文章的封面图。</span></span> <span class="giallo-l"><span>主题：AI agent 的技能库</span></span> <span class="giallo-l"><span>比例：16:9</span></span> <span class="giallo-l"><span>风格：清爽、现代、适合技术博客</span></span> <span class="giallo-l"><span>不要文字，不要 logo。</span></span></code></pre><h3 id="2-gei-wang-zhan-zuo-shi-jue-su-cai">2. 给网站做视觉素材</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $imagegen 为当前文档站生成一个 SKILL.md 技能库页面的背景图。</span></span> <span class="giallo-l"><span>要求：抽象卡片网格、轻量科技感、不要文字，适合浅色和深色模式。</span></span> <span class="giallo-l"><span>如果结果要用于项目，请保存到 static/images/skills-library-cover.png。</span></span></code></pre> <p>这个例子里，最后一句很重要。如果你希望图片进入项目，就要明确说保存路径。Codex 才能把最终图片放到仓库里，而不是只停留在临时预览。</p> <h3 id="3-gen-ju-xian-you-tu-pian-ji-xu-gai">3. 根据现有图片继续改</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $imagegen 把这张封面图改得更适合产品文档站：</span></span> <span class="giallo-l"><span>减少装饰元素，增加信息秩序感，保留整体色调。</span></span></code></pre> <p>如果你上传了图片，Codex 可以把它当作编辑目标或参考图。你也可以明确说明：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>第一张图作为编辑目标，第二张图只作为风格参考。</span></span></code></pre> <p>这种角色说明越清楚，结果越稳定。</p> <hr /> <h2 id="system-skill-he-curated-skill-you-shen-me-qu-bie">system skill 和 curated skill 有什么区别</h2> <p>在 <a href="/skills/">SKILL 页面</a> 里，你会看到两类 skill：</p> <ul> <li><code>.system</code>：Codex 内置，通常不需要安装</li> <li><code>.curated</code>：OpenAI 精选技能，需要用安装器安装</li> </ul> <p><code>imagegen</code> 属于 <code>.system</code>，所以不需要执行安装。</p> <p>如果你看到的是 <code>chatgpt-apps</code>、<code>linear</code>、<code>pdf</code>、<code>vercel-deploy</code> 这类 <code>.curated</code> skill，安装方式是在 Codex 对话里输入：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>$skill-installer chatgpt-apps</span></span></code></pre> <p>注意：这仍然是在 <strong>Codex 对话里输入</strong>，不是在系统终端里执行。</p> <p>不要这样做：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>$skill-installer chatgpt-apps</span></span></code></pre> <p>在 shell 里，<code>$skill-installer</code> 会被当作环境变量展开，它不是命令。</p> <p>安装完成后，通常需要重启 Codex，新的 skill 才会出现在可用列表里。</p> <hr /> <h2 id="zen-me-zhi-dao-zi-ji-you-na-xie-skill">怎么知道自己有哪些 skill</h2> <p>最简单的方式是在 Codex 里试：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/skills</span></span></code></pre> <p>或者直接输入 <code>$</code>，看 Codex 是否弹出可用 skill 列表。</p> <p>你也可以从本站顶部的 <code>技能库</code> 入口进入 <a href="/skills/">SKILL 技能库</a>，按名称、用途或分类搜索。比如：</p> <ul> <li>想作图：搜 <code>imagegen</code></li> <li>想读 PDF：搜 <code>pdf</code></li> <li>想部署网站：搜 <code>vercel-deploy</code>、<code>netlify-deploy</code></li> <li>想处理 GitHub CI：搜 <code>gh-fix-ci</code></li> <li>想做安全分析：搜 <code>security-threat-model</code></li> </ul> <hr /> <h2 id="pu-tong-yong-hu-de-tui-jian-yong-fa">普通用户的推荐用法</h2> <p>刚开始不需要学所有 skill。按下面这个顺序就够了：</p> <ol> <li>先用内置 skill：比如 <code>$imagegen</code>、<code>$skill-creator</code>、<code>$skill-installer</code></li> <li>有明确任务时再搜索：去 <code>𝑆𝐾𝐼𝐿𝐿</code> 页面找对应 skill</li> <li>看到 <code>.curated</code> skill 后，用 <code>$skill-installer &lt;name&gt;</code> 安装</li> <li>安装后重启 Codex</li> <li>下次对话里直接点名调用：比如 <code>用 $pdf 检查这个文件</code></li> </ol> <p>如果你不知道该不该点名 skill，可以直接自然语言描述任务。Codex 有时也会根据任务自动选择合适的 skill。但对新手来说，显式写 <code>$imagegen</code>、<code>$pdf</code>、<code>$linear</code> 更容易理解，也更可控。</p> <hr /> <h2 id="chang-jian-wu-qu">常见误区</h2> <h3 id="wu-qu-yi-ba-skill-dang-cheng-xin-mo-xing">误区一：把 skill 当成新模型</h3> <p>Skill 不是模型。<code>imagegen</code> 不是一个新模型名，它是一套工作流程说明。</p> <p>模型负责生成或推理，skill 负责告诉 Codex：这类任务应该按什么步骤做。</p> <h3 id="wu-qu-er-ba-skill-installer-dang-zhong-duan-ming-ling">误区二：把 <code>$skill-installer</code> 当终端命令</h3> <p><code>$skill-installer chatgpt-apps</code> 应该输入到 Codex 对话里。</p> <p>终端命令通常长这样：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codex</span></span></code></pre> <p>或者：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">npm</span><span style="color: #9ECBFF;"> i</span><span style="color: #79B8FF;"> -g</span><span style="color: #9ECBFF;"> @openai/codex@latest</span></span></code></pre> <p>两者不要混淆。</p> <h3 id="wu-qu-san-suo-you-skill-du-yao-an-zhuang">误区三：所有 skill 都要安装</h3> <p>不需要。<code>.system</code> 类型已经内置，例如：</p> <ul> <li><code>imagegen</code></li> <li><code>openai-docs</code></li> <li><code>skill-installer</code></li> <li><code>skill-creator</code></li> <li><code>plugin-creator</code></li> </ul> <p>只有 <code>.curated</code> 或第三方 skill 才需要安装。</p> <h3 id="wu-qu-si-di-san-fang-skill-ke-yi-sui-bian-zhuang">误区四：第三方 skill 可以随便装</h3> <p>不要把 skill 只当成“提示词”。一个 skill 可能包含脚本、参考文件和自动化步骤。安装第三方来源前，最好先看它的 <code>SKILL.md</code> 和脚本内容。</p> <hr /> <h2 id="zui-hou-yong-yi-ju-hua-ji-zhu">最后，用一句话记住</h2> <p>如果你只记住一件事：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Skill 是 Codex 的可复用工作流。imagegen 是最容易上手的例子：在 Codex 里输入 $imagegen，然后用自然语言描述你想要的图片。</span></span></code></pre> <p>想找更多现成 skill，可以从站点顶部的 <a href="/skills/">技能库</a> 开始。想系统理解 skill、prompt 和 plugin 的区别，可以继续看《<a href="/blog/openai-skills-guide/">OpenAI Skills 是什么？普通用户也能看懂的上手指南</a>》。</p> <p>参考资源：</p> <ul> <li><a rel="external" href="https://github.com/openai/skills">OpenAI Skills GitHub 仓库</a></li> <li><a rel="external" href="https://github.com/openai/skills/tree/main/skills/.system/imagegen">imagegen skill 源码</a></li> </ul> OpenAI 如何在内部使用 Codex：7 个工程场景与实践方法 2026-05-21T08:00:00+00:00 2026-05-21T08:00:00+00:00 Unknown https://xaicontrol.com/blog/how-openai-uses-codex/ <figure class="content-image"> <img src="&#x2F;images&#x2F;codex.webp" alt="" decoding="async" loading="lazy" > </figure> <p>OpenAI 在官方 PDF <a rel="external" href="https://cdn.openai.com/pdf/6a2631dc-783e-479b-b1a4-af0cfbd38630/how-openai-uses-codex.pdf">How OpenAI uses Codex</a> 中，整理了 Codex 在其内部工程团队中的真实使用方式。文档来自 OpenAI 工程师访谈与内部使用数据，重点不是介绍某个单点功能，而是回答一个更实用的问题：当 Codex 被放进高复杂度、高节奏的软件工程环境里，它到底能在哪些环节产生价值？</p> <blockquote> <p>说明：本文是基于官方 PDF 的中文译写与结构化整理，覆盖原文完整章节与要点，便于中文读者阅读；不是对原文的逐字转载。</p> </blockquote> <hr /> <h2 id="zong-lan-codex-yi-jin-ru-openai-de-ri-chang-gong-cheng-liu">总览：Codex 已进入 OpenAI 的日常工程流</h2> <p>在 OpenAI 内部，Codex 已经被安全、产品工程、前端、API、基础设施、性能工程等多个技术团队日常使用。它承担的任务范围很宽，从理解陌生代码、重构大型代码库，到发布新功能、排查线上事故、补齐测试和清理技术债，都有相应场景。</p> <p>这份文档传递出的核心判断是：Codex 的价值不只是“帮你写几行代码”，而是能在工程工作中承担一部分上下文收集、方案拆解、机械性改动、测试生成和辅助排障工作。对团队来说，它更像一个能在仓库里行动的工程协作者，而不是单纯的代码补全工具。</p> <p>OpenAI 把内部用法归纳为 7 类：</p> <ol> <li>代码理解</li> <li>重构与迁移</li> <li>性能优化</li> <li>提升测试覆盖率</li> <li>提高开发速度</li> <li>保持工作心流</li> <li>探索与方案构思</li> </ol> <p>下面逐项展开。</p> <h2 id="1-dai-ma-li-jie-geng-kuai-jin-ru-mo-sheng-xi-tong">1. 代码理解：更快进入陌生系统</h2> <p>工程师最常遇到的问题之一，是在一个不熟悉的代码区域里快速定位核心逻辑。无论是新人 onboarding、临时接手模块、排查 bug，还是线上事故响应，都需要先回答几个基础问题：入口在哪里？调用链怎么走？状态在哪里变化？失败如何传播？哪些模块彼此依赖？</p> <p>OpenAI 内部团队会让 Codex 帮忙梳理这些问题。它可以从仓库中定位某个功能的核心实现，解释服务或模块之间的关系，追踪请求、数据和错误状态的流转路径，也能暴露一些原本需要人工整理的架构模式或缺失文档。</p> <p>在事故响应时，这一点尤其有价值。工程师不一定熟悉出问题的子系统，但可以把错误栈、日志片段或现象描述交给 Codex，让它先找出相关文件、组件关系和可疑路径。这样人可以更快进入判断阶段，而不是把大量时间消耗在“先找到哪里该看”上。</p> <p>可以借鉴的提问方式：</p> <ul> <li>这个仓库里的认证逻辑主要在哪里实现？</li> <li>请从入口到响应返回，解释这个服务的请求链路。</li> <li>某个模块和哪些组件交互？失败路径是如何处理的？</li> <li>根据这段错误栈，帮我定位最可能相关的文件和调用链。</li> </ul> <h2 id="2-zhong-gou-yu-qian-yi-rang-kua-wen-jian-gai-dong-geng-yi-zhi">2. 重构与迁移：让跨文件改动更一致</h2> <p>第二类高频场景是重构和迁移。很多工程改动不是修改单个函数，而是跨多个包、多个目录甚至几十个文件同步推进。例如 API 形态升级、旧模式替换、新依赖迁移、回调风格改成异步写法、拆分过大的模块、为后续测试做结构调整等。</p> <p>这类任务靠正则或查找替换往往不够，因为真正困难的不是“找到字符串”，而是理解每个调用点在上下文中的语义差异。Codex 可以在改动时结合文件结构、依赖关系、局部代码风格和已有实现模式，生成更一致的修改。</p> <p>OpenAI 的内部用法里，Codex 还会被用于清理历史代码：把过时写法替换成当前推荐模式，把过大的文件按职责拆分，或者先分析旧模式影响范围，再输出 Markdown 说明和对应 PR。对发布前的阻塞问题来说，这种“先扫描、再总结、再修复”的流程尤其实际。</p> <p>可以借鉴的提问方式：</p> <ul> <li>请找出旧服务调用模式的所有使用点，并按影响范围分组。</li> <li>把这个大文件按职责拆成几个模块，并为拆分后的模块补充测试。</li> <li>将数据库访问从回调风格迁移到 async/await，保持现有行为不变。</li> <li>参考某个模块里的新模式，迁移当前目录下的同类实现。</li> </ul> <h2 id="3-xing-neng-you-hua-fa-xian-man-lu-jing-yu-zhong-fu-cheng-ben">3. 性能优化：发现慢路径与重复成本</h2> <p>Codex 也被 OpenAI 团队用于性能和可靠性工作。典型任务包括分析慢路径、识别内存占用较高的实现、发现低效循环、重复计算、重复数据库调用、昂贵查询和可以缓存的中间结果。</p> <p>性能优化的难点通常不是“能否写出一个更短的函数”，而是先找到真正值得优化的路径。Codex 可以帮助工程师扫过请求处理器、数据访问层或批处理逻辑，指出潜在热点，再给出可评审的替代方案。人类工程师仍然需要做基准测试、验证语义和选择最终方案，但前期分析成本会下降。</p> <p>另一个重要用途是代码健康检查。OpenAI 文档提到，团队也会用 Codex 发现仍在活跃使用的风险模式或弃用模式。这样做的价值不只在当前性能收益，还在于减少长期技术债，降低未来回归问题的概率。</p> <p>可以借鉴的提问方式：</p> <ul> <li>分析这个请求处理函数里是否存在重复昂贵操作。</li> <li>找出可以批量化的数据库查询，并说明改动风险。</li> <li>这个循环能否降低内存占用？请解释优化后的复杂度变化。</li> <li>扫描当前模块中仍在使用的弃用 API 或高风险模式。</li> </ul> <h2 id="4-ti-sheng-ce-shi-fu-gai-lu-ba-bian-jie-qing-kuang-xi-tong-hua">4. 提升测试覆盖率：把边界情况系统化</h2> <p>测试是 Codex 很适合介入的环节，尤其是覆盖薄弱或完全没有测试的区域。OpenAI 内部工程师会在修 bug 或重构时，让 Codex 建议应覆盖的边界条件、失败路径和回归场景。对于新代码，Codex 可以根据函数签名、周边逻辑和已有测试风格生成单元测试或集成测试草稿。</p> <p>这类工作看似简单，但实际很消耗注意力。开发者经常能想到主路径测试，却容易漏掉空输入、最大长度、非法状态、罕见但合法的组合、权限分支、网络异常或依赖返回异常。Codex 的优势是可以系统性列举这些情况，并把它们转成可运行测试。</p> <p>更实际的做法是，让 Codex 先分析缺口，再生成测试，而不是直接要求它“多写几个测试”。例如先让它比较实现与现有测试覆盖，列出未覆盖行为，再让它按优先级补测试。这样更容易得到可审查、可合并的结果。</p> <p>可以借鉴的提问方式：</p> <ul> <li>为这个函数补充单元测试，覆盖边界条件和失败路径。</li> <li>阅读现有测试文件，找出还没有覆盖的重要场景。</li> <li>为这个排序工具生成 property-based test。</li> <li>扩展当前测试，覆盖空值、非法状态和异常依赖返回。</li> </ul> <h2 id="5-ti-gao-kai-fa-su-du-cong-jiao-shou-jia-dao-zui-hou-yi-gong-li">5. 提高开发速度：从脚手架到最后一公里</h2> <p>Codex 对开发速度的帮助，体现在开发周期的开头和结尾。</p> <p>在新功能刚开始时，工程师可以让 Codex 生成目录结构、基础模块、API stub、验证逻辑、日志骨架和初始测试，让项目快速进入“可运行”的状态。这样人可以更早验证接口和交互，而不是先手工搭一堆样板代码。</p> <p>在功能接近发布时，Codex 又可以处理一些小但必要的尾部任务，比如修复低优先级 bug、补齐遗漏逻辑、生成 rollout 脚本、添加 telemetry hook、补配置文件、整理迁移说明等。这些任务单个不大，但堆在一起会明显拖慢发布。</p> <p>OpenAI 文档还提到，工程师会把产品反馈或规格描述交给 Codex，让它生成初稿代码，之后再由人继续收敛。这个模式适合把模糊需求快速变成可讨论的实现雏形。</p> <p>可以借鉴的提问方式：</p> <ul> <li>根据这个规格创建一个初始实现，先保证主流程可运行。</li> <li>为 <code>POST /events</code> 增加 API 路由、基础校验和日志。</li> <li>参考现有 telemetry 模板，为新流程添加成功与失败事件。</li> <li>根据这段产品反馈生成一个 stub 实现，并列出需要人工确认的问题。</li> </ul> <h2 id="6-bao-chi-xin-liu-ba-sui-pian-ren-wu-jiao-gei-hou-tai-tui-jin">6. 保持心流：把碎片任务交给后台推进</h2> <p>工程工作经常被会议、on-call、即时消息和临时排障打断。Codex 在 OpenAI 内部的另一个价值，是帮助工程师保持主线注意力。</p> <p>当工程师发现一个顺手可修的小问题时，不一定要立刻切分支、切上下文、手动修复。可以把它作为一个 Codex 任务发出去，稍后再回来审查 PR。对于 Slack 讨论、Datadog trace、issue 片段、日志和临时笔记，也可以先交给 Codex 整理成计划、原型或后续任务。</p> <p>这并不意味着人不需要审查，而是把“发现任务”和“立刻中断当前工作”解耦。Codex 可以作为一个轻量任务暂存区，先保存上下文、推进初稿，等工程师回到这个问题时，已经有可读的分析或可运行的草稿。</p> <p>可以借鉴的提问方式：</p> <ul> <li>根据这段讨论整理一个可执行的重构计划。</li> <li>先补出重试逻辑的结构和 TODO，我稍后完善 backoff 策略。</li> <li>总结这个文件的职责和未完成点，方便我明天接着做。</li> <li>根据这条 issue 找到相关代码，并起草一个最小修复方案。</li> </ul> <h2 id="7-tan-suo-yu-fang-an-gou-si-kuo-zhan-she-ji-xuan-xiang">7. 探索与方案构思：扩展设计选项</h2> <p>Codex 不只用于确定性任务，也能参与开放式探索。OpenAI 团队会用它比较不同设计方案、验证假设、尝试陌生模式、寻找替代实现，或者把一个方案改写成更函数式、更事件驱动、更模块化的版本。</p> <p>这类工作适合让 Codex 先产生多个候选方向，再由工程师判断取舍。它可以帮助暴露权衡点，例如可维护性、性能、复杂度、迁移成本、失败恢复、测试难度和团队熟悉度。</p> <p>探索场景还包括查找相似 bug。修复一个已知问题后，可以让 Codex 扫描仓库里是否存在类似模式，例如手写 SQL、过时 API、重复权限判断、同类边界条件遗漏等。这样可以把一次 bug 修复扩展成一次更完整的清理。</p> <p>可以借鉴的提问方式：</p> <ul> <li>如果把这个系统从请求响应模型改成事件驱动，会影响哪些模块？</li> <li>找出仓库中手动拼 SQL 的位置，并按风险排序。</li> <li>把这段实现改成更函数式的风格，尽量减少副作用。</li> <li>我刚修了这个 bug，请找出代码库里可能存在的相似问题。</li> </ul> <h2 id="openai-zong-jie-de-zui-jia-shi-jian">OpenAI 总结的最佳实践</h2> <p>文档后半部分给出了 OpenAI 内部使用 Codex 的一些经验。它们共同指向一个原则：Codex 的输出质量高度依赖任务结构、上下文质量和迭代方式。</p> <h3 id="xian-yong-ask-mode-zai-jin-ru-code-mode">先用 Ask Mode，再进入 Code Mode</h3> <p>对于较大的改动，不要一开始就让 Codex 直接修改代码。更稳的方式是先让它在 Ask Mode 中产出实现计划，确认范围、风险和步骤后，再把计划作为后续 Code Mode 的输入。</p> <p>这种两阶段流程能让 Codex 更接地气，也能减少跑偏。尤其是跨文件重构、依赖迁移、测试补齐和性能优化，先计划再执行通常比直接开改更可靠。</p> <p>OpenAI 还给了一个很实用的任务规模判断：Codex 更适合处理边界清晰、人大约一小时可以完成、或几百行代码量级的任务。随着模型能力提升，这个规模会继续扩大，但当下仍然值得把任务切小、切清楚。</p> <h3 id="chi-xu-da-mo-codex-de-kai-fa-huan-jing">持续打磨 Codex 的开发环境</h3> <p>Codex 的环境配置会直接影响成功率。启动脚本、环境变量、构建依赖、网络访问、测试命令和本地服务配置越清楚，Codex 越不容易被环境错误卡住。</p> <p>更好的做法是把失败反馈反过来沉淀到环境中：如果 Codex 经常因为同一个构建错误、缺少依赖或命令不明确而失败，就修正启动脚本或仓库说明。这个过程需要几轮迭代，但长期收益很高。</p> <h3 id="xiang-xie-github-issue-yi-yang-xie-ti-shi-ci">像写 GitHub Issue 一样写提示词</h3> <p>OpenAI 建议把给 Codex 的提示写得像一个清晰的 GitHub Issue 或 PR 描述。也就是说，不只是写“帮我改一下”，而是给出：</p> <ul> <li>目标行为</li> <li>相关文件路径</li> <li>组件或模块名</li> <li>参考实现</li> <li>关键 diff 或日志</li> <li>文档片段</li> <li>验收标准</li> </ul> <p>尤其有效的写法是让 Codex 参考仓库中已有模式，例如“按某个模块里的实现方式处理当前模块”。这比抽象描述“写得更好”更容易得到符合项目风格的结果。</p> <h3 id="ba-codex-ren-wu-dui-lie-dang-zuo-qing-liang-backlog">把 Codex 任务队列当作轻量 backlog</h3> <p>Codex 任务不一定每次都要一次性变成完整 PR。它也可以用来捕捉临时想法、部分工作、顺手修复和探索任务。对工程师来说，这相当于一个可以后台推进的轻量 backlog。</p> <p>当你回到主线工作后，可以审查这些任务的结果，选择合并、继续迭代或丢弃。关键价值是减少上下文切换，同时不让细碎机会完全丢失。</p> <h3 id="yong-agents-md-ti-gong-chi-jiu-shang-xia-wen">用 AGENTS.md 提供持久上下文</h3> <p>文档特别提到，可以维护 <code>AGENTS.md</code> 文件来向 Codex 提供仓库级长期上下文。这类文件通常可以包含命名约定、业务规则、已知特殊情况、依赖说明、测试方式、禁止事项和模型无法从代码本身推断出的背景。</p> <p>对于团队项目来说，<code>AGENTS.md</code> 的价值类似“给 agent 的工程手册”。它能让不同任务复用同一套规则，减少每次提示词都要重复交代项目习惯。</p> <h3 id="shi-yong-best-of-n-bi-jiao-duo-ge-fang-an">使用 Best of N 比较多个方案</h3> <p>OpenAI 还建议在复杂任务中使用 Best of N：同时生成多个候选响应或实现方向，然后比较、挑选甚至组合不同版本的优点。</p> <p>这适合用于设计选择、复杂重构、性能优化和不确定性较高的问题。与其把第一次输出当作最终答案，不如把 Codex 当作方案生成器，再由工程师做评审和综合。</p> <h2 id="zhan-wang-codex-zheng-zai-cheng-wei-gong-cheng-liu-cheng-de-yi-bu-fen">展望：Codex 正在成为工程流程的一部分</h2> <p>OpenAI 在结尾强调，Codex 仍处于 research preview，但已经对内部软件开发方式产生了实际影响：它帮助团队更快推进工作、写出更好的代码，也让一些原本不会被优先处理的小任务有机会被完成。</p> <p>更重要的是，随着模型能力提升、Codex 更深入地融入开发工作流，它的角色会继续变化。未来的 Codex 可能不只是响应单次指令，而是更稳定地参与长期项目、跨工具协作、代码审查、测试维护、迁移执行和工程知识沉淀。</p> <p>对普通团队的启发也很明确：不要只把 Codex 当作“写代码工具”。更有效的用法，是把它放到完整工程链路里，让它参与理解、计划、修改、测试、排障、总结和后续清理。任务越结构化、上下文越清楚、反馈循环越短，Codex 的收益就越稳定。</p> Codex Goals 使用指南：为什么 `/goal` 比“继续做”更强 2026-05-19T10:00:00+00:00 2026-05-19T10:00:00+00:00 Unknown https://xaicontrol.com/blog/codex-goals-guide/ <figure class="content-image"> <img src="&#x2F;images&#x2F;codex.webp" alt="" decoding="async" loading="lazy" > </figure> <p>很多人用 Codex 做复杂任务时，都会不自觉地反复说几句话：</p> <ul> <li>继续做</li> <li>再试下一个可能的修复</li> <li>跑一遍 benchmark</li> <li>现在检查测试</li> <li>直到真的做完再停</li> </ul> <p>OpenAI 在官方文章 <strong><a rel="external" href="https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex">Using Goals in Codex</a></strong> 里，给这类需求提供了一个更正式的机制：<code>/goal</code>。</p> <p>它的核心思想不是“让 Codex 更自由”，而是<strong>给 Codex 一个持续存在、可检查、可暂停、可恢复的完成目标</strong>。这样它不需要每做一步都等你重新发号施令，而是可以沿着同一个目标继续推进，直到满足完成条件，或者明确碰到阻塞。</p> <div class="infobox"> 说明：本文根据 OpenAI 官方 cookbook 文章 <code>Using Goals in Codex</code> 与官方 Codex CLI 文档整理，检查日期为 <strong>2026-05-19</strong>。文中命令、版本与行为边界，均以当日官方文档为准。 </div> <hr /> <h2 id="xian-kan-jie-lun-1-fen-zhong-ban">先看结论（1 分钟版）</h2> <ol> <li><strong><code>/goal</code> 不是普通 prompt 的加强版</strong>，而是一种“持续有效的目标契约”。</li> <li><strong>它最适合“终点明确，但路径不确定”的任务</strong>，比如性能优化、 flaky test 排查、依赖迁移、复杂重构、研究复现。</li> <li><strong>官方文档显示 Goals 从 Codex <code>0.128.0</code> 开始可用</strong>。</li> <li><strong><code>/goal</code> 目前是实验性 CLI 功能</strong>，需要启用 <code>features.goals</code>。</li> <li><strong>一个强 Goal 至少要写清楚 6 件事</strong>：结果、验证方式、约束、边界、迭代策略、阻塞停止条件。</li> <li><strong>Goal 的“完成”必须靠证据判断</strong>，不是靠模型觉得“大概好了”。</li> </ol> <hr /> <h2 id="yi-goal-dao-di-shi-shen-me">一、Goal 到底是什么</h2> <p>OpenAI 在官方文章里给出的定义很明确：<strong>Goal 是 Codex 中的持久化目标</strong>，会让当前线程跨多个 turn 持续朝某个确定结果推进。</p> <p>可以把它理解成：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>不是“下一步做什么”</span></span> <span class="giallo-l"><span>而是“在什么条件成立之前，不要停”</span></span></code></pre> <p>普通 prompt 更像一次临时指令：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>修一下这个测试</span></span></code></pre> <p>而 Goal 更像一个可持续追踪的完成条件：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal 让 checkout 测试在当前分支通过，同时不改变公开 API 行为</span></span></code></pre> <p>这两者的区别，不只是字数长短，而是工作模式不同。</p> <hr /> <h2 id="er-goal-he-pu-tong-prompt-de-qu-bie">二、Goal 和普通 Prompt 的区别</h2> <p>OpenAI 官方文章把两者的差别概括得很直接：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Prompt: ask -&gt; work -&gt; result -&gt; wait</span></span> <span class="giallo-l"><span>Goal: work -&gt; check -&gt; continue or complete</span></span></code></pre> <p>也就是说：</p> <ul> <li><strong>普通 prompt</strong>：Codex 按当前指令做一轮，给你结果，然后停下等你下一句。</li> <li><strong>Goal</strong>：Codex 做完一轮之后，会回头检查“目标是否已经满足”；如果还没有，而且 Goal 仍处于激活状态、预算也没用完，它就可以继续推进。</li> </ul> <p>这也是为什么 <code>/goal</code> 特别适合下面这类任务：</p> <ul> <li>先跑测试，再决定下一步怎么修</li> <li>先跑 benchmark，再决定该改哪里</li> <li>先复现实验，再决定还能不能继续逼近结果</li> </ul> <p>因为这些任务的<strong>下一步动作，本来就取决于刚刚得到的证据</strong>。</p> <hr /> <h2 id="san-shen-me-shi-hou-gai-yong-goal">三、什么时候该用 <code>/goal</code></h2> <p>官方 cookbook 文章给出的判断标准很实用：</p> <p><strong>当任务的终点很明确，但达到终点的路径还不明确时，就适合用 Goal。</strong></p> <h3 id="gua-he-de-ren-wu">适合的任务</h3> <p>OpenAI 在文中举出的典型场景包括：</p> <ul> <li>性能优化</li> <li>flaky test 调查</li> <li>依赖迁移</li> <li>需要先复现再修的 bug 排查</li> <li>多步骤重构</li> <li>benchmark 驱动的调优</li> <li>需要最终产物的研究型任务</li> </ul> <h3 id="bu-gua-he-de-ren-wu">不适合的任务</h3> <p>如果只是一次性编辑，普通 prompt 往往更合适，比如：</p> <ul> <li>改一段文案</li> <li>补一个小注释</li> <li>解释某个函数</li> <li>改一个明确的小错误</li> </ul> <p>一句话区分：</p> <ul> <li><strong>一次做完就结束</strong>：用普通 prompt</li> <li><strong>需要“做一轮、检查、继续、再检查”</strong>：用 Goal</li> </ul> <hr /> <h2 id="si-zen-me-qi-yong-he-shi-yong-goal">四、怎么启用和使用 <code>/goal</code></h2> <p>根据 OpenAI 官方 CLI 文档，<code>/goal</code> 目前是<strong>实验性功能</strong>。 按当前官方文档表述，这个命令面主要是以 <strong>Codex CLI slash command</strong> 的形式介绍的，因此本文也主要按 CLI 使用方式来说明。</p> <h3 id="1-xian-que-ren-ban-ben">1. 先确认版本</h3> <p>官方 cookbook 页面说明：<strong>Goals 从 Codex <code>0.128.0</code> 开始可用。</strong></p> <p>如果你是 CLI 用户，先更新并检查版本：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">npm</span><span style="color: #9ECBFF;"> install</span><span style="color: #79B8FF;"> -g</span><span style="color: #9ECBFF;"> @openai/codex@latest</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #79B8FF;"> --version</span></span></code></pre> <p>或：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">brew</span><span style="color: #9ECBFF;"> update</span></span> <span class="giallo-l"><span style="color: #B392F0;">brew</span><span style="color: #9ECBFF;"> upgrade codex</span></span> <span class="giallo-l"><span style="color: #B392F0;">codex</span><span style="color: #79B8FF;"> --version</span></span></code></pre><h3 id="2-qi-yong-goals-gong-neng">2. 启用 goals 功能</h3> <p>官方 slash command 文档给出两种方式：</p> <ol> <li>在 Codex 里打开 <code>/experimental</code></li> <li>或者在 <code>config.toml</code> 中启用：</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>[</span><span style="color: #B392F0;">features</span><span>]</span></span> <span class="giallo-l"><span>goals =</span><span style="color: #79B8FF;"> true</span></span></code></pre><h3 id="3-ji-ben-ming-ling">3. 基本命令</h3> <p>官方文档里 <code>/goal</code> 的命令面很简单：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal &lt;objective&gt; 设置目标</span></span> <span class="giallo-l"><span>/goal 查看当前目标</span></span> <span class="giallo-l"><span>/goal pause 暂停目标</span></span> <span class="giallo-l"><span>/goal resume 恢复目标</span></span> <span class="giallo-l"><span>/goal clear 清除目标</span></span></code></pre> <p>例如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Reduce p95 latency below 120 ms without regressing correctness tests</span></span></code></pre> <p>另外，官方文档还给出两个边界：</p> <ul> <li>Goal 内容不能为空</li> <li>最长不超过 <code>4000</code> 个字符</li> </ul> <p>如果说明太长，官方建议把细节放进文件，再让 Goal 指向那个文件。</p> <hr /> <h2 id="wu-yi-ge-qiang-goal-ying-gai-zen-me-xie">五、一个强 Goal 应该怎么写</h2> <p>这是 OpenAI 那篇文章最有价值的部分。</p> <p>官方给出的结论是：<strong>一个好 Goal 不是更长的 prompt，而是一份紧凑的工作契约。</strong></p> <p>最强的 Goal，通常会定义 6 件事：</p> <ol> <li><strong>Outcome</strong>：完成时什么结果应该成立</li> <li><strong>Verification surface</strong>：用什么证据验证它真的完成了</li> <li><strong>Constraints</strong>：什么东西不能被破坏或退化</li> <li><strong>Boundaries</strong>：允许动哪些文件、工具、数据或资源</li> <li><strong>Iteration policy</strong>：每一轮之后，Codex 应该如何决定下一步</li> <li><strong>Blocked stop condition</strong>：什么情况下应该停止，并报告当前已经无路可走</li> </ol> <p>这 6 点非常关键，因为它们解决的是 AI 长任务最常见的三个问题：</p> <ul> <li>到底算不算做完</li> <li>能不能为了达到目标把别的东西搞坏</li> <li>如果做不下去了，应该怎么诚实停下来</li> </ul> <h3 id="yi-ge-ke-zhi-jie-tao-yong-de-goal-mo-ban">一个可直接套用的 Goal 模板</h3> <p>可以把官方思路翻成这种写法：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal &lt;最终结果&gt;，通过 &lt;具体证据&gt; 验证，同时保持 &lt;约束条件&gt; 不退化。</span></span> <span class="giallo-l"><span>只使用 &lt;允许的文件/工具/边界&gt;。</span></span> <span class="giallo-l"><span>每轮之后，根据 &lt;迭代策略&gt; 决定下一步。</span></span> <span class="giallo-l"><span>如果被阻塞或在当前限制下已无有效路径，停止并报告 &lt;已尝试路径&gt;、&lt;证据&gt;、&lt;阻塞点&gt; 和 &lt;下一步需要的输入&gt;。</span></span></code></pre> <hr /> <h2 id="liu-ba-ruo-goal-gai-cheng-qiang-goal">六、把弱 Goal 改成强 Goal</h2> <p>官方文章给了非常典型的对比。</p> <h3 id="ruo-xie-fa">弱写法</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Improve performance</span></span></code></pre> <p>问题很明显：</p> <ul> <li>没有明确指标</li> <li>没有验证方式</li> <li>没有约束条件</li> </ul> <p>Codex 就算把延迟从 180ms 降到 135ms，也不知道该不该停。</p> <h3 id="qiang-xie-fa">强写法</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Reduce p95 checkout latency below 120 ms on the checkout benchmark while keeping the correctness test suite green</span></span></code></pre> <p>这句立刻多了 3 个关键点：</p> <ul> <li><strong>结果</strong>：p95 低于 120ms</li> <li><strong>验证面</strong>：checkout benchmark</li> <li><strong>约束</strong>：正确性测试必须继续为绿</li> </ul> <p>如果再写得更完整一点，可以像官方示例那样补上迭代策略和阻塞条件：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Reduce p95 checkout latency below 120 ms, verified by the checkout benchmark, while keeping the correctness suite green. Use only the checkout service, benchmark fixtures, and related tests. Between iterations, record what changed, what the benchmark showed, and the next best experiment to try. If the benchmark cannot run or no valid paths remain, stop with the attempted paths, the evidence gathered, the blocker, and the next input needed.</span></span></code></pre> <p>这就不再是一句“继续优化”，而是一份真正可执行、可审计的目标说明。</p> <hr /> <h2 id="qi-goal-ji-huo-hou-codex-hui-fa-sheng-shen-me-bian-hua">七、Goal 激活后，Codex 会发生什么变化</h2> <p>OpenAI 官方文章总结为 3 点。</p> <h3 id="1-mu-biao-hui-chi-xu-ke-jian">1. 目标会持续可见</h3> <p>如果 Codex 跑了一轮测试但失败了，线程里仍然保留着原来的终点。</p> <p>也就是说，它不会因为中间出现一次失败，就丢掉目标本身。</p> <h3 id="2-kong-xian-xian-cheng-ke-yi-ji-xu-tui-jin">2. 空闲线程可以继续推进</h3> <p>Goal 激活后，Codex 不一定只做一轮。只要线程空闲、没有新的用户输入排队、也没有别的待处理工作，而且 Goal 仍处于激活状态并且没超预算，它就可以继续。</p> <p>这里很重要的一点是：<strong>官方设计是保守的，不是无限循环。</strong></p> <p>OpenAI 说明，Codex 只会在安全边界上考虑继续，比如：</p> <ul> <li>一个 turn 已经结束</li> <li>当前线程空闲</li> <li>没有待处理的新输入</li> <li>没有其他挂起工作</li> </ul> <h3 id="3-wan-cheng-bi-xu-kao-zheng-ju">3. 完成必须靠证据</h3> <p>这可能是整套机制里最重要的原则：</p> <p><strong>Goal 不应该因为模型觉得“差不多了”就结束。</strong></p> <p>它应该在检查过这些东西之后再判断是否完成：</p> <ul> <li>修改过的文件</li> <li>运行过的命令</li> <li>测试结果</li> <li>benchmark 输出</li> <li>生成的 artifact</li> <li>研究证据</li> </ul> <p>所以，Goal 的本质不是“自动继续”，而是<strong>带证据地持续推进</strong>。</p> <hr /> <h2 id="ba-goal-bu-shi-quan-ju-ji-yi-er-shi-xian-cheng-ji-qi-yue">八、Goal 不是全局记忆，而是线程级契约</h2> <p>OpenAI 在官方文章里特别强调了一点：</p> <p><strong>Goal 是持久化的线程状态，不是全局记忆，也不是项目级说明。</strong></p> <p>这意味着：</p> <ul> <li>它属于当前 thread</li> <li>它跟着当前线程里的上下文走</li> <li>它依赖这个线程已经看过的文件、跑过的命令、见过的日志和形成的推理链路</li> </ul> <p>这套设计很重要，因为它避免了一个常见误解：</p> <blockquote> <p>Goal 不是让 Codex “永远记住一件事”，而是让它在当前这条工作线程里，持续对齐同一个完成标准。</p> </blockquote> <p>所以更准确的理解是：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Goal = 当前线程内持续有效的完成契约</span></span></code></pre> <p>不是：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Goal = 全局长期记忆</span></span></code></pre> <hr /> <h2 id="jiu-pu-tong-yong-hu-zui-rong-yi-fan-de-4-ge-cuo-wu">九、普通用户最容易犯的 4 个错误</h2> <h3 id="1-ba-goal-xie-cheng-kou-hao">1. 把 Goal 写成口号</h3> <p>比如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Improve the system</span></span></code></pre> <p>这几乎没法验证，也没法决定什么时候停。</p> <h3 id="2-zhi-xie-jie-guo-bu-xie-yan-zheng-fang-fa">2. 只写结果，不写验证方法</h3> <p>如果你说“把性能搞好”，但不说看哪份 benchmark，Codex 很难知道完成条件。</p> <h3 id="3-bu-xie-yue-shu">3. 不写约束</h3> <p>比如只说“把测试修好”，却没说“不要改公开 API 行为”，那 Codex 可能会通过一种你并不接受的方式达成目标。</p> <h3 id="4-mei-you-blocked-stop-condition">4. 没有 blocked stop condition</h3> <p>很多人会写“继续做直到完成”，但不写“如果做不下去该怎么停”。</p> <p>这会导致两种坏结果：</p> <ul> <li>要么过早停下</li> <li>要么在没有新证据的情况下瞎转</li> </ul> <p>官方建议非常明确：<strong>Goal 应该定义“无可辩护路径时如何停止并汇报”。</strong></p> <hr /> <h2 id="shi-3-ge-gua-he-zhi-jie-chao-de-goal-chang-jing">十、3 个适合直接抄的 Goal 场景</h2> <h3 id="1-xing-neng-you-hua">1. 性能优化</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Reduce p95 latency below 120 ms on the checkout benchmark while keeping the correctness suite green</span></span></code></pre><h3 id="2-flaky-test-pai-cha">2. flaky test 排查</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Make the checkout test suite pass on the current branch without changing public API behavior. Verify with the current test suite and failure logs. Use only the checkout service, related tests, and local reproduction steps. If no defensible fix remains, stop with attempted fixes, evidence, blocker, and the next input needed.</span></span></code></pre><h3 id="3-wen-dang-chan-wu-sheng-cheng">3. 文档产物生成</h3> <p>官方文章里也举了一个很实用的文档型例子：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/goal Produce a docs page for Goals that explains the lifecycle, command surface, and two examples. Verify that the page builds locally and that all referenced commands match the current CLI behavior.</span></span></code></pre> <p>这类例子很能说明问题：</p> <p>Goal 并不只适合改代码。只要有：</p> <ul> <li>明确结果</li> <li>明确验证方式</li> <li>明确边界</li> </ul> <p>它也可以用于文档、报告、研究和其他复杂产物。</p> <hr /> <h2 id="shi-yi-ru-guo-ni-bu-hui-xie-goal-xian-rang-codex-bang-ni-qi-cao">十一、如果你不会写 Goal，先让 Codex 帮你起草</h2> <p>OpenAI 官方文章还给了一个很实用的方法：</p> <ol> <li>先用人话描述任务</li> <li>再让 Codex 帮你把它改写成强 Goal</li> </ol> <p>例如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Help me turn this into a strong `/goal`: I want Codex to keep working on this flaky checkout test until we either fix it with evidence or can clearly explain what is blocking progress.</span></span></code></pre> <p>这一步很适合普通用户，因为真正难的往往不是做事，而是<strong>把“什么叫完成”写清楚</strong>。</p> <p>让 Codex 先给你起草一版，再由你补强：</p> <ul> <li>success condition</li> <li>verification surface</li> <li>constraints</li> <li>blocked stop condition</li> </ul> <p>通常会比你一开始自己硬写更稳。</p> <hr /> <h2 id="zui-hou-yi-ju-hua-goal-bu-shi-rang-codex-geng-xiang-zi-dong-jia-shi-er-shi-geng-xiang-you-yan-shou-biao-zhun-de-zhi-xing-zhe">最后一句话：<code>/goal</code> 不是让 Codex 更像“自动驾驶”，而是更像“有验收标准的执行者”</h2> <p>如果只用一句话总结 OpenAI 这套设计，我会这样说：</p> <p><strong>普通 prompt 是让 Codex 做一步，Goal 是让 Codex 对着验收标准持续做下去。</strong></p> <p>真正让 <code>/goal</code> 变强的，不是“自动继续”这件事本身，而是下面这三个词：</p> <ul> <li>持续目标</li> <li>线程作用域</li> <li>证据完成</li> </ul> <p>只要你把这三件事理解清楚，<code>/goal</code> 就不再只是一个新命令，而会变成 Codex 做复杂长任务时最值得掌握的能力之一。</p> <p>相关链接：</p> <ul> <li>OpenAI 官方 cookbook：<a rel="external" href="https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex">https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex</a></li> <li>OpenAI 官方 CLI slash commands：<a rel="external" href="https://developers.openai.com/codex/cli/slash-commands">https://developers.openai.com/codex/cli/slash-commands</a></li> </ul> OpenAI Skills 是什么？普通用户也能看懂的上手指南 2026-05-19T08:00:00+00:00 2026-05-19T08:00:00+00:00 Unknown https://xaicontrol.com/blog/openai-skills-guide/ <figure class="content-image"> <img src="&#x2F;images&#x2F;codex.webp" alt="" decoding="async" loading="lazy" > </figure> <p>很多人第一次看到 <a rel="external" href="https://github.com/openai/skills">openai/skills</a> 时，会以为这只是一个给开发者看的“提示词仓库”。其实它更像是 <strong>给 Codex 预装能力包的地方</strong>：把一套反复要做的事情，连同说明、脚本、参考资料，一起打包成一个 <code>skill</code>，以后需要时直接调用。</p> <p>如果你平时会这样用 AI：</p> <ul> <li>每次都要重复解释同一类任务</li> <li>希望它按固定流程做事，而不是临场发挥</li> <li>想把“我常用的一套方法”保存下来，自己复用或团队共享</li> </ul> <p>那 <code>skills</code> 就值得了解。</p> <div class="infobox"> 说明：本文根据 OpenAI 官方 GitHub 仓库 <code>openai/skills</code> 和 OpenAI Codex 官方 <code>Skills</code> 文档整理，检查日期为 <strong>2026-05-19</strong>。检查时仓库中可见 <code>5</code> 个内置 <code>.system</code> 技能目录和 <code>38</code> 个 <code>.curated</code> 技能目录。 </div> <hr /> <h2 id="xian-kan-jie-lun-1-fen-zhong-ban">先看结论（1 分钟版）</h2> <ol> <li><strong>Skill 不是新模型</strong>，而是给 Codex 增加一套“专门做某件事的方法包”。</li> <li><strong>它比一次性 prompt 更稳</strong>，因为里面不只有文字说明，还能带脚本、参考文档和资源文件。</li> <li><strong>普通用户最常见的用法</strong> 是先安装现成 skill，再在聊天里点名调用。</li> <li><strong>Codex 既能显式使用 skill，也能自动匹配</strong>。你可以手动写 <code>$linear</code>，也可以让它根据任务自己判断。</li> <li><strong>内置 skill 会自动带上</strong>；更多现成技能可以用 <code>$skill-installer</code> 安装。</li> <li><strong>如果你想把自己的工作流长期保存下来</strong>，可以先做 skill；等需要分发给别人时，再打包成 plugin。</li> </ol> <hr /> <h2 id="yi-skill-dao-di-shi-shen-me">一、Skill 到底是什么</h2> <p>OpenAI 官方文档对 skill 的定义可以翻成一句人话：</p> <p><strong>把“怎么做一类事情”的经验，做成一个可复用的小工具包。</strong></p> <p>这个包里通常不止一段提示词，而是几样东西放在一起：</p> <ul> <li><code>SKILL.md</code>：核心说明书，告诉 Codex 什么时候该用它、具体怎么做</li> <li><code>scripts/</code>：可选脚本，用来执行更稳定的步骤</li> <li><code>references/</code>：可选参考资料，减少每次重新解释背景</li> <li><code>assets/</code>：可选模板、素材、资源文件</li> </ul> <p>最简单的结构大概长这样：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>my-skill/</span></span> <span class="giallo-l"><span> SKILL.md</span></span> <span class="giallo-l"><span> scripts/</span></span> <span class="giallo-l"><span> references/</span></span> <span class="giallo-l"><span> assets/</span></span></code></pre> <p>所以，<code>skill</code> 不是“更花哨的 prompt”，而是 <strong>把提示、流程、资料和执行动作放进同一个文件夹里</strong>。</p> <hr /> <h2 id="er-ta-he-pu-tong-prompt-plugin-you-shen-me-qu-bie">二、它和普通 Prompt、Plugin 有什么区别</h2> <p>这是很多人最容易混淆的地方。</p> <h3 id="1-prompt-yi-ci-xing-shuo-qing-chu">1. Prompt：一次性说清楚</h3> <p>普通 prompt 适合临时任务，比如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>帮我把这段话改得更口语一点</span></span></code></pre> <p>说完就结束，下次还得重新交代。</p> <h3 id="2-skill-ba-zhong-fu-liu-cheng-gu-ding-xia-lai">2. Skill：把重复流程固定下来</h3> <p>如果你经常做的是这类事：</p> <ul> <li>检查 PR 为什么 CI 失败</li> <li>把会议记录整理成周报</li> <li>读取 PDF 并检查排版</li> <li>在 Linear 里查、建、改 issue</li> </ul> <p>那更适合做成 skill。因为它能把步骤固定下来，下次不用重新教。</p> <h3 id="3-plugin-ba-skill-bian-cheng-ke-an-zhuang-bao">3. Plugin：把 skill 变成“可安装包”</h3> <p>OpenAI 官方文档里也讲得很明确：<strong>skill 是创作格式，plugin 是分发格式。</strong></p> <p>可以这样理解：</p> <ul> <li>你自己在本地折腾、打磨流程：先做 <code>skill</code></li> <li>你想给团队或多个项目安装复用：再打成 <code>plugin</code></li> </ul> <p>所以 <code>openai/skills</code> 仓库的重点是“能力模板”，而不是“应用商店”。</p> <hr /> <h2 id="san-pu-tong-yong-hu-zen-me-kai-shi-yong">三、普通用户怎么开始用</h2> <h3 id="di-yi-bu-xian-zhi-dao-ta-bu-shi-yin-cang-gong-neng">第一步：先知道它不是隐藏功能</h3> <p>根据 OpenAI 官方文档，skills 现在可用于：</p> <ul> <li>Codex CLI</li> <li>IDE 扩展</li> <li>Codex App</li> </ul> <p>也就是说，它不是只有命令行高手才能碰的东西。</p> <h3 id="di-er-bu-xian-yong-xian-cheng-skill-bu-bi-yi-kai-shi-zi-ji-xie">第二步：先用现成 skill，不必一开始自己写</h3> <p><code>openai/skills</code> 仓库里有两类现成内容：</p> <ul> <li><code>.system</code>：随 Codex 自带的内置技能</li> <li><code>.curated</code>：可额外安装的精选技能</li> </ul> <p>当前仓库里可见的内置技能包括：</p> <ul> <li><code>imagegen</code></li> <li><code>openai-docs</code></li> <li><code>plugin-creator</code></li> <li><code>skill-creator</code></li> <li><code>skill-installer</code></li> </ul> <p>如果你想安装一个精选 skill，官方推荐方式是直接在 Codex 里调用安装器。例如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>$skill-installer linear</span></span></code></pre> <p>也可以让它从别的 GitHub 目录安装 skill。安装完如果没立刻显示，官方建议重启 Codex。</p> <h3 id="di-san-bu-yong-liang-chong-fang-shi-diao-yong">第三步：用两种方式调用</h3> <p>OpenAI 官方文档给了两种触发方式：</p> <ol> <li><strong>显式调用</strong>：你在提示里直接点名 skill</li> <li><strong>隐式调用</strong>：Codex 根据任务描述自己判断要不要用</li> </ol> <p>显式调用最容易理解，比如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $pdf 帮我检查这份 PDF 有没有版面错位</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $linear 帮我把这个需求拆成 3 条 issue，并按优先级排序</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>用 $gh-fix-ci 看一下这个 PR 为什么 GitHub Actions 失败了</span></span></code></pre> <p>如果你不知道当前有哪些技能，通常可以先试：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>/skills</span></span></code></pre> <p>或者直接输入 <code>$</code>，从技能列表里选。</p> <hr /> <h2 id="si-zhe-ge-cang-ku-li-you-na-xie-xian-cheng-ji-neng">四、这个仓库里有哪些现成技能</h2> <p>截至本文检查时，<code>openai/skills</code> 仓库里的技能覆盖面已经相当广，不只是“写代码”。</p> <h3 id="1-kai-fa-yu-pai-zhang">1. 开发与排障</h3> <p>例如：</p> <ul> <li><code>gh-fix-ci</code>：排查 GitHub Actions 失败</li> <li><code>playwright</code>、<code>playwright-interactive</code>：做网页自动化和交互测试</li> <li><code>pdf</code>：读、审、生成 PDF</li> <li><code>security-threat-model</code>：做安全威胁建模</li> </ul> <p>这类 skill 的价值在于：它不是单纯说“去检查一下”，而是把检查顺序、工具和交付结果都规范化了。</p> <h3 id="2-xie-zuo-yu-xiang-mu-guan-li">2. 协作与项目管理</h3> <p>例如：</p> <ul> <li><code>linear</code></li> <li><code>sentry</code></li> <li><code>notion-knowledge-capture</code></li> <li><code>notion-meeting-intelligence</code></li> </ul> <p>这些技能说明一个趋势：Codex 不只是改代码，也开始进入“整理信息、追踪任务、管理流程”的工作区。</p> <h3 id="3-she-ji-yu-nei-rong-xiang-guan">3. 设计与内容相关</h3> <p>例如：</p> <ul> <li><code>figma</code></li> <li><code>figma-generate-design</code></li> <li><code>figma-implement-design</code></li> <li><code>screenshot</code></li> <li><code>transcribe</code></li> <li><code>speech</code></li> </ul> <p>这意味着 skill 的思路并不局限于程序员。只要一件事有相对固定的做法，就有机会被做成可复用技能。</p> <h3 id="4-bu-shu-yu-fa-bu">4. 部署与发布</h3> <p>例如：</p> <ul> <li><code>vercel-deploy</code></li> <li><code>netlify-deploy</code></li> <li><code>render-deploy</code></li> <li><code>cloudflare-deploy</code></li> </ul> <p>对很多团队来说，这类 skill 的意义不是“替你按按钮”，而是把常见发布步骤和检查项标准化。</p> <hr /> <h2 id="wu-wei-shen-me-pu-tong-yong-hu-ye-zhi-de-guan-xin">五、为什么普通用户也值得关心</h2> <p>如果你只是偶尔问 AI 一个问题，skills 当然不是刚需。</p> <p>但只要你进入下面这些场景，它就开始变得很有用：</p> <h3 id="1-ni-you-zhong-fu-gong-zuo">1. 你有重复工作</h3> <p>比如每周都要：</p> <ul> <li>写周报</li> <li>整理会议纪要</li> <li>检查文档格式</li> <li>审核发布前清单</li> </ul> <p>那 skill 的价值就是：<strong>以后不用再重复教 AI 做法。</strong></p> <h3 id="2-ni-xi-wang-jie-guo-geng-wen-ding">2. 你希望结果更稳定</h3> <p>很多人对 AI 最大的不满不是“不会做”，而是“每次做法不一样”。</p> <p>skill 的作用，就是把流程写死一点、边界讲清楚一点、需要时再配上脚本。这样输出会更像一个长期可复用的助手，而不是一次一变的聊天对象。</p> <h3 id="3-ni-xiang-ba-jing-yan-liu-xia-lai">3. 你想把经验留下来</h3> <p>很多团队内部都有这种隐形知识：</p> <ul> <li>新人怎么提 issue 更规范</li> <li>发版前要检查哪些项</li> <li>遇到线上报警先看什么</li> <li>写某类文档要遵循什么结构</li> </ul> <p>以前这些知识要么存在某个人脑子里，要么散落在群消息里。现在可以变成 skill。</p> <hr /> <h2 id="liu-zi-ji-zuo-yi-ge-skill-nan-bu-nan">六、自己做一个 Skill，难不难</h2> <p>没那么难，而且 OpenAI 官方已经把“从零新建”这件事做成了内置工具。</p> <p>如果你想自己创建 skill，官方推荐先用：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>$skill-creator</span></span></code></pre> <p>它会问你几件关键事情：</p> <ul> <li>这个 skill 是干什么的</li> <li>什么时候应该触发</li> <li>是纯说明就够，还是要带脚本</li> </ul> <p>如果你只想做一个最小版本，甚至一个 <code>SKILL.md</code> 就可以起步。比如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span style="color: #85E89D;">name</span><span>:</span><span style="color: #9ECBFF;"> weekly-report</span></span> <span class="giallo-l"><span style="color: #85E89D;">description</span><span>:</span><span style="color: #9ECBFF;"> Use when the user wants to turn rough meeting notes into a short weekly status update.</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Read the notes, group them into progress, risks, and next steps, then write a concise weekly report in Chinese.</span></span></code></pre> <p>保存位置也不复杂：</p> <ul> <li>只想自己跨项目使用：放到 <code>$HOME/.agents/skills</code></li> <li>只想给当前项目或团队使用：放到仓库里的 <code>.agents/skills</code></li> </ul> <p>这也是 skill 最实用的一点：<strong>先在本地把工作流跑顺，再考虑要不要产品化。</strong></p> <hr /> <h2 id="zui-hou-yi-ju-hua-xian-bie-ji-zhao-zi-ding-yi-yi-qie">最后一句话：先别急着“自定义一切”</h2> <p>对大多数普通用户来说，最合理的起步顺序是：</p> <ol> <li>先装一个离自己最近的现成 skill</li> <li>用几次，感受它和普通 prompt 的差别</li> <li>真有重复工作，再把自己的流程写成 skill</li> </ol> <p>如果只用一句话概括 <code>openai/skills</code>，我会这么说：</p> <p><strong>它想做的不是“再给你一个更聪明的模型”，而是让同一个模型，学会把常用工作长期、稳定地做下去。</strong></p> <p>相关链接：</p> <ul> <li>GitHub 仓库：<a rel="external" href="https://github.com/openai/skills">https://github.com/openai/skills</a></li> <li>OpenAI 官方文档：<a rel="external" href="https://developers.openai.com/codex/skills">https://developers.openai.com/codex/skills</a></li> </ul> XAI Router 启用 Codex App 插件 2026-05-10T00:00:00+00:00 2026-05-10T00:00:00+00:00 Unknown https://xaicontrol.com/blog/xai-router-codex-plugins-enable/ <figure class="content-image"> <img src="&#x2F;images&#x2F;codex-plugins&#x2F;directory.png" alt="" decoding="async" loading="lazy" > </figure> <p>不少用户在配置 Codex App 时，会遇到一个现象：模型请求已经可以通过 XAI Router 正常使用，但 Codex Apps / Plugins 页面仍然是灰色，无法打开插件目录。</p> <p>这个问题的关键不是“模型 API 有没有代理成功”，而是 <strong>Codex 插件页面需要官方 ChatGPT/Codex 登录态</strong>。最简单、最稳定的方式是：</p> <ol> <li>先用官方账号登录 Codex。</li> <li>再把模型请求配置到 XAI Router。</li> <li>不要把插件后台地址强行改到模型代理地址。</li> </ol> <p>这样既能正常打开插件页面，也能让日常模型请求继续走 XAI Router 的 Codex 套餐。</p> <hr /> <h2 id="xian-kan-jie-lun">先看结论</h2> <p>如果你只是普通用户，推荐使用下面这套方案：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Codex 插件页面：使用官方 Codex / ChatGPT 登录态</span></span> <span class="giallo-l"><span>Codex 模型请求：使用 XAI Router API</span></span></code></pre> <p>也就是说，登录和模型 API 是两件事：</p> <ul> <li><strong>官方登录态</strong>：用于解锁 Codex Apps、Plugins、远程插件目录等能力。</li> <li><strong>XAI Router API Key</strong>：用于实际模型调用、计费、路由和套餐额度。</li> </ul> <p>不要把这两件事混在同一个 <code>auth.json</code> 里。</p> <hr /> <h2 id="wei-shen-me-cha-jian-ye-mian-hui-bian-hui">为什么插件页面会变灰</h2> <p>Codex 的插件页面不是单纯看你有没有模型 API Key。它会检查当前 Codex 是否有官方 ChatGPT/Codex backend 登录态。</p> <p>如果你只配置了一个普通 API Key，例如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>sk-Xvs...</span></span></code></pre> <p>模型请求可以正常发出，但 Codex 客户端会认为你不是官方 ChatGPT/Codex backend 登录模式，于是 Apps / Plugins 页面可能会被禁用。</p> <p>这也是很多用户困惑的地方：</p> <blockquote> <p>明明 Codex 能回答、能改代码，为什么插件还是灰的？</p> </blockquote> <p>原因是：<strong>模型请求可用，不等于插件后台可用。</strong></p> <hr /> <h2 id="zheng-que-lian-lu-ying-gai-shi-shen-me">正确链路应该是什么</h2> <p>推荐链路如下：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>插件目录 / Apps 页面</span></span> <span class="giallo-l"><span>Codex App -&gt; 官方 ChatGPT backend</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>模型请求</span></span> <span class="giallo-l"><span>Codex App -&gt; XAI Router -&gt; 上游 Codex 模型服务</span></span></code></pre> <p>这样做的好处是：</p> <ol> <li>插件页面由官方登录态解锁，兼容性最好。</li> <li>模型调用继续走 XAI Router，不影响套餐额度和路由能力。</li> <li>不需要用户理解复杂的 backend-api 代理细节。</li> <li>不需要为了插件页面额外修改本地代理服务。</li> </ol> <hr /> <h2 id="di-yi-bu-xian-zai-codex-app-deng-lu-guan-fang-zhang-hao">第一步：先在 Codex App 登录官方账号</h2> <p>Codex App 的插件页面依赖 App 内的官方登录态。请在 Codex App 里退出当前登录方式，然后使用自己的官方 OpenAI / ChatGPT 账号重新登录。</p> <p>完成后，Codex App 会在本地保存官方登录状态，用于打开 Apps / Plugins 页面。</p> <p>注意：不要把 XAI Router Key 当成 Codex App 的登录凭证。也就是说，不要把 <code>sk-Xvs...</code> 写进 <code>~/.codex/auth.json</code>，否则 Codex 可能会进入 API Key auth 模式。模型请求可以用，但插件页面仍然可能无法打开。</p> <p>一句话记住：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Codex App 用官方账号登录，XAI Router Key 单独配置给模型 Provider。</span></span></code></pre> <hr /> <h2 id="di-er-bu-pei-zhi-xai-router-mo-xing-provider">第二步：配置 XAI Router 模型 Provider</h2> <p>打开或创建：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">~</span><span>/.codex/config.toml</span></span></code></pre> <p>推荐写法如下：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>model_provider =</span><span style="color: #9ECBFF;"> &quot;xai&quot;</span></span> <span class="giallo-l"><span>model =</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span></span> <span class="giallo-l"><span>model_reasoning_effort =</span><span style="color: #9ECBFF;"> &quot;xhigh&quot;</span></span> <span class="giallo-l"><span>plan_mode_reasoning_effort =</span><span style="color: #9ECBFF;"> &quot;xhigh&quot;</span></span> <span class="giallo-l"><span>model_reasoning_summary =</span><span style="color: #9ECBFF;"> &quot;none&quot;</span></span> <span class="giallo-l"><span>model_context_window =</span><span style="color: #79B8FF;"> 1050000</span></span> <span class="giallo-l"><span>model_auto_compact_token_limit =</span><span style="color: #79B8FF;"> 945000</span></span> <span class="giallo-l"><span>approval_policy =</span><span style="color: #9ECBFF;"> &quot;never&quot;</span></span> <span class="giallo-l"><span>sandbox_mode =</span><span style="color: #9ECBFF;"> &quot;danger-full-access&quot;</span></span> <span class="giallo-l"><span>service_tier =</span><span style="color: #9ECBFF;"> &quot;fast&quot;</span></span> <span class="giallo-l"><span>suppress_unstable_features_warning =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>cache_ttl =</span><span style="color: #9ECBFF;"> &quot;30m&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">model_providers</span><span>.</span><span style="color: #B392F0;">xai</span><span>]</span></span> <span class="giallo-l"><span>name =</span><span style="color: #9ECBFF;"> &quot;OpenAI&quot;</span></span> <span class="giallo-l"><span>base_url =</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com&quot;</span></span> <span class="giallo-l"><span>experimental_bearer_token =</span><span style="color: #9ECBFF;"> &quot;sk-Xvs...&quot;</span></span> <span class="giallo-l"><span>wire_api =</span><span style="color: #9ECBFF;"> &quot;responses&quot;</span></span> <span class="giallo-l"><span>requires_openai_auth =</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"><span>supports_websockets =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">features</span><span>]</span></span> <span class="giallo-l"><span>goals =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>multi_agent =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>remote_connections =</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>responses_websockets_v2 =</span><span style="color: #79B8FF;"> true</span></span></code></pre> <p>把 <code>sk-Xvs...</code> 替换成你在 XAI Router 后台复制的 API Key。完成后重新启动 Codex App。</p> <hr /> <h2 id="wei-shen-me-tui-jian-experimental-bearer-token">为什么推荐 experimental_bearer_token</h2> <p>对普通用户来说，<code>experimental_bearer_token</code> 的好处是配置最少：不用理解 shell、环境变量、<code>.zshrc</code>、<code>.bashrc</code>，也不用担心 Codex App 是否能读取终端环境变量。</p> <p>你只需要记住一件事：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Codex App 官方登录态放在 auth.json</span></span> <span class="giallo-l"><span>XAI Router Key 放在 config.toml 的 experimental_bearer_token</span></span></code></pre> <p>注意：<code>experimental_bearer_token</code> 会明文保存在 <code>~/.codex/config.toml</code>。请不要把这个文件上传到公开仓库，也不要截图公开完整 Key。</p> <hr /> <h2 id="chang-jian-wen-ti">常见问题</h2> <h3 id="1-wo-yi-jing-neng-yong-codex-xie-dai-ma-wei-shen-me-cha-jian-huan-shi-hui-de">1. 我已经能用 Codex 写代码，为什么插件还是灰的？</h3> <p>因为模型请求可用，只说明模型 API 可用。插件页面还需要官方 ChatGPT/Codex 登录态。</p> <p>如果你之前使用 API Key 方式登录过 Codex，Codex App 可能仍处于 API Key 认证模式。此时可以在 App 里主动退出，再用自己的官方 OpenAI / ChatGPT 账号登录。这样会让本地 <code>~/.codex/auth.json</code> 重新保存官方登录态，用于开启插件页面。</p> <p>如果官方账号提示默认模型额度不足，也不代表 XAI Router 不可用。只要本文的 Provider 配置生效，真正的模型请求仍然会走 XAI Router。</p> <h3 id="2-cha-jian-qing-qiu-hui-bu-hui-xiao-hao-xai-router-tao-can">2. 插件请求会不会消耗 XAI Router 套餐？</h3> <p>插件目录浏览、安装这类后台请求主要依赖官方登录态。真正调用模型、让 Codex 执行任务时，模型请求会按你的 XAI Router Provider 配置走 XAI Router。</p> <hr /> <h2 id="zui-hou-zai-zong-jie-yi-ci">最后再总结一次</h2> <p>如果你的目标是“Codex 插件能打开，同时模型请求走 XAI Router”，请按这个顺序做：</p> <ol> <li>登录自己的官方 OpenAI / ChatGPT 账号，保留官方登录态。</li> <li>在 <code>~/.codex/config.toml</code> 配置 XAI Router Provider，可以直接复制 XAI Router 后台提供的推荐配置。</li> </ol> <p>如果你还没有 XAI Router Codex 套餐，可以访问 <a rel="external" href="https://m.xairouter.com">m.xairouter.com</a> 注册账号并开通 Codex 套餐。开通后复制你的 API Key，按本文配置即可让 Codex 模型请求通过 XAI Router 使用。</p> GPT-5.5 与 GPT Image 2 图片生成 API 2026-04-25T10:30:00+00:00 2026-06-17T00:00:00+00:00 Unknown https://xaicontrol.com/blog/gpt-5-5-gpt-image-2-xai-router/ <figure class="content-image"> <img src="&#x2F;images&#x2F;gpt-5-5-gpt-image-2-cover.png" alt="" decoding="async" loading="lazy" > </figure> <p>GPT-5.5 不只适合处理文字、代码和复杂工具调用，也可以作为多模态工作流里的“调度模型”：由 <code>gpt-5.5</code> 理解用户意图，再通过 <code>image_generation</code> 工具调用图像模型生成图片。</p> <p>在 XAI Router 上，这个调用有两条 OpenAI 风格的入口：</p> <ul> <li><strong>Responses API</strong>：让 <code>gpt-5.5</code> 作为主模型，通过 <code>image_generation</code> 工具调用 <code>gpt-image-2</code>。</li> <li><strong>Images API</strong>：直接使用 OpenAI 官方兼容的 <code>/v1/images/generations</code> 和 <code>/v1/images/edits</code> 请求 <code>gpt-image-2</code>。</li> </ul> <p>核心组合是：</p> <ul> <li>主模型：<code>gpt-5.5</code></li> <li>工具：<code>image_generation</code></li> <li>图像模型：<code>gpt-image-2</code></li> <li>Images API：<code>/v1/images/generations</code>、<code>/v1/images/edits</code></li> <li>Base URL：<code>https://api.xairouter.com</code></li> <li>Key 环境变量：<code>XAI_API_KEY</code></li> </ul> <p>本文参考 OpenAI 官方图片生成工具和 Images API 示例，再把请求地址、鉴权环境变量和模型选择改成 XAI Router 版本。你可以把它理解成三层关系：</p> <table><thead><tr><th>层级</th><th>OpenAI 官方写法</th><th>XAI Router 写法</th></tr></thead><tbody> <tr><td>API Base URL</td><td><code>https://api.openai.com/v1</code></td><td><code>https://api.xairouter.com/v1</code></td></tr> <tr><td>API Key</td><td><code>OPENAI_API_KEY</code></td><td><code>XAI_API_KEY</code></td></tr> <tr><td>主模型</td><td><code>gpt-5.5</code></td><td><code>gpt-5.5</code></td></tr> <tr><td>图像工具</td><td><code>image_generation</code></td><td><code>image_generation</code></td></tr> <tr><td>图像模型</td><td>GPT Image 模型，例如 <code>gpt-image-2</code></td><td><code>gpt-image-2</code></td></tr> </tbody></table> <p>OpenAI 官方文档里的关键点是：<code>image_generation</code> 是 Responses API 的内置工具；工具调用结果会包含 base64 图片；<code>gpt-5.5</code> 支持这个工具；真正执行图像生成的是 GPT Image 模型，例如 <code>gpt-image-2</code>。如果你已经使用 OpenAI 官方 Images API，也可以直接把 <code>baseURL</code> 切到 XAI Router，继续调用 <code>/v1/images/generations</code> 或 <code>/v1/images/edits</code>。</p> <hr /> <h2 id="xai-router-shi-ce-tong-guo-neng-li">XAI Router 实测通过能力</h2> <p>以下结果基于 <strong>2026 年 4 月 25 日至 2026 年 5 月 1 日</strong>对 <code>https://api.xairouter.com</code> 的实测。接口能力会继续演进，生产系统仍建议保留超时、重试和失败记录。</p> <table><thead><tr><th>能力</th><th>实测结果</th><th>建议</th></tr></thead><tbody> <tr><td><code>/v1/models</code> 查询 <code>gpt-5.5</code>、<code>gpt-image-2</code></td><td>成功，均在模型列表中</td><td>可用于启动前探测</td></tr> <tr><td><code>/v1/responses</code> 文本调用 <code>gpt-5.5</code></td><td>成功，<code>status=completed</code></td><td>可作为基础连通性检查</td></tr> <tr><td><code>/v1/responses</code> + <code>image_generation</code> + <code>gpt-image-2</code> + <code>stream:true</code></td><td>成功，返回 <code>response.completed</code> 和图片 base64</td><td>推荐路径</td></tr> <tr><td><code>tool_choice: { type: "image_generation" }</code></td><td>成功，能强制走图像工具</td><td>适合固定“生成图片”按钮</td></tr> <tr><td><code>partial_images</code></td><td>成功，但请求 2 张 partial 时实际可能只返回 1 张</td><td>UI 不要假设 partial 数量固定</td></tr> <tr><td><code>quality:"high"</code> + <code>output_format:"png"</code></td><td>成功</td><td>可用于成稿质量控制</td></tr> <tr><td><code>/v1/responses</code> 非流式图片生成</td><td>本次成功返回完整图片</td><td>可用，但仍建议优先用 stream</td></tr> <tr><td><code>/v1/images/generations</code> + <code>gpt-image-2</code></td><td>成功，返回 OpenAI Images API 风格 JSON，包含 <code>data[0].b64_json</code></td><td>OpenAI SDK 兼容接入首选</td></tr> <tr><td><code>/v1/images/edits</code> + <code>gpt-image-2</code></td><td>成功，支持图片输入后编辑或参考图生成</td><td>用于改图、角色延续和参考图工作流</td></tr> <tr><td><code>3840x2160</code> / <code>2160x3840</code> 4K 输出</td><td>成功，解码后的 JPEG 文件尺寸分别确认为 <code>3840x2160</code> 和 <code>2160x3840</code></td><td>可用，但延迟和成本高于 1024 尺寸</td></tr> <tr><td><code>4096x4096</code></td><td>返回 HTTP 400，最长边不能超过 <code>3840</code></td><td>不要把 4K 理解成 <code>4096x4096</code></td></tr> </tbody></table> <p>因此，在 XAI Router 当前行为下有两个推荐路径：</p> <ul> <li>需要 <code>gpt-5.5</code> 理解用户需求、改写提示词或参与多步骤工作流：使用 <strong>Responses API + <code>stream:true</code> + <code>image_generation</code> 工具 + <code>gpt-image-2</code></strong>。</li> <li>已经接入 OpenAI 官方 Images API 或只需要生成/编辑单张图片：使用 <strong><code>/v1/images/generations</code> 或 <code>/v1/images/edits</code> + <code>model:"gpt-image-2"</code></strong>。</li> </ul> <hr /> <h2 id="liang-tiao-diao-yong-lu-jing-zen-me-xuan">两条调用路径怎么选</h2> <table><thead><tr><th>路径</th><th>Endpoint</th><th><code>model</code> 字段怎么写</th><th>适合场景</th></tr></thead><tbody> <tr><td>Responses API 工具调用</td><td><code>/v1/responses</code></td><td>主模型写 <code>gpt-5.5</code>，工具里写 <code>model:"gpt-image-2"</code></td><td>聊天式生成、多轮编辑、让主模型先理解或扩写提示词</td></tr> <tr><td>Images API 生成</td><td><code>/v1/images/generations</code></td><td>直接写 <code>model:"gpt-image-2"</code></td><td>OpenAI 官方 Images API 兼容、文本生成单张或多张图片</td></tr> <tr><td>Images API 编辑</td><td><code>/v1/images/edits</code></td><td>直接写 <code>model:"gpt-image-2"</code></td><td>上传图片后编辑、用参考图生成新图、局部修改</td></tr> </tbody></table> <p>如果你的客户端已经是 OpenAI SDK 的 <code>client.images.generate()</code> 或 <code>client.images.edit()</code>，通常只需要修改 <code>baseURL</code> 和 API Key。请求里的模型建议明确写 <code>gpt-image-2</code>。XAI Router 当前这组 Images API 以 <code>gpt-image-2</code> 为目标模型，不建议依赖 DALL·E 的旧参数语义。</p> <p><code>/v1/images/variations</code> 属于旧图像模型常见接口，不是 <code>gpt-image-2</code> 的推荐路径；对 <code>gpt-image-2</code>，重点使用 <code>generations</code> 和 <code>edits</code>。</p> <p>所有示例都使用：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> XAI_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;你的 XAI API Key&quot;</span></span></code></pre> <hr /> <h2 id="images-api-sheng-cheng-tu-pian">Images API：生成图片</h2> <p>这是最接近 OpenAI 官方 Images API 的写法。请求地址是 <code>https://api.xairouter.com/v1/images/generations</code>，返回值包含 <code>data[0].b64_json</code>。</p> <p>如果请求没有显式设置图片输出参数，XAI Router 当前 Images API 默认按 <code>quality:"medium"</code>、<code>output_format:"png"</code> 处理，并且不主动设置 <code>output_compression</code>。只有在你选择 <code>jpeg</code> 或 <code>webp</code> 时，才建议按需传 <code>output_compression</code>。</p> <h3 id="curl">cURL</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1/images/generations&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Authorization: Bearer </span><span>$XAI_API_KEY</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Content-Type: application/json&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39;{</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;model&quot;: &quot;gpt-image-2&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;prompt&quot;: &quot;Generate a polished square portrait of a professional XAI female AI assistant in a bright futuristic control room. No text, no logos, no watermark.&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;size&quot;: &quot;1024x1024&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;quality&quot;: &quot;high&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;output_format&quot;: &quot;png&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;response_format&quot;: &quot;b64_json&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &#39;.data[0].b64_json&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> xai-assistant.png</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">file</span><span style="color: #9ECBFF;"> xai-assistant.png</span></span></code></pre> <p>典型返回结构如下：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;created&quot;</span><span>:</span><span style="color: #79B8FF;"> 1777573692</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;data&quot;</span><span>: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;b64_json&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;...&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;revised_prompt&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;...&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;output_format&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;png&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;quality&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;high&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;size&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;usage&quot;</span><span>: {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;input_tokens&quot;</span><span>:</span><span style="color: #79B8FF;"> 123</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;output_tokens&quot;</span><span>:</span><span style="color: #79B8FF;"> 456</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;total_tokens&quot;</span><span>:</span><span style="color: #79B8FF;"> 579</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>对 <code>gpt-image-2</code>，建议把 <code>response_format</code> 固定为 <code>b64_json</code>。如果需要 URL，推荐在你的后端解码 base64 后上传到对象存储或 CDN，再把自有 URL 返回给前端。</p> <h3 id="node-js">Node.js</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> fs</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;node:fs&quot;</span><span>;</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> client</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>({</span></span> <span class="giallo-l"><span> apiKey: process.env.</span><span style="color: #79B8FF;">XAI_API_KEY</span><span>,</span></span> <span class="giallo-l"><span> baseURL:</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> result</span><span style="color: #F97583;"> = await</span><span> client.images.</span><span style="color: #B392F0;">generate</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span> prompt:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;Generate a polished square portrait of a professional XAI female AI assistant in a bright futuristic control room. No text, no logos, no watermark.&quot;</span><span>,</span></span> <span class="giallo-l"><span> size:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> quality:</span><span style="color: #9ECBFF;"> &quot;high&quot;</span><span>,</span></span> <span class="giallo-l"><span> output_format:</span><span style="color: #9ECBFF;"> &quot;png&quot;</span><span>,</span></span> <span class="giallo-l"><span> response_format:</span><span style="color: #9ECBFF;"> &quot;b64_json&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> imageBase64</span><span style="color: #F97583;"> =</span><span> result.data[</span><span style="color: #79B8FF;">0</span><span>].b64_json;</span></span> <span class="giallo-l"><span>fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">&quot;xai-assistant.png&quot;</span><span>, Buffer.</span><span style="color: #B392F0;">from</span><span>(imageBase64,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>));</span></span></code></pre><h3 id="python">Python</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">import</span><span> base64</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">from</span><span> openai</span><span style="color: #F97583;"> import</span><span> OpenAI</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>client</span><span style="color: #F97583;"> =</span><span> OpenAI(</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> api_key</span><span style="color: #F97583;">=</span><span>os.environ[</span><span style="color: #9ECBFF;">&quot;XAI_API_KEY&quot;</span><span>],</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> base_url</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>result</span><span style="color: #F97583;"> =</span><span> client.images.generate(</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> model</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> prompt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Generate a polished square portrait of a professional XAI female AI assistant in a bright futuristic control room. No text, no logos, no watermark.&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> size</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> quality</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;high&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> output_format</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;png&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> response_format</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;b64_json&quot;</span><span>,</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">with</span><span style="color: #79B8FF;"> open</span><span>(</span><span style="color: #9ECBFF;">&quot;xai-assistant.png&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;wb&quot;</span><span>)</span><span style="color: #F97583;"> as</span><span> f:</span></span> <span class="giallo-l"><span> f.write(base64.b64decode(result.data[</span><span style="color: #79B8FF;">0</span><span>].b64_json))</span></span></code></pre> <hr /> <h2 id="images-api-4k-tu-pian">Images API：4K 图片</h2> <p><code>gpt-image-2</code> 支持灵活尺寸，但 4K 要按官方约束理解：</p> <ul> <li>4K 横图：<code>3840x2160</code></li> <li>4K 竖图：<code>2160x3840</code></li> <li>最大边不超过 <code>3840</code></li> <li>两条边都必须是 <code>16px</code> 的倍数</li> <li>长边和短边比例不超过 <code>3:1</code></li> <li>总像素必须在 <code>655,360</code> 到 <code>8,294,400</code> 之间</li> </ul> <p>超过 <code>2560x1440</code> 总像素的输出属于高分辨率/实验性范围，建议先用低或中等质量确认构图，再切到 4K 和更高质量。</p> <p>实测 <code>3840x2160</code> 和 <code>2160x3840</code> 都能生成，<code>4096x4096</code> 会被拒绝：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;error&quot;</span><span>: {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;message&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;Invalid size &#39;4096x4096&#39;. The longest edge must be less than or equal to 3840.&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;type&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;image_generation_user_error&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;param&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;tools&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;code&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;invalid_value&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>4K 生成耗时更长，建议先用 <code>quality:"low"</code> 或 <code>quality:"medium"</code> 做草稿，确认画面方向后再提高质量。</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1/images/generations&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Authorization: Bearer </span><span>$XAI_API_KEY</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Content-Type: application/json&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39;{</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;model&quot;: &quot;gpt-image-2&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;prompt&quot;: &quot;Generate a clean 4K landscape image of a professional XAI female AI assistant in a bright futuristic command center. No text, no logos, no watermark.&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;size&quot;: &quot;3840x2160&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;quality&quot;: &quot;low&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;output_format&quot;: &quot;jpeg&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;response_format&quot;: &quot;b64_json&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &#39;.data[0].b64_json&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> xai-4k-landscape.jpg</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">file</span><span style="color: #9ECBFF;"> xai-4k-landscape.jpg</span></span></code></pre> <p>竖图只需要把 <code>size</code> 改为 <code>2160x3840</code>。</p> <hr /> <h2 id="images-api-bian-ji-tu-pian">Images API：编辑图片</h2> <p>编辑接口使用 <code>/v1/images/edits</code>。OpenAI 官方 SDK 和 cURL 通常会发送 <code>multipart/form-data</code>，适合上传本地文件；XAI Router 会把输入图片传给 <code>gpt-image-2</code> 做编辑或作为参考图生成新图。</p> <p>对 <code>gpt-image-2</code>，不要传 <code>input_fidelity</code>。这个模型会自动以高保真方式处理输入图片，接口不允许再手动切换 fidelity。</p> <h3 id="curl-dan-tu-bian-ji">cURL 单图编辑</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1/images/edits&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Authorization: Bearer </span><span>$XAI_API_KEY</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;model=gpt-image-2&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;image=@source.png&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;prompt=Keep the same assistant identity and pose, but make the lighting brighter and add subtle floating interface panels. No text, no logos, no watermark.&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;size=1024x1024&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;quality=high&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;output_format=png&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;response_format=b64_json&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &#39;.data[0].b64_json&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> xai-assistant-edited.png</span></span></code></pre><h3 id="curl-duo-can-kao-tu">cURL 多参考图</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1/images/edits&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Authorization: Bearer </span><span>$XAI_API_KEY</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;model=gpt-image-2&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;image[]=@portrait.png&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;image[]=@style-reference.png&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;prompt=Create a new XAI assistant portrait using the first image as identity reference and the second image as lighting and color reference. No text, no logos, no watermark.&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;size=1024x1024&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;quality=high&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;output_format=png&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -F</span><span style="color: #9ECBFF;"> &quot;response_format=b64_json&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &#39;.data[0].b64_json&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> xai-assistant-reference-edit.png</span></span></code></pre><h3 id="node-js-bian-ji">Node.js 编辑</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> fs</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;node:fs&quot;</span><span>;</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI, { toFile }</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> client</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>({</span></span> <span class="giallo-l"><span> apiKey: process.env.</span><span style="color: #79B8FF;">XAI_API_KEY</span><span>,</span></span> <span class="giallo-l"><span> baseURL:</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> source</span><span style="color: #F97583;"> = await</span><span style="color: #B392F0;"> toFile</span><span>(fs.</span><span style="color: #B392F0;">createReadStream</span><span>(</span><span style="color: #9ECBFF;">&quot;source.png&quot;</span><span>),</span><span style="color: #9ECBFF;"> &quot;source.png&quot;</span><span>, {</span></span> <span class="giallo-l"><span> type:</span><span style="color: #9ECBFF;"> &quot;image/png&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> result</span><span style="color: #F97583;"> = await</span><span> client.images.</span><span style="color: #B392F0;">edit</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span> image: source,</span></span> <span class="giallo-l"><span> prompt:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;Keep the same assistant identity and pose, but make the lighting brighter and add subtle floating interface panels. No text, no logos, no watermark.&quot;</span><span>,</span></span> <span class="giallo-l"><span> size:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> quality:</span><span style="color: #9ECBFF;"> &quot;high&quot;</span><span>,</span></span> <span class="giallo-l"><span> output_format:</span><span style="color: #9ECBFF;"> &quot;png&quot;</span><span>,</span></span> <span class="giallo-l"><span> response_format:</span><span style="color: #9ECBFF;"> &quot;b64_json&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;xai-assistant-edited.png&quot;</span><span>,</span></span> <span class="giallo-l"><span> Buffer.</span><span style="color: #B392F0;">from</span><span>(result.data[</span><span style="color: #79B8FF;">0</span><span>].b64_json,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>),</span></span> <span class="giallo-l"><span>);</span></span></code></pre><h3 id="python-bian-ji">Python 编辑</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">import</span><span> base64</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">from</span><span> openai</span><span style="color: #F97583;"> import</span><span> OpenAI</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>client</span><span style="color: #F97583;"> =</span><span> OpenAI(</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> api_key</span><span style="color: #F97583;">=</span><span>os.environ[</span><span style="color: #9ECBFF;">&quot;XAI_API_KEY&quot;</span><span>],</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> base_url</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">with</span><span style="color: #79B8FF;"> open</span><span>(</span><span style="color: #9ECBFF;">&quot;source.png&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;rb&quot;</span><span>)</span><span style="color: #F97583;"> as</span><span> image:</span></span> <span class="giallo-l"><span> result</span><span style="color: #F97583;"> =</span><span> client.images.edit(</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> model</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> image</span><span style="color: #F97583;">=</span><span>image,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> prompt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Keep the same assistant identity and pose, but make the lighting brighter and add subtle floating interface panels. No text, no logos, no watermark.&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> size</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> quality</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;high&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> output_format</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;png&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> response_format</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;b64_json&quot;</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">with</span><span style="color: #79B8FF;"> open</span><span>(</span><span style="color: #9ECBFF;">&quot;xai-assistant-edited.png&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;wb&quot;</span><span>)</span><span style="color: #F97583;"> as</span><span> f:</span></span> <span class="giallo-l"><span> f.write(base64.b64decode(result.data[</span><span style="color: #79B8FF;">0</span><span>].b64_json))</span></span></code></pre> <p>如果需要局部编辑，可以传 <code>mask</code>。使用 mask 时，mask 应与第一张输入图尺寸一致，并包含 alpha 通道；实际效果仍建议通过提示词明确说明要替换或保留的区域。</p> <hr /> <h2 id="images-api-liu-shi-sheng-cheng-he-partial-images">Images API：流式生成和 partial images</h2> <p>直接调用 Images API 也可以使用 <code>stream:true</code> 和 <code>partial_images</code>。这条路径返回的是 Images API 风格事件：</p> <ul> <li><code>image_generation.partial_image</code>：中间图，<code>data.b64_json</code> 是 partial 图片。</li> <li><code>image_generation.completed</code>：最终图，<code>data.b64_json</code> 是最终图片。</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> fs</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;node:fs&quot;</span><span>;</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> client</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>({</span></span> <span class="giallo-l"><span> apiKey: process.env.</span><span style="color: #79B8FF;">XAI_API_KEY</span><span>,</span></span> <span class="giallo-l"><span> baseURL:</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> stream</span><span style="color: #F97583;"> = await</span><span> client.images.</span><span style="color: #B392F0;">generate</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span> prompt:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;Draw a polished XAI assistant in a bright futuristic control room. No text, no logos, no watermark.&quot;</span><span>,</span></span> <span class="giallo-l"><span> size:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> quality:</span><span style="color: #9ECBFF;"> &quot;medium&quot;</span><span>,</span></span> <span class="giallo-l"><span> output_format:</span><span style="color: #9ECBFF;"> &quot;png&quot;</span><span>,</span></span> <span class="giallo-l"><span> response_format:</span><span style="color: #9ECBFF;"> &quot;b64_json&quot;</span><span>,</span></span> <span class="giallo-l"><span> stream:</span><span style="color: #79B8FF;"> true</span><span>,</span></span> <span class="giallo-l"><span> partial_images:</span><span style="color: #79B8FF;"> 2</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">for await</span><span> (</span><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> event</span><span style="color: #F97583;"> of</span><span> stream) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (event.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;image_generation.partial_image&quot;</span><span>) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> const</span><span style="color: #79B8FF;"> index</span><span style="color: #F97583;"> =</span><span> event.partial_image_index</span><span style="color: #F97583;"> ??</span><span style="color: #79B8FF;"> 0</span><span>;</span></span> <span class="giallo-l"><span> fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">`partial-${</span><span>index</span><span style="color: #9ECBFF;">}.png`</span><span>, Buffer.</span><span style="color: #B392F0;">from</span><span>(event.b64_json,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (event.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;image_generation.completed&quot;</span><span>) {</span></span> <span class="giallo-l"><span> fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">&quot;final.png&quot;</span><span>, Buffer.</span><span style="color: #B392F0;">from</span><span>(event.b64_json,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>partial_images</code> 可以请求 <code>0</code> 到 <code>3</code> 张中间图，但实际返回数量不保证固定。如果最终图生成很快，可能少于请求数量。</p> <hr /> <h2 id="responses-api-zui-xiao-qing-qiu-ti">Responses API：最小请求体</h2> <p>如果你只想先确认接口能跑，最小请求体可以这样写：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;model&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;input&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;Generate an elegant image of a glass AI studio with soft light.&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;tools&quot;</span><span>: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;type&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;model&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;size&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;stream&quot;</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>这里的 <code>model: "gpt-5.5"</code> 是 Responses API 的主模型。<code>tools</code> 里的 <code>image_generation</code> 负责生成图像，并把图像模型指定为 <code>gpt-image-2</code>。</p> <p>在实际使用中，建议保留 <code>stream: true</code>。流式响应会把生成进度和最终图片结果直接推回来，便于在脚本里拿到 base64 并落盘。</p> <hr /> <h2 id="responses-api-guan-fang-shi-li-gai-cheng-xai-router">Responses API：官方示例改成 XAI Router</h2> <p>OpenAI 官方 JavaScript 示例大致是：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> openai</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> response</span><span style="color: #F97583;"> = await</span><span> openai.responses.</span><span style="color: #B392F0;">create</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span> input:</span><span style="color: #9ECBFF;"> &quot;Generate an image of a premium AI workspace&quot;</span><span>,</span></span> <span class="giallo-l"><span> tools: [{ type:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span> }],</span></span> <span class="giallo-l"><span>});</span></span></code></pre> <p>改成 XAI Router 时，主要改两处：</p> <ol> <li><code>apiKey</code> 从 <code>process.env.XAI_API_KEY</code> 读取。</li> <li><code>baseURL</code> 改成 <code>https://api.xairouter.com/v1</code>。</li> </ol> <p>同时，如果你希望明确使用 <code>gpt-image-2</code>，可以在 <code>image_generation</code> 工具里指定 <code>model</code>：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> fs</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;node:fs&quot;</span><span>;</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> client</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>({</span></span> <span class="giallo-l"><span> apiKey: process.env.</span><span style="color: #79B8FF;">XAI_API_KEY</span><span>,</span></span> <span class="giallo-l"><span> baseURL:</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> response</span><span style="color: #F97583;"> = await</span><span> client.responses.</span><span style="color: #B392F0;">create</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span> input:</span><span style="color: #9ECBFF;"> &quot;Generate an elegant image of a glass AI studio with soft light.&quot;</span><span>,</span></span> <span class="giallo-l"><span> tools: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> type:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span> size:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> imageData</span><span style="color: #F97583;"> =</span><span> response.output</span></span> <span class="giallo-l"><span> .</span><span style="color: #B392F0;">filter</span><span>((</span><span style="color: #FFAB70;">output</span><span>)</span><span style="color: #F97583;"> =&gt;</span><span> output.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;image_generation_call&quot;</span><span>)</span></span> <span class="giallo-l"><span> .</span><span style="color: #B392F0;">map</span><span>((</span><span style="color: #FFAB70;">output</span><span>)</span><span style="color: #F97583;"> =&gt;</span><span> output.result);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> (imageData.</span><span style="color: #79B8FF;">length</span><span style="color: #F97583;"> &gt;</span><span style="color: #79B8FF;"> 0</span><span>) {</span></span> <span class="giallo-l"><span> fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">&quot;xai-image.png&quot;</span><span>, Buffer.</span><span style="color: #B392F0;">from</span><span>(imageData[</span><span style="color: #79B8FF;">0</span><span>],</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>));</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>这就是最接近官方文档的改法。它适合普通同步调用；如果图片生成耗时较长，建议改用下面的流式版本。</p> <hr /> <h2 id="curl-sheng-cheng-bing-bao-cun-wei-png">cURL：生成并保存为 PNG</h2> <p>先设置 API Key：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> XAI_API_KEY</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;你的 XAI API Key&quot;</span></span></code></pre> <p>下面这个脚本会调用 <code>gpt-5.5</code>，让它通过 <code>image_generation</code> 工具使用 <code>gpt-image-2</code> 生成图片，并把最终 base64 解码为 <code>xai-generated-image.png</code>。</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>out</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;xai-generated-image.png&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>prompt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;Create an elegant technical cover image: a refined glass AI studio, a luminous prompt console, and a generated image appearing as a softly glowing framed visual. No words, no logos, no watermark.&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>body</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">jq</span><span style="color: #79B8FF;"> -nc --arg</span><span style="color: #9ECBFF;"> prompt &quot;</span><span>$prompt</span><span style="color: #9ECBFF;">&quot; &#39;{</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> model: &quot;gpt-5.5&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> input: $prompt,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> tools: [</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> type: &quot;image_generation&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> model: &quot;gpt-image-2&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> size: &quot;1024x1024&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ],</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> stream: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>sse</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span>b64</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">trap</span><span style="color: #9ECBFF;"> &#39;rm -f &quot;$sse&quot; &quot;$b64&quot;&#39; EXIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS -N --max-time 300</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1/responses&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Authorization: Bearer </span><span>$XAI_API_KEY</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -H</span><span style="color: #9ECBFF;"> &quot;Content-Type: application/json&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --data-binary</span><span style="color: #9ECBFF;"> &quot;</span><span>$body</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$sse</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">awk</span><span style="color: #9ECBFF;"> &#39;/^data: /{</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> data=$0</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> sub(/^data: /, &quot;&quot;, data)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> if (data != &quot;[DONE]&quot;) print data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}&#39; &quot;</span><span>$sse</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span></span> <span class="giallo-l"><span style="color: #F97583;">while</span><span style="color: #9ECBFF;"> IFS</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;"> read</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> json</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #B392F0;"> jq</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &#39;(.item.result? // .result? // empty)&#39;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> &lt;&lt;&lt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$json</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">done |</span></span> <span class="giallo-l"><span style="color: #B392F0;">awk</span><span style="color: #9ECBFF;"> &#39;length($0) &gt; max {max=length($0); best=$0} END {if (max &gt; 0) print best}&#39;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$b64</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [</span><span style="color: #F97583;"> ! -s</span><span style="color: #9ECBFF;"> &quot;</span><span>$b64</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;No image result found.&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &quot;</span><span>$b64</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$out</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">file</span><span style="color: #9ECBFF;"> &quot;</span><span>$out</span><span style="color: #9ECBFF;">&quot;</span></span></code></pre> <p>成功时，你会看到类似输出：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>xai-generated-image.png: PNG image data, 1024 x 1024, 8-bit/color RGB, non-interlaced</span></span></code></pre> <p>这段脚本做了三件事：</p> <ol> <li>用 <code>jq</code> 组装 JSON 请求体，避免 shell 引号把长提示词弄坏。</li> <li>用 <code>curl -N</code> 接收 Server-Sent Events 流式响应。</li> <li>从事件里的 <code>image_generation_call.result</code> 提取最长的 base64 字符串并解码成 PNG。</li> </ol> <p>如果你希望看到中间进度，可以在解析 SSE 时打印 <code>event:</code> 行。常见事件包括：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>response.created</span></span> <span class="giallo-l"><span>response.in_progress</span></span> <span class="giallo-l"><span>response.output_item.added</span></span> <span class="giallo-l"><span>response.image_generation_call.generating</span></span> <span class="giallo-l"><span>response.output_item.done</span></span> <span class="giallo-l"><span>response.completed</span></span></code></pre> <hr /> <h2 id="responses-api-node-js-shi-li">Responses API：Node.js 示例</h2> <p>如果你在 Node.js 项目里使用 OpenAI SDK，可以把 <code>baseURL</code> 指向 XAI Router：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">import</span><span> fs</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;node:fs&quot;</span><span>;</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> OpenAI</span><span style="color: #F97583;"> from</span><span style="color: #9ECBFF;"> &quot;openai&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> client</span><span style="color: #F97583;"> = new</span><span style="color: #B392F0;"> OpenAI</span><span>({</span></span> <span class="giallo-l"><span> apiKey: process.env.</span><span style="color: #79B8FF;">XAI_API_KEY</span><span>,</span></span> <span class="giallo-l"><span> baseURL:</span><span style="color: #9ECBFF;"> &quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> stream</span><span style="color: #F97583;"> = await</span><span> client.responses.</span><span style="color: #B392F0;">create</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span> input:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;Create an elegant technical cover image: a refined glass AI studio, a luminous prompt console, and a generated image appearing as a softly glowing framed visual. No words.&quot;</span><span>,</span></span> <span class="giallo-l"><span> tools: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> type:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span> size:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> stream:</span><span style="color: #79B8FF;"> true</span><span>,</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> imageBase64</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">for await</span><span> (</span><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> event</span><span style="color: #F97583;"> of</span><span> stream) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (event.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;response.output_item.done&quot;</span><span>) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> const</span><span style="color: #79B8FF;"> item</span><span style="color: #F97583;"> =</span><span> event.item;</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (item?.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;image_generation_call&quot;</span><span style="color: #F97583;"> &amp;&amp;</span><span> item.result) {</span></span> <span class="giallo-l"><span> imageBase64</span><span style="color: #F97583;"> =</span><span> item.result;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> (</span><span style="color: #F97583;">!</span><span>imageBase64) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> throw new</span><span style="color: #B392F0;"> Error</span><span>(</span><span style="color: #9ECBFF;">&quot;No image result returned&quot;</span><span>);</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">&quot;xai-generated-image.png&quot;</span><span>, Buffer.</span><span style="color: #B392F0;">from</span><span>(imageBase64,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>));</span></span></code></pre> <p>这个版本的重点是监听 <code>response.output_item.done</code>。当 <code>item.type</code> 是 <code>image_generation_call</code> 时，<code>item.result</code> 通常就是最终图片的 base64 内容。</p> <hr /> <h2 id="responses-api-python-shi-li">Responses API：Python 示例</h2> <p>Python 版本同样只需要把客户端指向 XAI Router：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">import</span><span> base64</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">from</span><span> openai</span><span style="color: #F97583;"> import</span><span> OpenAI</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>client</span><span style="color: #F97583;"> =</span><span> OpenAI(</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> api_key</span><span style="color: #F97583;">=</span><span>os.environ[</span><span style="color: #9ECBFF;">&quot;XAI_API_KEY&quot;</span><span>],</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> base_url</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;https://api.xairouter.com/v1&quot;</span><span>,</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>response</span><span style="color: #F97583;"> =</span><span> client.responses.create(</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> model</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> input</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Generate an elegant image of a glass AI studio with soft light.&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> tools</span><span style="color: #F97583;">=</span><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;type&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;model&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;size&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>image_data</span><span style="color: #F97583;"> =</span><span> [</span></span> <span class="giallo-l"><span> output.result</span></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> output</span><span style="color: #F97583;"> in</span><span> response.output</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> output.type</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;image_generation_call&quot;</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> image_data:</span></span> <span class="giallo-l"><span style="color: #F97583;"> with</span><span style="color: #79B8FF;"> open</span><span>(</span><span style="color: #9ECBFF;">&quot;xai-generated-image.png&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;wb&quot;</span><span>)</span><span style="color: #F97583;"> as</span><span> f:</span></span> <span class="giallo-l"><span> f.write(base64.b64decode(image_data[</span><span style="color: #79B8FF;">0</span><span>]))</span></span></code></pre> <p>如果你要做 Web 服务，建议把保存逻辑换成对象存储上传，例如 S3、R2、OSS 或你自己的 CDN。数据库里只保存图片 URL、提示词、模型、尺寸和生成状态，不要把大段 base64 直接塞进业务表。</p> <hr /> <h2 id="responses-api-qiang-zhi-diao-yong-tu-xiang-gong-ju">Responses API：强制调用图像工具</h2> <p>默认情况下，主模型会根据用户输入决定是否调用工具。大多数“请生成一张图片”的请求都会触发 <code>image_generation</code>，但如果你的产品按钮就是“生成图片”，可以用 <code>tool_choice</code> 强制调用：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;model&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;input&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;Draw an elegant AI product cover image.&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;tools&quot;</span><span>: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;type&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;model&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;size&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;tool_choice&quot;</span><span>: {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;type&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>这个写法适合后台任务、批量生成和固定按钮触发的工作流。聊天场景可以不加，让模型自己判断什么时候需要生成图片。</p> <hr /> <h2 id="responses-api-chang-yong-gong-ju-xuan-xiang">Responses API：常用工具选项</h2> <p><code>image_generation</code> 工具除了 <code>model</code> 之外，还可以设置一些输出参数。实际支持情况以 XAI Router 当前模型能力为准，但接口形态可以按 OpenAI 官方风格组织：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;type&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;model&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;size&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;quality&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;high&quot;</span><span>,</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> &quot;output_format&quot;</span><span>:</span><span style="color: #9ECBFF;"> &quot;png&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>常见选项可以这样理解：</p> <table><thead><tr><th>参数</th><th>用途</th><th>建议</th></tr></thead><tbody> <tr><td><code>size</code></td><td>输出尺寸</td><td>头像和封面先用 <code>1024x1024</code>；4K 横图用 <code>3840x2160</code>，竖图用 <code>2160x3840</code></td></tr> <tr><td><code>quality</code></td><td>渲染质量</td><td>默认按 <code>medium</code>；预览可用 <code>low</code>，成稿可用 <code>high</code></td></tr> <tr><td><code>output_format</code></td><td>输出格式</td><td>默认按 <code>png</code>；需要无损后处理用 <code>png</code>，网页大图可考虑 <code>webp</code> 或 <code>jpeg</code></td></tr> <tr><td><code>output_compression</code></td><td>压缩级别</td><td>默认不主动设置；只在 JPEG/WebP 场景按需设置</td></tr> <tr><td><code>background</code></td><td>背景</td><td><code>gpt-image-2</code> 不支持 <code>background:"transparent"</code></td></tr> <tr><td><code>action</code></td><td>生成或编辑</td><td>新图用 <code>generate</code>，多轮上下文可保留 <code>auto</code></td></tr> </tbody></table> <p>如果你需要透明图，建议先生成干净的纯色背景，再用后处理去底。不要直接对 <code>gpt-image-2</code> 请求原生透明背景；如果后续路由接入支持透明背景的图像模型，再单独确认模型和参数。</p> <hr /> <h2 id="responses-api-liu-shi-partial-images">Responses API：流式 partial images</h2> <p>OpenAI 官方示例里，图片生成可以返回 partial images，用于更快给用户展示中间结果。XAI Router 兼容时，可以在工具里加 <code>partial_images</code>：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> stream</span><span style="color: #F97583;"> = await</span><span> client.responses.</span><span style="color: #B392F0;">create</span><span>({</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-5.5&quot;</span><span>,</span></span> <span class="giallo-l"><span> input:</span><span style="color: #9ECBFF;"> &quot;Draw an elegant AI studio with a generated image panel.&quot;</span><span>,</span></span> <span class="giallo-l"><span> stream:</span><span style="color: #79B8FF;"> true</span><span>,</span></span> <span class="giallo-l"><span> tools: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> type:</span><span style="color: #9ECBFF;"> &quot;image_generation&quot;</span><span>,</span></span> <span class="giallo-l"><span> model:</span><span style="color: #9ECBFF;"> &quot;gpt-image-2&quot;</span><span>,</span></span> <span class="giallo-l"><span> size:</span><span style="color: #9ECBFF;"> &quot;1024x1024&quot;</span><span>,</span></span> <span class="giallo-l"><span> partial_images:</span><span style="color: #79B8FF;"> 2</span><span>,</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span>});</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">for await</span><span> (</span><span style="color: #F97583;">const</span><span style="color: #79B8FF;"> event</span><span style="color: #F97583;"> of</span><span> stream) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (event.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;response.image_generation_call.partial_image&quot;</span><span>) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> const</span><span style="color: #79B8FF;"> imageBuffer</span><span style="color: #F97583;"> =</span><span> Buffer.</span><span style="color: #B392F0;">from</span><span>(event.partial_image_b64,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>);</span></span> <span class="giallo-l"><span> fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">`partial-${</span><span>event</span><span style="color: #9ECBFF;">.</span><span>partial_image_index</span><span style="color: #9ECBFF;">}.png`</span><span>, imageBuffer);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (event.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;response.output_item.done&quot;</span><span>) {</span></span> <span class="giallo-l"><span style="color: #F97583;"> const</span><span style="color: #79B8FF;"> item</span><span style="color: #F97583;"> =</span><span> event.item;</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> (item?.type</span><span style="color: #F97583;"> ===</span><span style="color: #9ECBFF;"> &quot;image_generation_call&quot;</span><span style="color: #F97583;"> &amp;&amp;</span><span> item.result) {</span></span> <span class="giallo-l"><span> fs.</span><span style="color: #B392F0;">writeFileSync</span><span>(</span><span style="color: #9ECBFF;">&quot;final.png&quot;</span><span>, Buffer.</span><span style="color: #B392F0;">from</span><span>(item.result,</span><span style="color: #9ECBFF;"> &quot;base64&quot;</span><span>));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>产品上可以先展示 partial image，再用最终图替换它。这样用户感知延迟会低很多，尤其适合图片生成页、创意工具和聊天式设计助手。</p> <hr /> <h2 id="responses-api-wei-shen-me-jian-yi-shi-yong-stream">Responses API：为什么建议使用 stream</h2> <p>图片生成比普通文本响应耗时更长。虽然当前实测中非流式 Responses 图片生成可以直接返回完整结果，但对脚本和服务端任务来说，<code>stream: true</code> 更直接：</p> <ol> <li>可以看到 <code>response.image_generation_call.generating</code> 等进度事件。</li> <li>可以在同一条连接里拿到最终 <code>image_generation_call</code>。</li> <li>不需要额外管理轮询、任务状态和超时恢复。</li> </ol> <p>如果你只是做一次性验证，可以先把提示词写短，生成一张 <code>1024x1024</code> 的图。等链路稳定后，再增加更详细的画面描述、品牌约束和风格要求。</p> <hr /> <h2 id="ti-shi-ci-jian-yi">提示词建议</h2> <p>图像生成提示词不需要很长，但最好明确四件事：</p> <ul> <li><strong>主体</strong>：要生成什么，例如技术封面、产品图、角色头像。</li> <li><strong>构图</strong>：居中、半身、俯视、留白、横幅或方图。</li> <li><strong>风格</strong>：写实、半写实、插画、产品渲染、编辑感。</li> <li><strong>避免项</strong>：不要水印、不要文字、不要变形手、不要低质量伪影。</li> </ul> <p>例如：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Create an elegant technical cover image for an article about GPT-5.5 calling GPT Image 2 through an API router.</span></span> <span class="giallo-l"><span>Show a refined glass AI studio, a luminous prompt console, and a generated image appearing as a softly glowing framed visual.</span></span> <span class="giallo-l"><span>Square 1024x1024 composition, premium editorial look, graphite, ivory, soft teal and silver accents.</span></span> <span class="giallo-l"><span>No words, no logos, no watermark, no clutter.</span></span></code></pre> <p>如果你需要图片里出现准确文字，建议谨慎使用。图像模型可以生成文字，但稳定性通常不如在前端、设计软件或后处理流程里单独排版。</p> <hr /> <h2 id="gua-he-luo-di-de-chan-pin-xing-tai">适合落地的产品形态</h2> <p>这个组合适合很多常见产品功能：</p> <table><thead><tr><th>场景</th><th>典型输入</th><th>输出</th></tr></thead><tbody> <tr><td>博客封面生成</td><td>文章标题、摘要、风格</td><td>封面图</td></tr> <tr><td>电商素材</td><td>商品名、卖点、背景偏好</td><td>商品场景图</td></tr> <tr><td>角色头像</td><td>人设、职业、服装、表情</td><td>头像或角色卡</td></tr> <tr><td>广告创意</td><td>活动主题、品牌色、禁用元素</td><td>多个方向的视觉草案</td></tr> <tr><td>设计助手</td><td>用户自然语言需求</td><td>可保存和复用的图片资产</td></tr> </tbody></table> <p>一个稳妥的后端流程通常是：</p> <ol> <li>接收用户输入和画面约束。</li> <li>用 <code>gpt-5.5</code> 整理或补全图像提示词。</li> <li>调用 <code>image_generation</code>，图像模型指定 <code>gpt-image-2</code>。</li> <li>把 base64 解码成图片文件。</li> <li>上传到对象存储或 CDN。</li> <li>返回图片 URL、模型、尺寸、提示词和生成时间。</li> </ol> <p>这样做比把生成逻辑直接塞在前端更稳：Key 不暴露，超时可控，也方便记录失败原因和重试。</p> <hr /> <h2 id="chang-jian-wen-ti">常见问题</h2> <h3 id="gpt-image-2-neng-bu-neng-fang-zai-responses-api-de-model-zi-duan"><code>gpt-image-2</code> 能不能放在 Responses API 的 <code>model</code> 字段？</h3> <p>不要这样写。Responses API 的 <code>model</code> 字段应该放文本/主线模型，例如 <code>gpt-5.5</code>。<code>gpt-image-2</code> 是图像模型，应该放在 <code>image_generation</code> 工具配置里。</p> <p>但如果你调用的是 <code>/v1/images/generations</code> 或 <code>/v1/images/edits</code>，那里的 <code>model</code> 字段就应该直接写 <code>gpt-image-2</code>。</p> <h3 id="xu-yao-rang-tu-pian-li-chu-xian-zhong-wen-biao-ti-zen-me-ban">需要让图片里出现中文标题怎么办？</h3> <p>建议把文字和图片分开处理：图像模型负责生成无字背景或主视觉，前端、Canvas、设计软件或后处理脚本负责排版中文。这样可控性更高，也更容易保持品牌字体和响应式布局。</p> <hr /> <h2 id="xiao-jie">小结</h2> <p>通过 XAI Router 调用 <code>gpt-image-2</code>，现在有两种稳定写法：</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>gpt-5.5 -&gt; image_generation tool -&gt; gpt-image-2 -&gt; base64 image result</span></span> <span class="giallo-l"><span>/v1/images/generations or /v1/images/edits -&gt; gpt-image-2 -&gt; b64_json image result</span></span></code></pre> <p>Responses API 适合把“理解需求、扩写提示词、选择工具、生成图像”放在同一个多模态工作流里。Images API 适合兼容 OpenAI 官方 SDK 和 <code>/v1/images/*</code> 调用，尤其是已有 <code>images.generate()</code> 或 <code>images.edit()</code> 代码的应用。对应用开发来说，前端只需要提交自然语言需求或图片文件，后端调用 XAI Router，再把 <code>gpt-image-2</code> 返回的图片保存到对象存储、CDN 或本地文件即可。</p> <p>参考资料：</p> <ul> <li><a rel="external" href="https://developers.openai.com/api/docs/guides/tools-image-generation">OpenAI Image generation tool</a></li> <li><a rel="external" href="https://developers.openai.com/api/docs/guides/image-generation">OpenAI Image generation guide</a></li> <li><a rel="external" href="https://developers.openai.com/api/docs/models/gpt-image-2">OpenAI GPT Image 2 model page</a></li> <li><a rel="external" href="https://developers.openai.com/api/docs/models/gpt-5.5">OpenAI GPT-5.5 model page</a></li> </ul>