Reasonix 是一款面向 AI 编程、项目分析和 Agent 工作流的工具。

安装完成后，很多用户会发现一个问题：明明自己的 API 接口中已经有不少模型，但在 Reasonix 的会话列表里却看不到，输入 /model 也无法切换。

这通常不是模型接口出了问题，而是还没有完成 Reasonix 内部的模型接入和启用。

Reasonix 的模型管理并不是“填写一个 API Key，就自动开放接口中的全部模型”，而是分为两个层级：

1. 先添加模型供应商，也就是 Provider；
2. 再从该供应商中选择并启用需要使用的模型。

只有完成这两个步骤，模型才会真正出现在 Reasonix 的会话、Planner 和 Executor 配置中。

如果把 Reasonix 看成一个工作台，那么模型供应商就是接入工作台的线路，而“已启用模型”则决定这条线路上的哪些模型可以被实际调用。

二、模型设置：决定 Reasonix 能调用哪些模型

进入 Reasonix 的设置页面后，可以看到模型配置主要分为两个 Tab：

• 使用：设置默认模型、规划模型、运行上限以及模型调用策略；
• 接入：添加和管理模型供应商，也就是 Provider。

官方平台、自建接口、第三方聚合平台以及 OpenAI 兼容接口，都需要在“接入”页面进行配置。

其中，“接入”是整个模型配置过程中最关键的一步。

2.1 Reasonix 模型接入的核心逻辑

Reasonix 不会无条件显示接口中的所有模型。

只有先添加模型供应商，并保存、启用对应模型后，这些模型才会出现在以下位置：

• “模型 → 使用”页面；
• 新建会话的模型选择器；
• 会话中的 /model 模型切换列表；
• Planner、Executor 等模型配置选项。

可以把它简单理解为：

供应商负责提供模型接口，已启用模型决定哪些模型可以在 Reasonix 中使用。

即使某个模型已经存在于服务端接口中，只要它没有在供应商设置里被勾选启用，Reasonix 仍然不会将它显示在会话模型列表中。

因此，当出现“接口里明明有模型，但 Reasonix 看不到”的情况时，不要急着判断接口不可用。先检查供应商是否已经刷新模型，以及目标模型是否已经启用。

2.2 API Key 是如何保存的

Reasonix 不建议把完整 API Key 直接写进主配置文件，而是通过环境变量进行引用。

在供应商配置页面中，需要填写的通常不是完整密钥，而是环境变量名称，例如：

UIUIAPI_API_KEY

真正的 API Key 会统一保存在 Reasonix 的全局 .env 文件中。

默认位置通常为：

~/.reasonix/.env

对应内容类似：

UIUIAPI_API_KEY=sk-xxxxxxxxxxxxxxxx

而在供应商配置文件中，只会记录类似下面的环境变量引用：

api_key_env: UIUIAPI_API_KEY

这种设计有几个明显的好处。

第一，主配置文件中不会直接暴露完整密钥。即使复制配置、上传项目或分享截图，也不容易误传 API Key。

第二，多个供应商或多个配置文件可以共用统一的密钥管理方式，后续更换 Key 时也更加方便。

第三，可以将模型配置和敏感凭证分开管理，降低密钥被提交到 Git 仓库或公开文档中的风险。

需要特别注意：环境变量名称区分大小写。

例如下面两个变量，在系统中会被视为不同的变量：

UIUIAPI_API_KEY
uiuiapi_api_key

供应商配置页面填写的变量名称，必须与 .env 文件中的名称完全一致。

2.3 uiuiAPI 接入 Reasonix 的配置示例

以本文实际使用的环境为例，Reasonix 已经接入一个名为 uiuiAPI 的自定义模型供应商。

当前配置如下：

本文示例环境中启用的模型包括：

gpt-5.5
gpt-5.5-thinking
gpt-5.5-xhigh
gpt-5.6-Luna
gpt-5.6-sol
gpt-5.6-terra

完成启用后，这些模型便可以出现在 Reasonix 的模型使用页面和会话模型选择器中。

这里有一个很容易被忽略的问题：Reasonix 中填写或启用的模型 ID，必须与接口实际返回的模型 ID 完全一致。

以下差异都可能导致调用失败：

• 大小写不一致；
• 连字符和下划线不一致；
• 模型后缀缺失；
• 使用了展示名称，而不是实际模型 ID；
• 模型已经下线，但本地仍然保留旧名称。

例如，接口返回的是：

gpt-5.5-thinking

就不要自行修改成：

GPT-5.5-Thinking

模型名称看起来相似，并不代表服务端会自动识别。

三、自定义接入模型的完整步骤

Reasonix 主要支持两种模型供应商接入方式：

1. 使用官方提供的推荐预设；
2. 手动创建自定义供应商。

对于 OpenAI、Anthropic 或其他已经被 Reasonix 预置的平台，可以优先使用推荐预设。

对于 uiuiAPI自建服务、企业内部接口以及其他 OpenAI 兼容平台，则更适合选择“自定义供应商”。

3.1 打开模型接入页面

进入 Reasonix 设置页面，依次点击：

设置 → 模型 → 接入

进入模型接入页面后，点击右上角的：

+ 添加模型服务

随后可以选择：

• 推荐预设；
• 自定义供应商。

不同版本的 Reasonix 在按钮名称和页面布局上可能略有区别，但整体配置逻辑基本一致。

3.2 方式一：使用推荐预设

Reasonix 通常会预置一些常见模型服务，例如：

• Kimi；
• MiMo；
• MiniMax；
• GLM；
• Qwen；
• StepFun；
• Novita。

选择对应供应商后，Reasonix 一般会自动填写部分基础信息，例如：

• 协议类型；
• 默认 Base URL；
• API Key 环境变量名称；
• 模型发现方式。

用户只需要根据自己的接口情况填写 API Key，或者调整接口地址、模型列表和其他参数即可。

这种方式配置速度比较快，适合直接使用官方模型服务的用户。

不过，即使使用推荐预设，也建议检查一次 Base URL 和协议类型。部分用户使用的是代理地址、企业网关或自定义线路，如果完全照搬官方地址，可能无法访问自己实际购买的服务。

3.3 方式二：添加自定义供应商

对于 uiuiAPI 自建中转接口以及其他 OpenAI 兼容平台，建议选择：

自定义供应商

主要需要填写以下字段：

下面分别说明每个字段应该如何填写。

1. 名称

名称主要用于 Reasonix 内部展示，不会直接影响接口调用。

可以填写品牌名称、接口用途、账号类型或线路名称，例如：

uiuiAPI
uiuiAPI-VIP
OpenAI-Official
Claude-Backup
Local-Model
Development-Line

如果只接入一个供应商，填写平台名称即可。

如果同时接入多个 Base URL，建议在名称中标明线路用途，例如：

uiuiAPI-默认线路
uiuiAPI-VIP线路
uiuiAPI-备用线路

这样在切换模型或排查接口问题时会直观很多。

2. Base URL

Base URL 是 Reasonix 实际发送模型请求的接口地址。

对于 OpenAI 兼容接口，通常建议填写带有 /v1 的地址，例如：

https://api.uiuihao.com/v1

一般不需要填写完整的聊天接口路径：

https://api.uiuihao.com/v1/chat/completions

Reasonix 会根据所使用的协议和请求类型，自动拼接对应路径。

如果直接把 /v1/chat/completions 填进 Base URL，后续有可能被再次拼接，形成错误地址，例如：

/v1/chat/completions/chat/completions

不同服务端实现可能存在差异，但在大多数 OpenAI 兼容场景下，填写到 /v1 即可。

3. API Key 环境变量名

这里填写的不是完整 API Key，而是保存密钥的环境变量名称。

例如：

UIUIAPI_API_KEY

Reasonix 会将真实密钥写入或读取：

~/.reasonix/.env

对应格式为：

UIUIAPI_API_KEY=sk-xxxxxxxxxxxxxxxx

建议环境变量名称使用大写字母和下划线，避免空格、中文或特殊符号。

如果要接入多个供应商，可以分别设置不同变量：

UIUIAPI_API_KEY=sk-xxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
BACKUP_API_KEY=sk-xxxxxxxx

这样不同供应商之间互不影响，后续更换密钥时也更容易定位。

4. 协议类型

如果接口兼容 OpenAI 的请求格式，通常选择：

openai

如果服务端使用 Anthropic 原生协议，则应选择对应的 Anthropic 类型。

协议类型必须与服务端实际支持的请求格式一致。

否则，即使 Reasonix 能够成功获取模型列表，也可能在发送消息时出现以下问题：

• 参数格式错误；
• 消息结构不兼容；
• 工具调用字段无法识别；
• 流式输出异常；
• 系统提示词字段不被支持；
• 返回结果无法解析。

因此，“能刷新模型列表”只能说明模型列表接口可以访问，并不能完全证明聊天调用一定正常。

5. 模型发现

开启“模型发现”后，Reasonix 会尝试从供应商接口自动获取模型列表。

对于支持 OpenAI 模型列表接口的平台，一般会请求：

GET /v1/models

如果供应商支持该接口，建议开启模型自动发现。

这样后续平台新增模型时，只需要回到 Reasonix 点击“刷新模型”，不必手动逐个录入模型 ID。

如果刷新失败，也不一定代表聊天接口不可用。有些平台可以正常调用聊天模型，但没有实现标准的 /v1/models 接口，或者对模型列表访问做了额外限制。

遇到这种情况，可以关闭自动发现，改为手动添加模型。

6. 额外请求头

大多数 OpenAI 兼容接口只需要标准的 Authorization 请求头，因此“额外请求头”通常可以留空。

只有供应商明确要求额外 Header 时，才需要填写，例如：

X-API-Source
X-User-ID
X-Channel
X-Project-ID

不要随意重复添加标准 Authorization Header，除非供应商文档明确要求。

重复、格式错误或相互冲突的认证请求头，反而可能导致接口返回 401 或 403 错误。

3.4 保存供应商并启用模型

供应商信息填写完成后，先保存配置。

随后通常可以执行以下操作：

• 点击“配置”，修改已有供应商；
• 点击“刷新模型”，重新获取接口模型列表；
• 在“已启用模型”区域勾选需要开放的模型；
• 取消勾选暂时不用或不希望展示的模型；
• 保存启用状态。

需要再次强调：

只有被勾选并保存的模型，才会出现在 Reasonix 的模型选择列表中。

因此，如果接口明明支持某个模型，但 Reasonix 会话中看不到，可以优先检查以下几项：

1. 是否成功刷新了模型列表；
2. 目标模型是否已经被勾选；
3. 勾选后是否点击了保存；
4. 供应商是否处于启用状态；
5. API Key 是否正确写入；
6. Base URL 是否包含正确的 /v1 路径；
7. 模型 ID 是否与接口返回值完全一致。

四、uiuiAPI 接入 Reasonix 的推荐配置

对于 uiuiAPI 以及其他多模型聚合平台，Reasonix 的自定义供应商功能比较实用。

完成一次供应商配置后，可以通过同一个入口接入多个系列的模型，例如：

• GPT 系列；
• Claude 系列；
• Gemini 系列；
• DeepSeek 系列；
• Grok 系列；
• 其他兼容 OpenAI 请求协议的模型。

不过需要注意，Reasonix 的主要使用场景仍然是 AI 编程、文本生成、项目分析以及 Agent 工作流。

即使聚合平台中存在图像或视频模型，也不代表 Reasonix 当前界面一定能够完整适配其输入参数和输出格式。

例如，部分图像或视频模型可能需要：

• 图片尺寸参数；
• 首尾帧图片；
• 视频时长；
• 异步任务查询；
• 特殊响应字段；
• 文件上传接口。

这些能力未必能够通过普通文本会话直接调用。

因此，在 Reasonix 中选择模型时，建议优先启用适合文本、代码和工具调用场景的模型。

4.1 建议开启模型自动发现

如果聚合平台支持：

GET /v1/models

建议打开模型发现功能。

以后在 uiuiAPI 后台新增模型后，只需要回到 Reasonix，点击：

刷新模型

便可以获取更新后的模型列表。

通常不需要重新创建供应商，也不需要重新填写 API Key。

不过，刷新模型后，新模型不一定会自动进入会话列表。仍然需要检查它是否已经被勾选启用。

4.2 不要一次启用过多模型

聚合平台中的模型数量通常比较多，但没有必要将所有模型都开放到 Reasonix 的会话列表中。

模型启用得越多，选择器越长，日常使用时反而越容易选错。

比较合理的配置方式是保留少量、用途明确的模型：

• 一个日常默认模型；
• 一个高推理模型；
• 一个低成本快速模型；
• 一个 Planner 专用模型；
• 一个备用模型。

例如可以按用途命名和选择：

默认模型：日常代码修改与问答
Planner：复杂项目分析与任务拆解
快速模型：简单修改、文档和重复任务
备用模型：主模型不可用时临时切换

这样不仅能让模型列表更简洁，也方便控制调用成本和响应速度。

4.3 默认模型与 Planner 模型分开设置

Reasonix 支持将普通执行模型与 Planner 模型分开配置。

Planner 更适合负责：

• 分析项目结构；
• 理解用户需求；
• 拆解复杂任务；
• 制定代码修改计划；
• 判断文件之间的依赖关系；
• 评估修改可能带来的影响。

执行模型则更适合负责：

• 修改代码；
• 创建文件；
• 生成测试；
• 调整文档；
• 执行重复性任务；
• 根据已有方案完成具体操作。

比较实用的配置思路是：

Planner：高推理、上下文能力较强的模型
Executor：响应快、稳定、成本相对较低的模型

这样既能保证复杂任务的规划质量，也能控制实际执行阶段的成本和等待时间。

如果所有任务都使用最高成本的推理模型，效果未必会成比例提升，反而可能让简单修改变得更慢。

如果使用配置文件，也可以通过类似 planner_model 的配置项指定规划模型。具体字段名称应以当前 Reasonix 版本为准。

4.4 如何切换默认模型

需要修改默认模型时，可以进入：

设置 → 模型 → 使用

在“使用”页面中选择：

• 当前默认模型；
• Planner 模型；
• 其他模型调用策略。

也可以直接在会话中输入：

/model

从当前已经启用的模型中快速切换。

如果 /model 列表中看不到某个模型，通常有以下几种原因：

• 模型还没有在“接入”页面中启用；
• 模型刚刚启用，会话列表尚未刷新；
• 当前会话仍然绑定旧模型；
• 供应商没有保存成功；
• 模型 ID 已经发生变化。

可以先回到“设置 → 模型 → 接入”检查启用状态，再重新打开会话模型选择器。

4.5 修改配置后是否需要重启 Reasonix

大多数供应商和模型配置修改后，不需要立即重启 Reasonix 桌面端。

通常可以按照以下顺序操作：

1. 保存供应商配置；
2. 点击“刷新模型”；
3. 勾选并保存需要使用的模型；
4. 重新打开模型选择器；
5. 必要时新建一个会话。

如果修改后仍然没有生效，再尝试：

• 重启 Reasonix；
• 检查 .env 文件；
• 确认 API Key 环境变量名称；
• 确认当前会话是否仍然绑定旧模型；
• 查看接口返回的具体错误信息。

有些设置会保留在已经创建的会话中，因此修改全局默认模型后，不一定会立刻覆盖旧会话。

这时直接使用 /model 重新选择，或者新建一个会话，通常更加省事。

五、常见接入问题与排查方法

5.1 提示“未设置密钥”

先检查供应商配置中的 API Key 环境变量名称，例如：

UIUIAPI_API_KEY

然后打开：

~/.reasonix/.env

确认文件中存在：

UIUIAPI_API_KEY=sk-xxxxxxxxxxxxxxxx

重点检查：

• 变量名称是否完全一致；
• 大小写是否一致；
• 是否多了空格；
• Key 前后是否包含引号；
• Key 是否已经失效；
• .env 文件是否保存在正确目录。

推荐格式为：

UIUIAPI_API_KEY=sk-xxxxxxxxxxxxxxxx

除非密钥本身包含特殊字符，否则一般不需要额外添加引号。

5.2 可以刷新模型，但发送消息失败

这种情况通常说明 /v1/models 可以正常访问，但聊天接口调用失败。

建议重点检查：

• 协议类型是否选择正确；
• Base URL 是否多写或少写路径；
• 模型 ID 是否正确；
• 当前 API 分组是否拥有该模型权限；
• API Key 是否有余额或可用额度；
• 服务端是否兼容 Reasonix 发送的请求参数；
• 模型是否支持工具调用；
• 模型是否支持流式输出；
• 接口是否存在并发或频率限制。

如果错误信息中出现：

401 Unauthorized

通常与 API Key、认证请求头或账号权限有关。

如果出现：

404 Not Found

通常与 Base URL 或请求路径有关。

如果出现：

model not found

通常说明模型 ID 不一致，或者当前账号、分组没有该模型权限。

如果出现参数验证错误，则可能是模型协议与 Reasonix 请求格式不兼容。

5.3 模型已经存在，但会话里看不到

进入：

设置 → 模型 → 接入

找到对应供应商，检查“已启用模型”区域。

模型必须同时满足以下条件：

1. 已经从接口中获取或手动添加；
2. 已经被勾选；
3. 已经保存启用状态；
4. 供应商处于启用状态。

完成后重新打开模型选择器。

如果仍然看不到，可以尝试新建会话，或者重启 Reasonix。

5.4 刷新模型列表失败

可以按照以下顺序排查：

1. Base URL 是否正确；
2. 接口是否支持 /v1/models；
3. API Key 是否有效；
4. 接口是否限制模型列表访问；
5. 是否需要额外请求头；
6. 本地网络是否能够访问接口域名；
7. 是否存在代理、证书或 DNS 问题；
8. 服务端返回格式是否符合 OpenAI 兼容规范。

也可以使用其他 API 调试工具测试模型列表接口，例如请求：

GET https://api.uiuihao.com/v1/models

如果接口本身不支持自动模型发现，可以关闭该功能，改为手动维护模型列表。

5.5 修改默认模型后，仍然调用旧模型

先进入：

设置 → 模型 → 使用

确认默认模型是否已经更新。

如果当前会话创建时已经绑定了旧模型，可以在会话中输入：

/model

重新选择目标模型。

也可以直接新建一个会话。

Reasonix 的全局默认模型，主要影响后续新建会话。已经存在的会话可能会继续保留原来的模型配置，这是正常现象。

5.6 模型列表能看到，但调用提示模型不存在

这种情况经常出现在聚合平台或多渠道接口中。

可能原因包括：

• 模型存在于模型列表，但当前分组没有权限；
• 模型名称是展示名称，并非实际调用 ID；
• 后台刚刚调整过模型映射；
• 当前渠道暂时不可用；
• 模型名称大小写或后缀不一致；
• 模型已下线，但模型列表缓存尚未更新。

建议回到供应商页面重新刷新模型，并对照服务端实际返回的模型 ID。

不要只根据网页上的模型名称手动猜测调用 ID。

5.7 部分模型可以聊天，但不能执行 Agent 任务

普通聊天能够成功，并不代表模型一定适合 Reasonix 的完整 Agent 工作流。

Reasonix 在处理项目任务时，可能需要模型支持：

• 工具调用；
• 函数调用；
• 结构化输出；
• 较长上下文；
• 多轮任务状态保持；
• 稳定的流式输出；
• 代码理解与修改。

部分模型虽然可以正常完成文本问答，但在工具调用或结构化输出方面支持不完整，可能出现：

• 一直重复规划；
• 无法正确调用工具；
• 返回格式解析失败；
• 修改文件时中断；
• Planner 正常，但 Executor 无法执行。

遇到这种情况，可以尝试更换一个对工具调用和代码任务支持更完善的模型。

六、一套更实用的模型配置思路

如果不确定应该启用哪些模型，可以先使用一套相对简单的配置。

日常默认模型

适合普通代码问答、局部修改、解释报错和生成文档。

要求是响应速度快、稳定性好，不必一味追求最高推理强度。

Planner 模型

适合分析大型项目、跨文件修改、复杂需求拆解和架构调整。

建议选择上下文能力较强、推理稳定的模型。

快速执行模型

用于格式调整、批量替换、简单页面修改、测试生成和重复性任务。

这类任务通常不需要最高级别的推理能力。

备用模型

当默认模型出现限流、渠道异常或响应不稳定时，可以快速切换到备用模型，避免工作流完全中断。

最终可以形成类似这样的配置：

默认模型：稳定的通用编程模型
Planner：高推理模型
快速任务：低延迟模型
备用模型：另一条独立线路

比起一次性启用几十个模型，这种配置方式更清楚，也更适合长期使用。

七、界智通(jieagi)总结

Reasonix 的模型接入看起来字段不少，但真正的核心流程并不复杂：

添加供应商
→ 填写 Base URL
→ 设置 API Key 环境变量
→ 选择正确的协议类型
→ 刷新模型列表
→ 勾选并启用模型
→ 设置默认模型与 Planner

其中最容易被忽略的有三点：

第一，接口中存在模型，不代表它已经在 Reasonix 中启用。

第二，API Key 环境变量名称必须与 .env 文件完全一致。

第三，模型名称必须使用接口实际返回的模型 ID，不能随意修改大小写、连字符或后缀。

以 uiuiAPI 这类 OpenAI 兼容聚合平台为例，完成一次自定义供应商配置后，就可以在 Reasonix 中统一管理多个文本和编程模型。

合理区分默认模型、Planner 模型、快速模型与备用模型，不仅能提升复杂任务的完成质量，也能更好地控制响应速度和接口使用成本。

当模型无法显示或调用失败时，也不必立刻重新安装软件。大多数问题都可以从供应商状态、模型启用、Base URL、环境变量、协议类型和模型 ID 这几个方向快速定位。

版权信息： 本文由界智通(jieagi)团队编写，图片、文本保留所有权利。未经授权，不得转载或用于商业用途。

过去一年，大模型之间的竞争已经不只是"谁回答得更聪明"，而是逐渐转向一个更实际的问题：模型能不能长时间稳定地完成复杂任务？

这个变化对开发者来说感受尤其明显。以前我们更多关心模型能不能写一段代码、改一个函数、总结一篇文章；现在，越来越多团队开始把模型放进真实业务流里——让它读完整个代码仓库、交叉分析多份文档、连续调用外部工具、维持多轮上下文，甚至承担起接近"半自动项目助理"的角色。Claude Fable 5 的出现，正是瞄准了这类场景。

根据 Anthropic 官方文档，Claude Fable 5 的 API ID 为 claude-fable-5，被定位为 Anthropic 目前最强的广泛发布模型，面向需要最高能力上限的工作负载。它支持文本和图像输入、文本输出，具备多语言能力和视觉理解，可通过 Claude API、Claude Platform on AWS、Amazon Bedrock、Google Cloud 和 Microsoft Foundry 等渠道调用。

更关键的是，它的规格设计明显偏向"重任务"：1M tokens 上下文窗口、最高 128k tokens 输出，并且始终开启 adaptive thinking（自适应思考）机制。相比常规聊天模型，它更像是为长链路推理、复杂代码工程和多工具编排量身打造的高端选项。

也正因如此，Claude Fable 5 并不适合拿来做低成本闲聊或简单分类，它真正的价值在于：处理那些便宜模型容易断线、忘上下文、工具调用混乱、跨文件一致性差的复杂任务。

一次不大不小的插曲：发布、下架，再到恢复

Claude Fable 5 的上线过程并不平静，这段经历本身也值得开发者了解——它直接关系到接入的稳定性预期。

• 6 月 9 日发布：Anthropic 同时推出 Claude Fable 5（面向公众，带安全分类器）和能力对等的 Claude Mythos 5（仅限 Project Glasswing 可信合作伙伴使用，不带分类器）。Fable 5 在软件工程、长时程代理任务、知识工作和视觉理解上表现突出。
• 6 月 12 日全球下架：美国政府以国家安全为由发出出口管制指令，Anthropic 在无法逐一核验用户资质的情况下，选择全球暂停访问以规避合规风险。
• 6 月 30 日管制解除，7 月 1 日恢复访问：经过协商与安全分类器升级，商务部撤销限制，Fable 5 于 7 月 1 日起重新全球可用；Mythos 5 仍维持有限访问。

恢复后，Fable 5 已在 Claude.ai、Claude Platform、Claude Code、Claude Cowork 等平台上线，并陆续覆盖 AWS、Google Cloud、Microsoft Foundry。付费计划方面，Pro、Max、Team 及部分 Enterprise 用户在 7 月 7 日前可使用 Fable 5 抵扣至多 50% 的周使用额度，此后转为按使用积分（usage credits）计费。API 调用则从一开始就按标准 token 单价计费，不受这一窗口期影响。

这段插曲对开发者的实际启示是：接入任何前沿模型时，都应该提前设计 fallback 策略——不只是应对模型报错，也要应对政策性、地缘性的临时不可用。

二、模型定位：不是"更贵的聊天模型"，而是高端任务层

如果只看名字，很多人会把 Claude Fable 5 理解成 Claude 系列的一次常规升级。但从官方定位和规格来看，它更像是 Anthropic 单独为高端任务拉出来的一层能力模型。

在 Anthropic 的模型选择建议中，如果开发者不确定该用哪个模型，官方建议先从 Claude Opus 4.8 开始；只有当工作负载明确需要"最高可用能力"时，才升级到 Claude Fable 5。这个细节其实很关键：它暗示 Fable 5 并不是默认最划算的选项，而是为高难度任务准备的"能力上限优先"模型。

适合 Fable 5 的典型任务大致可以归为四类：

第一类，复杂代码工程。 比如大型代码库重构、跨模块 bug 定位、复杂迁移方案设计、长时间运行的 coding agent 任务。这类场景不是简单生成代码，而是要求模型长期保持上下文、理解模块间依赖、反复自我验证。

第二类，超长文档分析。 比如企业制度、合同、技术规范、产品需求文档、研发资料库等。1M tokens 上下文的价值，在这类场景里会体现得非常直接。

第三类，多工具 Agent。 当模型需要连续调用搜索、数据库、代码执行、文件读取、API 查询等工具时，它的状态管理能力和错误恢复能力会直接决定最终结果的可靠性。

第四类，高价值知识工作。 比如技术调研、竞品分析、架构评审、投研报告、复杂方案设计。这类任务单次调用成本偏高，但如果能显著节省人工时间，仍然可能是划算的。

所以对开发者来说，Fable 5 更合理的用法不是"全站默认替换"，而是作为模型路由体系里的高端层：简单任务交给低成本模型，中等复杂度任务交给 Opus、Sonnet 等通用模型，真正复杂、长上下文、多工具的任务再路由到 Fable 5。

三、核心能力：长上下文、长输出与复杂任务的稳定性

Claude Fable 5 最值得关注的三项能力，是 1M 上下文、128k 输出、adaptive thinking。

1. 1M tokens 上下文

1M tokens 上下文意味着模型可以一次性接收非常大的资料量。对开发者而言，这不只是"能塞更多文字"，而是会改变应用的设计方式。

以前做长文档问答，通常需要切片、召回、重排、再拼接，这个流程容易丢信息，也容易让模型只看到局部内容。Fable 5 的长上下文让很多场景可以更直接地处理完整资料，尤其适合：

• 大型代码仓库分析
• 多份合同或制度的交叉比对
• 长篇技术文档审查
• 产品需求与实现方案的一致性检查
• 多轮 Agent 的状态保留

不过长上下文并非没有代价。上下文越长，成本和延迟越容易上升。生产环境中仍然建议配合 RAG、缓存、摘要和分层路由，而不是每次都把全部资料一股脑塞进去。

2. 最高 128k tokens 输出

128k 输出对代码生成、长报告生成、迁移方案、批量结构化文档的价值很直接。比如让模型输出完整接口文档、长篇技术方案、多文件重构建议时，不容易因为输出长度不够而被截断。

这也要求开发者重新设置 max_tokens：由于 Fable 5 默认带思考机制，max_tokens 不只是控制可见回答的长度，也会占用模型完成复杂任务所需的推理空间。如果沿用旧模型偏小的输出上限，很可能出现内容还没讲完就被截断的情况。

3. Adaptive thinking（自适应思考）

Claude Fable 5 使用自适应思考机制，模型会根据任务难度自行决定投入多少推理过程。根据 Anthropic 的迁移文档，Fable 5 不支持关闭 thinking，开发者应该通过 effort、max_tokens、提示词结构和任务边界来控制效果，而不是试图关掉它。

这也意味着调参的重点需要转移：不再是传统的 temperature、top_p，而是更工程化的控制方式：

• 明确任务目标
• 明确输出格式
• 明确验收标准
• 控制 effort 档位
• 配合工具调用和缓存
• 持续监控成本与延迟

四、API 调用方式：Messages API 仍是核心入口

如果你不想单独申请 Anthropic 官方 API Key，也可以通过 uiuiAPI 获取APIKey，开发者能快速调用 Claude Fable 5。uiuiAPI 支持 OpenAI 兼容格式，一个 API Key 即可接入 Claude、GPT、Gemini、Grok、DeepSeek 等多类模型。只需将接口地址改为 https://uiuiapi地址/v1，模型名填写 claude-fable-5，即可在常见客户端或项目中快速测试使用，更适合多模型接入、项目开发和商业化运营场景。

从开发体验来看，Claude Fable 5 的接入方式并不复杂，仍然使用 Anthropic 的 Messages API，模型 ID 为：

claude-fable-5

Fable 5 可在 Claude API、Claude Platform on AWS、Amazon Bedrock、Google Cloud 和 Microsoft Foundry 上使用。

Python 调用示例

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=4096,
    output_config={
        "effort": "high"
    },
    system=(
        "你是一名资深 AI 平台架构师。"
        "请用清晰、可执行、面向开发者的方式回答。"
        "如遇到不确定信息，请明确标注'需验证'。"
    ),
    messages=[
        {
            "role": "user",
            "content": "请帮我设计一个支持多模型路由、限流和成本统计的大模型 API 聚合平台架构。"
        }
    ]
)

print(response.content[0].text)

curl 调用示例

curl https://uiuiapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 4096,
    "output_config": {
      "effort": "high"
    },
    "system": "你是一名资深 AI 平台架构师，请用工程化、可落地的方式回答。",
    "messages": [
      {
        "role": "user",
        "content": "请分析 Claude Fable 5 在企业 Agent 系统中的适用场景。"
      }
    ]
  }'

需要提醒一点：Fable 5 内置了安全分类器，遇到高风险提示时可能直接以 stop_reason: "refusal" 返回（HTTP 200，而非报错），所以调用侧的错误处理逻辑需要单独覆盖这种情况，不能只按普通异常来处理。

流式响应建议

对于 Fable 5 这类可能输出较长内容的模型，建议默认开启流式响应，这样可以减少用户等待感，也能降低长响应超时的概率。

前端或服务端代理大致可以按这个思路处理：

1. 用户请求进入 API 网关；
2. 网关记录 trace_id、用户 ID、模型 ID；
3. 后端请求 Claude Messages API，并开启 stream；
4. 边接收边转发给前端；
5. 最终落库 token 用量、耗时、stop_reason、成本估算和错误信息。

这类模型更适合"边生成边展示"，尤其是技术报告、代码审查、长文档总结、Agent 执行过程说明等场景。

五、参数配置：重点不在 temperature，而在 effort 与任务结构

很多开发者接入新模型时，第一反应是问：temperature 设多少？top_p 设多少？

但在 Claude Fable 5 上，真正重要的不是这些传统采样参数，而是：

output_config.effort
max_tokens
system prompt
messages 上下文结构
tools 工具定义
stream 是否开启
fallback 策略

Anthropic 的迁移说明提到，Fable 5 使用 adaptive thinking，建议从较高的 effort 档位开始评估；同时，assistant prefill 这类旧式用法也不适合直接照搬迁移。

effort 怎么选？

可以按任务价值分层来考虑：

比较稳妥的做法是先用 high 做基线评估，再挑少量最复杂的任务测试 xhigh。不建议一上来就全部拉满档位，否则成本很容易失控。

六、成本与价格：能力很强，但价格也不便宜

Claude Fable 5 的定位很明确：高端能力，高端价格。

根据 Anthropic 官方定价，Claude Fable 5 的费用为：

• 输入：$10 / MTok
• 输出：$50 / MTok
• 5 分钟缓存写入：$12.50 / MTok
• 1 小时缓存写入：$20 / MTok
• 缓存命中与刷新：$1 / MTok

这个价格是 Claude Opus 4.8 的两倍。举个例子，如果一个请求输入 120k tokens、输出 8k tokens，不考虑缓存，大致成本是：

输入成本：0.12 × 10 = $1.20
输出成本：0.008 × 50 = $0.40
单次合计：约 $1.60

对普通聊天场景来说，这个价格显然偏高；但如果它替代的是工程师几个小时的复杂分析，或者帮助企业完成一次代码迁移评估，这笔成本反而可能相当合理——尤其是配合 Prompt Caching 之后，重复上下文的命中价格能降到标准输入价的十分之一，长期跑 Agent 任务时能省下不少钱。

所以，Fable 5 的成本优化重点不是"压低单价"，而是做好模型路由：

简单任务：低成本模型
中等任务：通用强模型
复杂任务：Claude Fable 5
离线批处理：Batch API（输入输出各半价）
重复上下文：Prompt Caching

在 API 聚合平台或企业内部模型网关中，建议单独给 Fable 5 设置预算、限流、并发和调用白名单，避免被当成普通聊天模型随意消耗。

七、数据保留与合规：上线前必须重点确认

Claude Fable 5 还有一个容易被忽略、但非常重要的限制：数据保留策略。

根据 Anthropic 官方文档，Claude Fable 5 和 Claude Mythos 5 属于 "Covered Models"，需要 30 天数据保留，且不支持 Zero Data Retention（零数据保留）——这一点即便是原本已经签了零保留协议的企业客户，也无法豁免。

这对企业客户、API 平台、金融、医疗、政企项目尤其重要。如果你的业务要求：

• 零数据保留；
• 严格本地化；
• 敏感数据不可离开指定区域；
• 对供应商数据处理有严格审计要求；

那么在接入 Fable 5 之前，务必先做一轮合规评估——不能只看模型能力强不强，还要看数据保留、日志、隐私协议、客户授权和业务边界是否匹配。

实际落地时，建议至少做三件事：

1. 在产品说明中明确模型供应商和数据处理边界；
2. 对敏感业务默认不走 Fable 5，除非用户明确授权；
3. 后台保留模型调用日志，但不要保存不必要的原始敏感内容。

对于 API 聚合平台来说，还可以在模型说明里加一句提示：该模型适合复杂任务，不建议输入高度敏感信息；企业客户如有严格的数据保留要求，应先确认合规策略再接入。

八、适用场景：哪些任务真正适合 Claude Fable 5？

复杂代码项目分析。 让模型阅读多个文件，判断某个功能为什么异常，给出重构建议，并生成可执行的修改步骤。Fable 5 的长上下文和复杂推理能力在这里更容易体现价值。

企业知识库深度问答。 当用户的问题不是简单检索，而是需要跨多个文档综合判断时，Fable 5 比普通模型更适合承担"分析层"的角色。

长时程 Agent 工作流。 比如自动调研、自动写报告、自动生成方案、自动拆解任务、连续调用工具并回写结果。Fable 5 的优势在于更容易保持任务目标，不容易在长链路中"跑偏"。

架构设计与技术决策。 比如模型路由系统设计、API 网关方案、成本核算、故障回退策略、安全合规设计等。这类问题往往没有单一标准答案，需要综合判断。

高质量内容生产。 用于生成深度技术文章、行业研究报告、产品白皮书、开发者文档时，Fable 5 的长输出和复杂结构控制能力比较有用。

九、不适合的场景：不要什么都上 Fable 5

再强的模型，也不应该被滥用。以下场景不建议优先使用 Claude Fable 5：

• 简单客服问答
• 短文本改写
• 普通翻译
• 简单分类
• 轻量摘要
• 高频低价值请求
• 对数据保留极其敏感的场景
• 对延迟要求极低的实时交互

这些任务用更便宜、更快的模型通常就够了。Fable 5 应该被放在"高价值、低频、复杂"的任务层，而不是成为默认模型。

十、提示词建议：让 Fable 5 更像工程助手，而不是聊天机器人

Fable 5 的提示词最好写得更像一份工程任务书，而不是随口一问。推荐的结构是：

你是……
你的目标是……
你需要参考……
输出必须包含……
如果遇到不确定信息，请标注。
如果存在风险，请单独输出。

举个例子：

你是一名资深 AI 平台架构师。

请基于以下需求，设计一个支持多模型路由的大模型 API 网关方案。

要求：
1. 先给结论；
2. 再给系统架构；
3. 说明模型路由策略；
4. 说明限流、计费、日志和错误回退；
5. 给出最小可落地版本；
6. 不确定的信息请标注"需验证"。

输出格式：
- 总体结论
- 架构设计
- 路由策略
- 成本控制
- 风险点
- 落地步骤

这种写法比"帮我分析一下"稳定得多，也更适合接入生产系统。

十一、生产部署建议：模型网关比单点调用更重要

如果只是个人测试，直接调用 Claude API 就够了。但如果要上线到真实业务，建议通过模型网关统一管理。一个比较稳妥的生产架构大致是这样：

用户请求
  ↓
API 网关 / 鉴权
  ↓
任务分类器
  ↓
模型路由
  ├─ 简单任务：低成本模型
  ├─ 中等任务：通用强模型
  └─ 高复杂任务：Claude Fable 5
  ↓
Prompt 模板层
  ↓
工具调用 / RAG / 文件解析
  ↓
流式响应
  ↓
日志、计费、限流、监控

上线前建议重点监控这些指标：

• 单次请求 token 成本
• 平均响应时间
• 流式首 token 时间
• refusal rate（拒答率）
• fallback 成功率
• 工具调用轮数
• 用户任务完成率
• 缓存命中率
• 不同模型的性价比对比

尤其是 API 聚合平台，不建议只做"模型转发"。真正专业的平台应该能做模型分层、成本提醒、错误回退、并发控制和日志脱敏，这样用户体验会明显更稳定。

十二、总结：把 Claude Fable 5 当作"高端任务加速器"来用

Claude Fable 5 最大的价值，不是便宜，也不是响应最快，而是它为复杂任务提供了更高的能力上限。它适合：

• 长上下文场景
• 复杂代码工程
• 多工具 Agent
• 深度研究
• 企业知识分析
• 高质量技术内容生成
• 高价值任务自动化

但它也有明显门槛：

• 成本较高
• 延迟可能更高
• 需要合理设置 effort
• 需要做好数据保留评估
• 需要模型路由和 fallback 机制
• 不适合所有请求默认使用

对开发者和平台方来说，最合理的策略是：不要把 Claude Fable 5 当成普通聊天模型，而要把它作为高端任务层，纳入完整的模型路由、成本控制和生产监控体系里。

如果你的业务正在做 AI Agent、代码助手、企业知识库、开发者工具或大模型 API 聚合平台，Claude Fable 5 值得认真评估——但真正上线时，建议先从少量高价值场景灰度验证，而不是全量替换现有模型。

参考资料

• Anthropic Claude Models Overview：Claude Fable 5 的模型定位、上下文、输出长度与可用平台
• Anthropic Pricing：Claude Fable 5 的输入、输出、缓存价格
• Anthropic Migration Guide：Fable 5 的迁移、effort 与 adaptive thinking 相关说明
• Anthropic API and Data Retention：Fable 5 的 30 天数据保留要求
• Anthropic 官方发布说明：Claude Fable 5 与 Claude Mythos 5 的发布背景https://www.anthropic.com/news/fable-mythos-access

版权信息： 本文由界智通(jieagi)团队编写，图片、文本保留所有权利。未经授权，不得转载或用于商业用途。

截至 2026 年 5 月 29 日 的公开资料，Claude Opus 4.8 是 Anthropic 在官方文档中标注的“最强、且已正式可用的通用模型”，定位是面向高难度编码、长程代理任务、知识工作与专业文档处理的旗舰模型；它默认提供 1M token 上下文窗口（Claude API、Bedrock、Vertex AI），最大输出 128k tokens，并支持 adaptive thinking、自适应 effort、prompt caching、Batch API、Files API、PDF、视觉、多种服务端/客户端工具。对开发者最重要的变化是：无须 long-context beta 头、默认 effort=high、支持会话中途 system 消息、较低的最小可缓存长度，以及非默认 temperature/top_p/top_k 会直接返回 400，这意味着 4.8 更像“高自治、高稳定”的工程模型，而不是传统“靠采样参数细调”的通用聊天模型。

如果你的目标是复杂编程代理、深度研究、多文档分析、长上下文审阅、强工具编排，Opus 4.8 值得作为首选；如果你的目标是更低成本、更高吞吐的生产问答/RAG/客服，Claude Sonnet 4.6 往往更均衡。若你当前已在 Opus 4.7 上运行，升级到 4.8 没有破坏性 API 变更，但应立即检查四件事：删掉非默认采样参数、显式评估 effort、用 streaming 处理长请求、把会话指令更新切换为“中途 system 消息 + prompt caching”。

就成本与性能而言，官方标准价已降到 $5/MTok 输入、$25/MTok 输出；Prompt Caching 命中价为基础输入价的 10%，Batch API 继续提供 50% 折扣，Fast mode 则把 Opus 4.8 提升到 $10/$50 per MTok 的更高单价以换取更快输出。官方没有给出统一的延迟/吞吐 SLA；第三方 Artificial Analysis 在“Adaptive Reasoning, Max Effort”的公开测量中显示，不同提供商上的 Opus 4.8 首 token 延迟约在 7.36s–20.02s，输出速度约 60.1–64.4 tokens/s，说明提供商选择会显著影响体感性能。

模型概述

官方定位。 Anthropic 将 Claude Opus 4.8 描述为其“most capable generally available model”，并强调它是对 Opus 4.7 的升级，重点提升了编码、agentic workflows、专业知识工作、协作体验与诚实性。官方发布页还明确写到，4.8 更倾向于主动标示不确定性，在内部评估中“约比前代少 4 倍”地让它自己写出的代码缺陷“悄悄通过而不提醒”。发布页与迁移指南共同表明：4.8 属于 Anthropic 当前旗舰开发模型，而非单纯聊天优化版本。

架构要点。 官方公开材料没有披露 4.8 的参数规模、层数、是否 MoE、训练 FLOPs 等底层架构细节；这部分应明确视为未指定。公开可确认的是：Claude 4 系列属于 hybrid reasoning large language models，支持标准响应模式与extended/adaptive thinking；4.8 延续 4.7 的能力面，支持 adaptive thinking，并通过 output_config.effort 调节思考深度。Anthropic 对 4.7 的透明度说明写到，该代模型经历了大规模预训练和以 Claude Constitution 为目标的后训练对齐，训练数据包括公开互联网信息、公共/私有数据集、以及其他模型生成的合成数据；这可以作为 4.8 的最近官方架构代理，但不能机械外推为 4.8 的完整训练细节。

能力边界与规格。 4.8 在 Anthropic 自家平台、Amazon Bedrock、Vertex AI 上默认提供 1M token 上下文窗口，在 Microsoft Foundry 上发布时为 200k；单次最大输出为 128k tokens。它支持 vision、PDF support、Files API、Batch processing、Prompt caching、服务端与客户端工具，并且从 4.8 开始，1M context 不再需要 beta header，也没有 long-context premium。同时，4.8 支持一个对工程非常有价值的新能力：你可以在 messages 数组中、用户消息之后插入 role: "system" 作为中途系统指令，以便更新行为约束而不重建整段前缀上下文、从而更容易保留 prompt cache 命中。

优点。 对开发者最直接的优势有四类。第一，长上下文与代理式执行：官方把 4.8 定位到长会话、长文档、长程代理工作流，并把 1M context 作为默认能力；第二，更强的工程可控性：中途 system 消息、prompt caching、batch、tooling 组合，使其更适合生产编排；第三，更好的“诚实性”和不确定性暴露，这对审计、高风险知识工作、代码复查尤其重要；第四，价格相较早期 Opus 4.x 显著下探，标准价从 Opus 4.1/4 的 $15/$75 降到 4.8 的 $5/$25。

限制。 4.8 也有几个非常关键的“坑点”。最重要的是，对该模型设置非默认 temperature、top_p 或 top_k 会 400；你应把“思考深度”交给 thinking={"type":"adaptive"} 与 output_config.effort，而不是继续走以前的采样调参思路。其次，prefill 在 Opus 4.8 上不支持；如果你过去用“assistant 预填充”控制输出起始格式，官方建议改用structured outputs 或系统提示。再次，长请求如果不用 streaming，官方 SDK 会认为它可能超时并直接报错或提前终止重试。最后，公开官方资料虽然反复提到 Claude Opus 4.8 System Card，但截至本报告撰写时，Anthropic 的公开 system cards 索引页尚未列出 4.8 条目；因此，4.8 的完整安全评估文档在公开可检索性上仍有不确定性。

API获取 与 SDK 调用示例

更快获取 Claude Opus 4.8 API Key：通过 uiuiAPI 统一接入

对于个人开发者和中小团队来说，想要体验 Claude Opus 4.8，第一步通常是准备可用的 API Key。不过在实际开发中，如果同时需要测试 Claude、GPT、Gemini、DeepSeek、Grok 等多个模型，逐个平台申请账号、管理密钥、适配不同接口格式，往往会增加不少额外成本。

这类场景下，可以考虑使用 uiuiAPI.com 这类聚合 API 服务。它将多种主流大模型统一到一个调用入口中，开发者只需要在后台获取一组 API Key，就可以通过相对统一的方式调用 Claude Opus 4.8 等模型。对于已经兼容 OpenAI 风格 /v1/chat/completions 接口的项目来说，接入成本通常比较低，只需要调整 base_url、api_key 和 model 参数，就能快速完成测试和迁移。

从开发体验来看，uiuiAPI 更适合用于模型选型、产品原型验证、AI 编程助手、知识库问答、自动化内容生成和 Agent 工作流等场景。开发者可以先用统一接口快速验证不同模型在回答质量、响应速度、成本和稳定性上的表现，再根据业务需求选择最合适的模型组合。

这种方式的价值并不只是“多一个 API Key 获取渠道”，而是让模型接入变得更灵活：简单任务可以使用轻量模型控制成本，复杂代码分析、长文档理解和多步骤推理任务则可以切换到 Claude Opus 4.8。对于需要快速落地 AI 应用的团队来说，统一入口、统一密钥管理和统一调用规范，能明显减少前期试错成本。

当然，如果项目对官方账单、合规体系或原生平台能力有强依赖，也可以直接接入 Anthropic 官方 API。更务实的做法是：早期通过 uiuiAPI 快速完成测试和业务验证，等产品形态稳定后，再根据调用规模、成本结构和合规要求，决定继续使用聚合接口，还是进一步接入官方 API。对开发者来说，最重要的不是拘泥于某一种接入方式，而是让模型调用更稳定、成本更可控、开发效率更高。

下面的示例以 Anthropic 官方 Claude API 为基准。核心原则只有两条：一是 Messages API 是无状态的，你需要自己保存并回传完整对话历史；二是 Opus 4.8 不要传非默认采样参数，重点改用 thinking 与 effort。

Python

# 场景：服务端应用 / Web API / 后台任务
# 覆盖：认证、会话管理、adaptive thinking、streaming、重试、上下文计数

import os
import asyncio
from anthropic import AsyncAnthropic, DefaultAioHttpClient
import anthropic

MODEL = "claude-opus-4-8"

client = AsyncAnthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    http_client=DefaultAioHttpClient(),  # 更适合高并发 async 场景
    max_retries=2,                       # 官方默认就是 2，这里显式声明
    timeout=60.0                         # 长请求建议显式设置
)

async def ask_claude(history, user_text):
    messages = history + [{"role": "user", "content": user_text}]

    # 先做 token 估算，避免 context overflow
    token_est = await client.messages.count_tokens(
        model=MODEL,
        messages=messages,
    )
    print("estimated_input_tokens =", token_est.input_tokens)

    try:
        async with client.messages.stream(
            model=MODEL,
            max_tokens=4096,
            system="你是一个严谨的软件架构评审助手，优先给出可执行建议。",
            thinking={"type": "adaptive", "display": "summarized"},
            output_config={"effort": "high"},
            cache_control={"type": "ephemeral"},  # 自动缓存，适合多轮会话
            messages=messages,
        ) as stream:
            buf = []
            async for text in stream.text_stream:
                print(text, end="", flush=True)
                buf.append(text)

            final_msg = await stream.get_final_message()
            return final_msg, "".join(buf)

    except anthropic.RateLimitError:
        # 真实生产环境里应该读取 retry-after 并指数退避
        raise
    except anthropic.APITimeoutError:
        # 对长请求优先改为 stream，或增大 timeout
        raise

async def main():
    history = [
        {"role": "user", "content": "我们准备把单体应用拆成 6 个服务。"},
        {"role": "assistant", "content": "好的，请告诉我当前系统的模块边界和部署方式。"},
    ]
    final_msg, text = await ask_claude(history, "请给我一个分阶段迁移计划。")
    print("\nrequest_id =", final_msg._request_id)

asyncio.run(main())

适用场景：后端服务、多轮助手、长文本输出、并发 API 网关。注意事项：Anthropic 官方 Python SDK 默认支持重试、超时、请求 ID 暴露；对高并发 async 场景，官方明确建议可切到 aiohttp backend；长请求尽量使用 streaming，且 Opus 4.8 应使用 adaptive thinking + effort，而不是采样参数。Messages API 本身是stateless，会话历史必须由你在应用层维护。

# 场景：长文档 / 长上下文分片 + 汇总
# 说明：Anthropic 没有规定固定 chunk 大小，下面是“先局部摘要、再全局综合”的工程模板

async def summarize_chunks(chunks):
    requests = []
    for i, chunk in enumerate(chunks):
        requests.append({
            "custom_id": f"chunk-{i}",
            "params": {
                "model": MODEL,
                "max_tokens": 1200,
                "messages": [{
                    "role": "user",
                    "content": f"<document index='{i}'>{chunk}</document>\n"
                               f"请先抽取关键事实，再给出 5 条摘要。"
                }]
            }
        })

    batch = await client.messages.batches.create(requests=requests)
    print("batch_id =", batch.id)
    # 生产环境中轮询 processing_status == 'ended' 后再取结果

适用场景：大规模异步摘要、海量 chunk 并行处理、离线报告生成。注意事项：Batch API 官方定价是输入/输出各打五折，适合“对时延不敏感、对成本敏感”的工作负载；对于长文档问答，官方建议把长文档放在前面、问题放在最后、必要时让模型先抽取相关引用再回答，而不是把所有原文直接塞进单轮对话里硬问。

JavaScript

// 场景：Node.js 网关 / BFF / Edge 以外的服务端
// 覆盖：认证、流式输出、取消、重试、会话状态

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxRetries: 2,
  timeout: 60_000,
});

const MODEL = "claude-opus-4-8";

async function runConversation(history, userInput) {
  const stream = client.messages
    .stream({
      model: MODEL,
      max_tokens: 4096,
      system: "你是企业知识库问答助手；不知道就明确说不知道。",
      thinking: { type: "adaptive", display: "summarized" },
      output_config: { effort: "high" },
      cache_control: { type: "ephemeral" },
      messages: [
        ...history,
        { role: "user", content: userInput }
      ],
    })
    .on("text", (text) => process.stdout.write(text));

  const full = await stream.finalMessage();
  return full;
}

async function main() {
  const history = [
    { role: "user", content: "这是第一轮背景信息：我们的系统基于事件总线。" },
    { role: "assistant", content: "收到，请继续。"}
  ];

  const msg = await runConversation(history, "给我设计一个可审计的事件追踪方案。");
  console.log("\nrequestId =", msg._request_id);
}

main().catch(console.error);

适用场景：Node.js 服务端、SSE 转发、前后端分离架构中的后端代理层。注意事项：TypeScript/JavaScript SDK 默认也会对 连接错误、408、409、429、>=500 做指数退避重试；长请求官方建议使用 streaming。浏览器默认禁用该 SDK，只有显式 dangerouslyAllowBrowser: true 才能打开，因为会暴露密钥，不建议直接在前端持有 Anthropic API Key。

// 场景：并发请求
// 说明：对“互不依赖”的请求用 Promise.all；对超大规模离线任务优先 Batch API

async function fanOut(questions) {
  return Promise.all(
    questions.map((q) =>
      client.messages.create(
        {
          model: MODEL,
          max_tokens: 1200,
          messages: [{ role: "user", content: q }],
        },
        { maxRetries: 5 } // 单请求覆盖默认重试
      )
    )
  );
}

适用场景：多个独立查询、批量标签分类、分治式代理步骤。注意事项：Anthropic 官方对大规模批处理提供了单独的 Message Batches API，并且批任务有自己独立的限流模型；如果并发突然飙升，除了普通 429 外，还可能触发 acceleration limits，官方建议逐步升流而不是瞬时打满。

curl

# 场景：最小可复现调试 / CI / shell 脚本
# 注意：Opus 4.8 不要传非默认 temperature / top_p / top_k

curl https://sg.uiuiapi.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 2048,
    "system": "你是一个中文技术文档助手，输出必须结构化。",
    "thinking": {"type": "adaptive", "display": "summarized"},
    "output_config": {"effort": "high"},
    "messages": [
      {"role": "user", "content": "请比较事件驱动与请求驱动架构的适用场景。"}
    ]
  }'

适用场景：故障排查、CI smoke test、平台无 SDK 环境。注意事项：认证核心是 API key；官方 SDK 默认会自动带上 anthropic-version: 2023-06-01，而你在 curl 中需要自己显式补齐。若你在 Opus 4.8 上继续传非默认采样参数，迁移指南明确说明会触发 400 错误。

开发实践与集成指南

Anthropic 官方对 prompt engineering 的建议非常明确：角色放 system，其余大部分业务内容尽量放到首个 user turn；使用 XML tags 分隔 instructions/context/examples/input；针对多文档和长上下文任务，把长文档放前面、查询放后面，并要求模型先引用再回答，通常更稳定。对于复杂任务，官方建议用 3–5 个 few-shot 示例，并用 <examples>/<example> 标签隔离，减少模型把示例误当成当前输入。

一个可落地的提示模板如下。这不是官方逐字模板，而是把 Anthropic 的建议收束成适合生产的通用写法：

<role>
你是企业级知识工作助手，优先保证可验证性、引用与边界说明。
</role>

<instructions>
1. 先判断问题是否需要引用上下文。
2. 若上下文不足，明确指出“不足以判断”。
3. 若上下文充分，先列出依据，再给结论。
4. 输出格式必须为：
   - 结论
   - 关键依据
   - 风险与不确定性
</instructions>

<context>
{{retrieved_documents}}
</context>

<examples>
  <example>
    <input>……</input>
    <output>……</output>
  </example>
</examples>

<input>
{{user_query}}
</input>

如果你需要中途改变策略，例如“从现在开始回答必须是 JSON”或“接下来的 3 轮只做文档抽取不做建议”，在 Opus 4.8 上优先用中途 system 消息，而不是重写整个历史；这样做最大的工程收益，是保住前缀缓存命中。

上图适用于典型企业集成：RAG 做证据召回，Prompt 组装器负责角色/约束/XML 结构，Claude 负责推理与工具规划，工具执行始终放在应用侧受控环境。Anthropic 官方文档把 Tools、Prompt Caching、Batch、Files、MCP 都放在这条链路的不同抽象层上；若是远程工具，TypeScript SDK 还可直接通过 MCP helpers 或 mcp_servers 接入。

上下文保留策略。 Anthropic 官方推荐的主线是：短会话靠完整历史回传 + 自动 prompt caching，长会话靠server-side compaction，再辅以 token counting 预估；extended thinking 的历史思考块会被 Claude API 自动从未来上下文窗口计算中剥离，不需要你手工清理，但在tool use 循环未完成前，相关 thinking block 需要原样保留并回传。

RAG 实践。 Anthropic 文档把 RAG 定义为把外部知识库检索结果送入上下文，以提升事实性和可引用性；同时也提醒，RAG 的效果取决于检索质量，并在法律摘要等场景中建议采用summary-indexed documents / contextual retrieval 这类“先摘要、再排序、再精读”的高级变体。官方没有规定通用 chunk 大小，因此应把 chunking 视为工程参数而非模型参数：最稳妥的做法，是用 语义分段 + count_tokens 预估 + 引用优先回答。

性能 成本 与模型对比

官方定价。 Claude Opus 4.8 标准价为 输入 $5/MTok，输出 $25/MTok；5 分钟缓存写入为 $6.25/MTok，1 小时缓存写入为 $10/MTok，缓存命中/刷新读取为 $0.50/MTok。Fast mode 研究预览价为 $10/$50 per MTok，而 Batch API 价为 $2.50/$12.50 per MTok。Anthropic 还明确说明：1M 长上下文按标准单价计费，没有 long-context premium。

成本估算方法。 一个标准请求的最简公式是：

总成本 = 输入 tokens × 输入单价 + 输出 tokens × 输出单价 + 额外工具成本

若开启 prompt caching，则把输入部分拆成：cache_write + cache_read + uncached_input。Anthropic 官方明确指出：5 分钟缓存只要命中 1 次就回本，1 小时缓存命中 2 次回本；如果你能把长 system prompt、工具 schema、历史对话或大文档前缀缓存起来，成本和 ITPM 压力都能明显下降。

上图假设 100k input + 20k output。按 Opus 4.8 标准价：0.1×5 + 0.02×25 = $1.00；Batch 约为 $0.50；Fast mode 约为 $2.00。这只是单轮估算，未计入工具附加费、缓存读写或数据驻留加价。citeturn35view0turn34view1turn36view0

延迟与吞吐。 官方文档给了 streaming、timeout、keep-alive、fast mode 和 effort 等机制，但没有给出统一的端到端延迟/吞吐 SLA。官方能确认的是：长请求建议使用 streaming；Python/TypeScript SDK 默认超时约 10 分钟，并会在超时后自动重试两次；TypeScript SDK 还会根据大 max_tokens 动态拉长非流式请求的超时上限。第三方 Artificial Analysis 在 “Adaptive Reasoning, Max Effort” 设置下测得，Claude Opus 4.8 的首 token 延迟在不同提供商上约为 Google 7.36s、Amazon 10.31s、Anthropic 20.02s，输出速度约为 60.1–64.4 tokens/s；这些数字更适合作为选型参考，不应直接当成你的生产 SLO。

可得基准。 官方发布页强调 4.8 在编码、代理与知识工作中继续提升，并引用合作方测试数据，例如 Online-Mind2Web 84%、法律代理基准与 Super-Agent 成绩提升等。独立第三方方面，Artificial Analysis 的公开页面显示，Claude Opus 4.8（max）已位居其 Intelligence Index 前列；搜索捕获结果显示其 Intelligence Index 约为 61，并在当天的榜单中与顶级前沿模型并列第一梯队。由于该结果依赖其私有评测方法和具体 effort/provider 配置，建议把它视为横向信号，不要替代你自己的 task-specific eval。

对比表。

开放问题与局限。 这份对比刻意优先采用官方资料，因此有三项内容需要明确标注“未指定”或“不可外推”：4.8 的底层架构细节、4.8 的单独知识截止日期、官方统一延迟/吞吐基线。另外，Anthropic 公告提到了 Claude Opus 4.8 System Card，但公开 system card 索引页截至本文撰写时尚未列出该条目，因此关于 4.8 的完整对齐/安全评估细节，当前公开可检索性仍不完整。

常见问题与故障排查

1. 为什么会报 401 / AuthenticationError？
   常见原因是 ANTHROPIC_API_KEY 未设置、密钥拼写错误，或你把前端浏览器直接暴露成了调用端。优先检查环境变量、服务端代理层，以及是否误把浏览器直连打开了。

2. 为什么 Opus 4.8 一传 temperature=0.2 就 400？
   因为 Anthropic 官方迁移指南明确说明：Opus 4.8 上设置非默认 temperature、top_p、top_k 会返回 400。解决方式是删掉这些字段，改用 thinking={"type":"adaptive"} 与 output_config.effort。

3. 为什么以前的 prefill 技巧在 4.8 上失效？
   因为官方说明 prefill 不支持 Opus 4.8。如果你以前靠预填助手回答来“卡格式”，应改用 structured outputs 或更强的系统/用户模板。

4. 为什么长请求经常超时或挂住？
   官方 SDK 已提示：长请求应优先改成 streaming；非流式、且 max_tokens 很大的请求，SDK 会认为它可能超过默认时限并报错或被中止重试。解决办法是：启用 streaming、增大 timeout、减少单轮输出长度。

5. 为什么明明是多轮对话，模型却“失忆”了？
   因为 Messages API 是 stateless。你必须把完整历史回传；历史里甚至可以包含 synthetic assistant messages。解决办法是自己维护 messages 历史，或结合 prompt caching/compaction 来做长会话管理。

6. 为什么触发 429，即使平均流量不高？
   官方文档说明除了普通 RPM/ITPM/OTPM 外，还可能触发 acceleration limits。如果你的组织突然陡增流量，也会被限。解决办法是遵从 retry-after、做指数退避，并把放量改成渐进升流。

7. 为什么缓存明明开了，成本和延迟却没降？
   常见原因是你修改了缓存层级前面的内容，导致 cache invalidation；或者内容长度没达到模型的最小可缓存门槛。对 Opus 4.8，最小可缓存长度已降到 1,024 tokens，但改变 tools → system → messages 的前缀内容仍会使后续层级失效。

8. 为什么 tool use 成本比预期高？
   因为工具定义、tool_use、tool_result 都会增加 token；服务端工具还可能有附加计费，例如 web search 为 $10 / 1,000 次搜索。解决办法是缩短 tool schema、限制 max_uses、仅在确有必要时开放工具。

9. 为什么会出现 model_context_window_exceeded？
   Claude 4.5+ 在总输入加 max_tokens 超过窗口时，可能会先接受请求，随后在实际生成阶段以 stop_reason: "model_context_window_exceeded" 停止。解决办法是：请求前做 token counting，接近上限时启用 compaction、删旧 tool results、减少冗余历史。

10. 为什么流式输出中断后不能像以前那样无缝恢复？
    Anthropic 文档指出，对 Claude 4.6+ 的流恢复策略，应在新请求里加一个用户消息，提示“上一条响应被中断，请从这里继续”；不能再简单地把半截回答塞成新的 assistant 前缀。

11. 为什么 Debug 日志里出现敏感内容？
    TypeScript SDK 明确提醒：debug 级别会记录 HTTP 请求和响应，请求/响应体中的敏感数据可能可见。解决办法是生产环境默认 warn 或 error，并对日志系统做脱敏。

12. 为什么 Files API 在某些平台不可用？
    官方文档说明 Files API 可用于 Claude API、Claude Platform on AWS 和 Microsoft Foundry，但当前不支持 Amazon Bedrock 或 Vertex AI。若你是多云部署，要把上传与文件引用能力视为平台差异项。

安全 合规 与隐私

密钥与客户端边界。 最基本也最容易犯错的一条，是 Anthropic API Key 必须只存在于服务端。Python SDK 文档建议使用 .env / python-dotenv，TypeScript SDK 则默认禁用浏览器使用，并明确把开启浏览器支持命名成 dangerouslyAllowBrowser，就是在提醒你：API Key 暴露前端通常不是可接受的生产形态。

数据保留。 Anthropic 对 Claude API 提供 Zero Data Retention 选项：在 ZDR 安排下，客户数据在响应返回后不做静态存储，除非法规要求或为打击滥用所必需。官方同时强调：Messages API 与 Token Counting API 属于 ZDR 覆盖范围；但 Console/Workbench、Claude Managed Agents、消费者产品界面，以及第三方站点/第三方工具链，并不自动落入 ZDR 保护范围。更重要的是，即便是 ZDR/HIPAA 场景，若触发政策违规调查或法律要求，输入与输出仍可能被保留最长 2 年。

合规与 PHI。 对需要处理受保护健康信息的组织，Anthropic 提供 HIPAA-ready API access 与 BAA；但官方也划定了边界：HIPAA readiness 不覆盖 Claude consumer products、Console/Workbench、Bedrock、Vertex AI、Claude Platform on AWS、Microsoft Foundry、Claude Code，且很多 beta 特性默认不在 BAA 范围内。另一个容易忽略的约束是：如果你使用 structured outputs 或 strict: true 工具模式，JSON schema 会被单独编译和缓存；Anthropic 明确要求不要把 PHI 写进 schema 本身，PHI 只应出现在 message content 中。

输出审查建议。 Anthropic 的 guardrails 文档建议采用多层防御：用轻量模型做无害性预筛、对 jailbreak/prompt injection 做输入验证、在 system prompt 里强化伦理/法律边界、对滥用用户做节流或封禁，并持续监测模型输出以做迭代优化。对内容审核类业务，Anthropic 还专门给出了 moderation 指南，强调可以用 LLM 做多语言、可解释、可变更策略的审核，但也提醒：Claude 自身受 AUP 约束，某些高风险内容即便你提示“不要审核”，它也可能仍然拒绝或标记。

安全资质。 Anthropic Trust Center 的公开资源索引显示，官方提供 2025 Type 2 SOC 2 / CSA STAR L2 report、SOC 3 report、ISO 27001 certificate 等合规材料；如果你的采购、法务或安全团队需要证据链，这些材料应通过 Trust Center 或企业流程获取，而不是仅凭营销页说明。

示例工程与部署建议

下面给出一个小型、可生产化改造的示例工程。目标是：用 FastAPI + Anthropic Python SDK + 向量检索 + Prompt Caching + Streaming 做一个面向内部知识库的“严谨问答助手”。

claude-opus-48-rag-assistant/
├─ .env.example
├─ requirements.txt
├─ Dockerfile
├─ docker-compose.yml
├─ app/
│  ├─ main.py              # FastAPI 入口
│  ├─ config.py            # 模型、超时、重试、日志、限流配置
│  ├─ anthropic_client.py  # SDK 封装、request_id、错误映射
│  ├─ prompts.py           # system/user 模板与 XML tags
│  ├─ conversation.py      # 会话历史持久化与中途 system 更新
│  ├─ rag.py               # 检索、重排、引用拼接
│  ├─ caching.py           # cache_control 与命中统计
│  ├─ observability.py     # 指标、追踪、结构化日志
│  └─ schemas.py           # Pydantic 输入输出模型
├─ tests/
│  ├─ test_prompts.py
│  ├─ test_rag.py
│  └─ test_api.py
└─ scripts/
   └─ load_test.py         # 并发压测与成本估算

一个最小服务端入口可以写成下面这样：

# app/main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from app.anthropic_client import ask_with_rag

app = FastAPI()

class ChatReq(BaseModel):
    session_id: str
    query: str

@app.post("/chat")
async def chat(req: ChatReq):
    try:
        return await ask_with_rag(req.session_id, req.query)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

对应的 Claude 封装层建议至少做五件事：记录 _request_id、读取 rate-limit headers、把 429/5xx/timeout 归一化、在长请求中强制 streaming、请求前调用 count_tokens 。这并不是“锦上添花”，而是 Anthropic 官方文档已经明确暴露出来的生产抓手：请求 ID 用于排障，rate-limit headers 用于回退窗口控制，token counting 用于避免窗口溢出。

部署建议。
本地开发阶段建议直接用 docker compose 起一个最小栈，方便做 .env、向量库、日志代理和 API 服务的一致化。云上部署时，如果你的需求是最低接入摩擦与 Anthropic 特性完整性，优先用 Anthropic Claude API；如果你的组织强依赖特定云账号治理，再考虑 Bedrock/Vertex/Foundry，但要把 1M context、Files API、自动缓存、Fast mode、数据驻留与计费差异作为平台选择矩阵中的显式项。

性能测试与监控指标。
建议把以下指标做成默认面板：p50/p95/p99 TTFT、end-to-end latency、output tokens/s、input/output/cache read/cache write tokens、429/5xx/timeout rate、tool call success rate、refusal rate、model_context_window_exceeded rate、cache hit ratio、cost per request、cost per successful task。其中最关键的三项，是请求级 _request_id、rate-limit 头和cache 命中率：前者用于追支持工单，后两者决定你是否能把 Opus 4.8 跑进“可控成本、可控延迟”的生产区间。

最终建议。
如果你要今天就落地，我建议采用下面的默认策略：
模型 用 claude-opus-4-8；推理 用 thinking: adaptive + effort: high；长响应 一律 streaming；多轮会话 开 cache_control: {"type":"ephemeral"}；大批量离线任务 走 Batch API；动态规则调整 用中途 system 消息；RAG 采用“检索片段 + 先引用后回答”；高风险输出 前后各加一层 guardrail；所有请求 记录 request_id、token、cost 和 retry-after。这样做最符合 Anthropic 官方文档当前暴露出的能力边界，也最符合 Opus 4.8 的工程设计哲学。

版权信息： 本文由界智通(jieagi)团队编写，图片、文本保留所有权利。未经授权，不得转载或用于商业用途。

过去一年，AI Agent 工具越来越多，但真正能长期运行、能记住上下文、能接入消息平台、还能通过 API 对外服务的项目并不多。很多工具更像是一次性的命令行助手：你问一次，它执行一次，任务结束后上下文也随之断开。

Hermes Agent 的定位不太一样。

它更接近一个可以长期驻留在服务器上的 AI Agent Runtime。你可以把它理解为一个“会持续成长的智能体运行时”：它可以在本地终端里运行，也可以部署到 Docker、VPS、服务器或云环境中；它可以通过 CLI/TUI 与用户交互，也可以作为 Gateway 接入 Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Teams 等消息入口；同时，它还提供 OpenAI-compatible API，让外部应用可以像调用模型接口一样调用 Hermes Agent。

从开发者视角看，Hermes Agent 的价值主要体现在三点：

第一，它不是单纯聊天工具，而是整合了模型调用、工具调用、文件操作、终端执行、持久记忆、技能系统和任务调度的完整 Agent 框架。

第二，它天然适合长期任务。通过 sessions、memories、skills、cron、checkpoints 等机制，Hermes Agent 可以把一次次交互沉淀为可复用能力。

第三，它具备比较完整的部署形态。无论你是想在本地快速体验，还是用 Docker Compose 跑在服务器上，甚至进一步接入 API Server、Dashboard、Langfuse 观测链路，都有相对清晰的路径。

截至本文整理时，Hermes Agent 近期版本已经进入 v0.13.x 系列。v0.11.0 之后，项目对 TUI、provider transport、Curator 技能库维护、多 Agent Kanban、Checkpoints、Gateway 会话恢复等能力做了明显增强。换句话说，它已经不只是一个“新鲜玩具”，而是开始向更完整的 Agent 基础设施演进。

二、Hermes Agent 的核心定位

从官方仓库和文档来看，Hermes Agent 的完整定位可以概括为：

一个可长期运行、可自我沉淀技能、可接入多平台、可通过 API 暴露能力的开源 AI Agent 框架。

它并不是传统意义上的 Chat UI，也不是只执行一条命令的 CLI 工具，而是把以下能力组合到了一起：

• Agent Loop：负责核心推理、工具选择和任务执行流程。
• Provider 调度：支持不同模型提供方和 OpenAI-compatible Endpoint。
• Skills：将常见任务沉淀为可复用技能。
• Memory：保存用户偏好、任务上下文和长期记忆。
• Messaging Gateway：接入 Telegram、Discord、Slack 等外部消息平台。
• API Server：提供 /v1/chat/completions、/v1/responses、/v1/models、/health 等接口。
• Cron：支持计划任务和自动化执行。
• Terminal Backend：支持 local、Docker、SSH、Modal、Daytona、Singularity/Apptainer 等执行环境。
• Dashboard：提供 Web 管理和观察入口。

如果用一句更工程化的话来描述：

Hermes Agent 是一个有状态的、单写者优先的 Agent Runtime，而不是一个天然无状态、可随意横向扩展的 API 服务。

这个判断非常重要，因为它会直接影响后面的部署方式、数据目录挂载、容器副本数量和高可用设计。

三、整体架构：从入口到执行再到状态沉淀

Hermes Agent 的架构可以拆成四层来看。

1. 入口层

入口层负责接收用户请求，常见入口包括：

• CLI / TUI：本地终端交互。
• Gateway：接入 Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Teams 等消息平台。
• API Server：对外提供 OpenAI-compatible API。
• Dashboard：Web 端管理和查看。

这意味着 Hermes Agent 不局限于“打开终端问一句”，而是可以变成一个常驻服务，供不同客户端访问。

2. 调度层

调度层是 Hermes Agent 的核心，它负责 session 管理、模型选择、工具调用、审批流程、任务拆解和执行控制。

这里比较关键的是 approval 机制。因为 Agent 可能会调用终端、访问文件、执行命令，如果完全放开会有安全风险。因此 Hermes Agent 提供了 manual、smart、off 等审批模式。生产环境中一般不建议直接关闭审批，而是根据任务风险选择 smart 或更严格的策略。

3. 执行层

执行层决定 Agent 到底在哪里执行命令和工具。常见 backend 包括：

• local：直接在本机执行。
• docker：在容器中执行，更适合隔离环境。
• ssh：连接远程主机执行。
• modal / daytona：适合云沙箱或远程开发环境。
• singularity / apptainer：适合部分科研和 HPC 场景。

对大多数开发者来说，早期体验可以用 local，但生产环境更建议使用 docker backend。原因很简单：Agent 一旦具备终端执行能力，就必须尽量把风险关在可控边界里。

4. 状态层

Hermes Agent 的状态主要保存在 ~/.hermes 或容器内的 /opt/data 中，包括：

~/.hermes/
├── config.yaml      # 非敏感配置
├── .env             # API Key、Token 等敏感变量
├── auth.json        # OAuth 登录信息
├── SOUL.md          # Agent 身份设定
├── memories/        # 长期记忆
├── skills/          # 技能库
├── cron/            # 定时任务
├── sessions/        # 会话记录
├── logs/            # 日志文件
└── state.db         # 运行状态数据库

这个目录可以理解为 Hermes Agent 的“数据大脑”。它保存了配置、记忆、技能、会话和日志，也解释了为什么 Hermes Agent 不适合多个实例同时写同一个数据目录。

一句话总结架构流程：

用户入口 → Session 建立/恢复 → Agent Loop → 模型与工具调用 → 执行后端 → 状态写回 → 响应输出

四、安装方式对比：本地、Docker、源码、Nix 怎么选？

Hermes Agent 支持 Linux、macOS、WSL2、Android/Termux，以及早期 Beta 状态的原生 Windows。实际使用时，不同环境建议选择不同安装方式。

如果只是想快速体验，推荐一行安装脚本。

如果想在服务器上长期运行，推荐 Docker Compose。

如果你是运维或平台团队，想把 Hermes Agent 纳入标准化基础设施，建议优先考虑 Docker Compose 或 NixOS，而不是手动在系统里堆依赖。

五、Linux / macOS / WSL2 快速安装

在 Debian/Ubuntu 环境中，可以先安装常用系统依赖：

sudo apt update
sudo apt install -y git ripgrep ffmpeg

然后执行官方安装脚本：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

安装完成后，建议先跑一遍初始化和检查：

hermes model
hermes tools
hermes doctor

其中：

• hermes model：配置模型 provider 和默认模型。
• hermes tools：选择启用的工具能力。
• hermes doctor：检查当前环境是否完整。

在 WSL2 环境里，如果 systemd 支持不稳定，建议先用前台模式运行：

hermes gateway run

如果需要保持会话，可以配合 tmux 或 screen 使用。

六、Docker 部署：更适合服务器长期运行

Docker 是 Hermes Agent 更适合生产验证的方式。它可以把运行环境、依赖、浏览器工具、Node.js、Python 环境等内容封装起来，减少宿主机差异带来的问题。

1. 创建数据目录

mkdir -p ~/.hermes

2. 首次初始化

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

这一步主要用于初始化模型、工具、Token 和基础配置。

3. 后台运行 Gateway

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

这里有一个非常关键的点：

容器可以删，镜像可以升级，但 /opt/data 里的数据一定要保留。

因为 Hermes Agent 的配置、会话、记忆、技能和日志都在这个目录里。如果没有持久化挂载，容器重建后状态会丢失。

七、Docker Compose 生产起步模板

如果你准备长期运行，建议直接使用 Docker Compose。下面是一份适合作为生产起点的配置：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # API / health
      - "9119:9119"   # dashboard
    volumes:
      - ${HOME}/.hermes:/opt/data
    environment:
      HERMES_DASHBOARD: "1"
      API_SERVER_ENABLED: "true"
      API_SERVER_HOST: "0.0.0.0"
      API_SERVER_KEY: "${API_SERVER_KEY}"
      API_SERVER_CORS_ORIGINS: "https://chat.example.com"
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

启动方式：

docker compose up -d

查看日志：

docker logs -f hermes

健康检查：

curl http://127.0.0.1:8642/health

如果返回类似：

{"status":"ok"}

说明基础服务已经正常运行。

资源建议

根据官方 Docker 文档和实际部署经验，建议资源如下：

如果只是跑聊天和简单工具，2 核 4G 基本够用。如果要跑浏览器自动化、复杂文件操作、长任务和多平台 Gateway，建议至少 4G 内存起步。

八、核心配置文件 config.yaml

Hermes Agent 的配置优先级可以这样理解：

CLI 参数 > config.yaml > .env > 默认值

通常建议：

• config.yaml 放非敏感配置。
• .env 放 API Key、Token、Secret。
• 不要把密钥写进 Git 仓库。

下面是一份偏生产环境的 config.yaml 示例：

model:
  provider: openrouter
  default: anthropic/claude-sonnet-4

terminal:
  backend: docker
  timeout: 180
  docker_run_as_host_user: true
  docker_mount_cwd_to_workspace: false
  docker_forward_env:
    - GITHUB_TOKEN
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

approvals:
  mode: smart
  timeout: 60

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

auxiliary:
  session_search:
    provider: auto
    model: ""
    timeout: 60
    max_concurrency: 2

display:
  language: zh
  streaming: true
  runtime_metadata_footer: true

streaming:
  enabled: true
  transport: edit
  edit_interval: 0.3
  buffer_threshold: 40

security:
  allow_private_urls: false
  tirith_enabled: true
  tirith_fail_open: true
  website_blocklist:
    enabled: true
    domains:
      - "*.internal.company.com"
      - "admin.example.com"

几个重点解释一下。

terminal.backend: docker 表示尽量让命令在容器边界中执行，而不是直接污染宿主机。

approvals.mode: smart 表示危险操作会触发更谨慎的审批逻辑，比完全关闭审批更适合真实环境。

auxiliary.session_search.max_concurrency 可以控制并发摘要或检索任务数量。如果你遇到 provider 429，或者模型服务限流明显，可以适当降低这个值。

security.allow_private_urls: false 很重要。它可以减少 SSRF 风险，避免 Agent 默认访问内网、metadata 地址或私有服务。

九、环境变量配置：把密钥放在 .env

常见 .env 示例：

OPENAI_API_KEY=sk-你的-uiuiapi-key
OPENAI_BASE_URL=https://sg.uiuiapi.com/v1

# API Server：这是 Hermes Agent 对外暴露的访问密钥，不是模型平台 Key
API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=change-me-very-long-random-string
API_SERVER_CORS_ORIGINS=https://chat.example.com

# Dashboard
HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119

生产环境里，至少要注意三点：

第一，API_SERVER_KEY 不要用弱密码。它相当于你的 Hermes API 访问密钥。

第二，API_SERVER_CORS_ORIGINS 不建议直接放 *。如果你明确知道前端域名，应该写具体域名。

第三，不要直接把 API Server 裸露到公网。更稳妥的做法是放在 Nginx、Traefik、Ingress 或内网网关后面，由反向代理负责 TLS、访问控制和日志审计。

API Key 建议

官方方式（稳妥但稍繁琐）：

1. 访问OpenAI或者Anthropic开发中心注册登录
2. 设置 → 计费，绑定支付方式并小额充值
3. API Keys 页面新建 Key 并立即复制保存

国内开发者推荐：UIUIAPI（uiuiapi.com）
这是我目前使用中最推荐的一站式 AI 模型聚合平台，支持 Claude Opus 4.7 在内的 300+ 主流模型。

核心优势：

• 一个 Key 通吃所有模型，无需多平台切换
• 提供优化节点，国内访问稳定、速度快
• OpenAI 兼容格式，代码几乎零改动
• 按量付费、额度灵活，再也不用担心官方支付和封号问题

UIUIAPI 快速上手：

1. 打开 UIUIAPI 注册
2. 令牌管理 → 新增令牌
3. 复制 sk- 开头的 Key，设置 base_url 为对应节点即可

对国内开发者来说，UIUIAPI 真正做到了“开箱即用”，把gpt-5.5、Claude 4.7 的强大能力变成了日常生产力工具。

十、API Server：把 Hermes Agent 当成模型后端调用

Hermes Agent 的一个实用能力是 API Server。开启后，可以通过 OpenAI-compatible API 调用它。

最小调用示例：

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      {"role": "user", "content": "请总结最近 10 行系统日志"}
    ],
    "stream": false
  }'

查询模型列表：

curl http://localhost:8642/v1/models \
  -H "Authorization: Bearer change-me-local-dev"

健康检查：

curl http://localhost:8642/health
curl http://localhost:8642/health/detailed

Python 调用示例：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="change-me-local-dev",
)

resp = client.chat.completions.create(
    model="hermes-agent",
    messages=[
        {"role": "system", "content": "You are a production SRE copilot."},
        {"role": "user", "content": "Summarize current deployment risks."},
    ],
)

print(resp.choices[0].message.content)

这意味着你可以把 Hermes Agent 接入 Open WebUI、LobeChat、LibreChat、AnythingLLM，或者自己的内部运维平台。

不过要注意，Hermes Agent 不是普通 LLM API。它背后可能会调用工具、读写文件、执行终端命令，因此权限边界一定要比普通模型服务更严格。

十一、Gateway 与多平台接入

Hermes Agent 的 Gateway 负责把 Agent 接入外部消息平台。比如你可以让它出现在 Telegram、Discord 或 Slack 中，像团队里的 AI 运维助手一样接受任务。

常用命令包括：

hermes gateway setup
hermes gateway run
hermes gateway status
hermes gateway logs

如果是 Linux 长期运行，可以安装为 service：

hermes gateway install
hermes gateway start
hermes gateway status

如果需要系统级服务：

sudo hermes gateway install --system
sudo hermes gateway start --system

不过，systemd 模式对 PATH、HERMES_HOME、权限和环境变量更敏感。真实服务器中，如果你不想处理这些细节，Docker Compose 往往更省心。

十二、安全基线：不要把 Agent 当普通聊天机器人部署

Hermes Agent 具备工具调用和终端执行能力，因此安全配置非常关键。

1. 优先使用 Docker Backend

相比 local backend，Docker backend 更适合作为生产环境的默认选择。它可以减少 Agent 对宿主机的直接影响，把命令执行放进更可控的容器边界中。

2. 不要开放全局 allow-all

消息平台接入时，建议使用 allowlist 或 pairing 机制。不要为了省事直接把所有用户放开，否则一旦 Bot Token 泄露或入口被撞库，风险会放大。

3. 禁止默认访问内网地址

建议保持：

security:
  allow_private_urls: false

这样可以降低访问内网服务、云厂商 metadata 地址和私有管理后台的风险。

4. API Server 放在反向代理后面

推荐结构：

用户 / 前端应用
    ↓ HTTPS
Nginx / Traefik / Ingress
    ↓ 内网
Hermes Agent API Server

Nginx 负责 TLS、访问日志、限流、IP 白名单和基础认证，Hermes Agent 的 Bearer Key 作为第二层保护。

5. 密钥单独管理

.env 中通常会放模型 API Key、Bot Token、Webhook Secret 等敏感信息。建议：

• 设置合理文件权限。
• 不提交到 Git。
• 生产环境使用 Secret Manager、K8s Secret 或服务器密钥管理工具。
• 定期轮换高权限 Token。

十三、日志与可观测性

Hermes Agent 自带日志能力，常见日志包括：

agent.log
errors.log
gateway.log

可以使用：

hermes logs
hermes logs gateway --since 10m
hermes logs errors --tail 100

如果开启 Dashboard，也可以在 Web 页面查看部分日志和状态。

API Server 提供：

/health
/health/detailed

对于生产环境，可以这样接入监控：

• 用 Prometheus Blackbox Exporter 或其他探测工具监控 /health。
• 用 Fluent Bit / Vector 收集 /opt/data/logs/*.log。
• 对 LLM 调用链路启用 Langfuse，观察 turn、LLM call、tool call。
• 对容器层面监控 CPU、内存、磁盘和重启次数。

需要说明的是，Hermes Agent 当前更偏向 Agent Runtime，并不是开箱即用的完整云原生监控系统。因此 Prometheus、Grafana、ELK 这类平台需要自己做集成。

十四、常见问题排查

1. Docker 部署后 API 访问不了

优先检查：

docker ps
docker logs -f hermes
curl http://127.0.0.1:8642/health

然后检查环境变量：

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642

如果 API Server 仍绑定在 127.0.0.1，容器外可能访问不到。

2. Dashboard 打不开

确认是否开启：

HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119

同时确认 Compose 中映射了端口：

ports:
  - "9119:9119"

3. 工具调用失败

如果 terminal 工具失败，先确认 backend：

hermes config get terminal.backend

如果使用 Docker backend，检查：

docker version
docker ps

如果是权限问题，确认当前用户是否有 Docker 权限。

4. 消息平台收不到回复

常见原因包括：

• Bot Token 错误或过期。
• Webhook 地址外网不可达。
• Gateway 没有运行。
• allowlist / pairing 配置不正确。

建议先看日志：

hermes logs gateway --since 10m

必要时重新执行：

hermes gateway setup

5. systemd service 启动失败

systemd 相关问题通常和 PATH、HERMES_HOME、权限、ExecStart 路径有关。

排查命令：

hermes gateway status
journalctl --user -u hermes-gateway -f

如果你修改过环境变量或安装路径，建议重新安装 service：

hermes gateway install

如果仍然不稳定，生产环境建议切回 Docker Compose。

6. 多个容器共享同一个数据目录后状态异常

这是部署中很容易踩的坑。

Hermes Agent 当前更适合单写者模型，不建议多个 Gateway 容器同时挂载同一个 /opt/data 目录写入。

正确做法是：

一个 profile → 一个数据目录 → 一个 Hermes 实例

如果需要多实例，应该拆成多个 profile 和多个独立目录，而不是多个实例抢同一个状态目录。

十五、生产部署建议

如果要把 Hermes Agent 用在真实团队或业务环境里，建议遵循下面这套基线。

1. 推荐拓扑

Nginx / Traefik
      ↓
Hermes Agent Docker Compose
      ↓
/opt/data 持久化卷
      ↓
日志采集 / Langfuse / 健康检查

2. 不建议一开始就上多副本

很多 API 服务可以直接横向扩展，但 Hermes Agent 不适合这样处理。因为它有会话、记忆、技能、状态数据库等本地状态。

如果确实需要高可用，建议考虑：

• 单主实例 + 数据卷快照。
• Warm Standby，但不要同时写同一目录。
• 多 profile 隔离，每个 profile 独立数据目录。
• 通过上层路由按 profile 分流。

3. 升级前先备份数据目录

升级前建议备份：

tar -czf hermes-backup-$(date +%F).tar.gz ~/.hermes

然后再升级镜像：

docker compose pull
docker compose up -d

升级后验证：

curl http://127.0.0.1:8642/health
curl http://127.0.0.1:8642/v1/models \
  -H "Authorization: Bearer $API_SERVER_KEY"

4. 最小验收清单

上线前建议确认：

• /health 返回正常。
• /v1/models 可以返回模型列表。
• 最小 chat completions 请求可以成功。
• Gateway 日志没有持续报错。
• Dashboard 可访问但不直接裸露公网。
• .env 权限正确，没有进入 Git 仓库。
• API Server 前面有 TLS 和访问控制。
• Docker 数据卷已经持久化。
• 日志和健康检查已经接入监控。

十六、适合哪些应用场景？

Hermes Agent 比较适合以下几类场景。

1. 个人 AI 助手

可以在本地或 VPS 上长期运行，记录项目上下文、常用脚本、个人偏好和操作习惯。

2. 团队运维助手

接入 Slack、Discord、Telegram 或企业内部 IM，让它辅助处理日志摘要、故障初筛、发布检查和自动化任务。

3. 开发者工作流增强

通过 Skills 和 Memory，把代码审查、脚本生成、部署检查、文档整理等任务沉淀成可复用流程。

4. 内部 AI 工具平台后端

开启 API Server 后，可以把 Hermes Agent 接入 Open WebUI、LobeChat、LibreChat 或自研控制台，作为一个具备工具调用能力的 Agent 后端。

5. 自动化任务调度

结合 cron 能力，定时执行日志检查、Issue 摘要、仓库扫描、日报生成等任务。

十七、它不适合什么场景？

为了避免误用，也要明确 Hermes Agent 的边界。

它不适合直接当作无状态高并发模型 API 网关来用。如果你的需求只是转发 OpenAI API、做 Key 管理、计费和限流，那么更适合使用专门的 API Gateway 或模型网关。

它也不适合在没有安全边界的情况下暴露给所有用户。因为 Agent 能调用工具、执行命令、访问文件，一旦权限控制不当，风险远高于普通聊天机器人。

它更不适合多个副本同时写一个数据目录。这样容易导致会话、状态数据库、技能库和日志出现不可预期问题。

更准确的定位是：

Hermes Agent 适合作为一个有状态、可扩展、可学习、可接入外部系统的智能体运行环境。

十八、界智通（jieAGi）总结

Hermes Agent 的吸引力，不在于它又做了一个聊天界面，而在于它把“AI Agent 长期运行”这件事做成了一个比较完整的工程框架。

它有 CLI/TUI，也有 Gateway；有 Memory，也有 Skills；能跑在本地，也能跑在 Docker；能作为个人助手，也能通过 API Server 接入外部系统。对于正在探索 AI Agent 落地的开发者和运维团队来说，它提供了一条很清晰的路线：先从本地体验开始，再用 Docker Compose 跑成常驻服务，最后逐步补上安全、日志、监控、API 接入和自动化任务。

不过，真正部署时一定要记住三个关键点：

第一，Hermes Agent 是有状态的，~/.hermes 或 /opt/data 必须妥善持久化和备份。

第二，它不适合多个实例同时写同一个数据目录，多实例要通过 profile 和数据目录隔离。

第三，它具备工具调用和终端执行能力，安全边界必须比普通 LLM API 更严格。

如果你只是想尝鲜，可以从一行安装脚本开始。如果你想长期稳定运行，Docker Compose 会是更稳妥的起点。如果你希望把它纳入团队内部 AI 工具链，那么 API Server、Gateway、日志采集、Langfuse 和反向代理安全策略，应该一起规划。

Hermes Agent 仍在快速迭代，但它已经展现出一个值得关注的方向：AI Agent 不再只是一次性对话工具，而是在逐步变成可以部署、可以维护、可以观测、可以持续成长的工程化系统。

GPT-5.5 是 OpenAI 在 GPT-5 系列上的一次重要升级。根据 OpenAI 官方介绍，GPT-5.5 被定位为面向“真实工作”的新一代智能模型，重点不是单纯做聊天，而是更好地完成代码编写、在线研究、信息分析、文档生成、表格处理，以及跨工具执行复杂任务。

简单理解，GPT-5.5 的核心变化可以概括为一句话：

GPT-5.5 不只是更会回答问题，而是更适合承担复杂、连续、多步骤的实际工作。

这也是 GPT-5.5 与早期通用聊天模型最大的区别。以前我们更多把大模型当成“问答助手”，而 GPT-5.5 更接近“任务型智能代理”的底座模型：它需要理解目标、拆解任务、调用工具、检查结果，并在必要时持续推进。

2. GPT-5.5 的核心能力升级

2.1 更强的代码与工程任务能力

OpenAI 官方评测中，GPT-5.5 在多项代码相关基准上相比 GPT-5.4 有提升。例如在 Terminal-Bench 2.0 中，GPT-5.5 得分为 82.7%，高于 GPT-5.4 的 75.1%；在 SWE-Bench Pro Public 中，GPT-5.5 为 58.6%，略高于 GPT-5.4 的 57.7%。

这类提升对于开发者非常关键，因为真实开发任务往往不是“写一个函数”这么简单，而是包括：

• 理解项目结构；
• 修改多文件代码；
• 排查报错；
• 分析日志；
• 生成测试用例；
• 优化接口调用；
• 编写部署脚本；
• 解释第三方 SDK 使用方式。

对于 AI 编程工具、代码助手、自动化测试平台、企业内部 DevOps Agent 来说，GPT-5.5 更适合作为复杂任务执行模型。

2.2 更适合办公、文档和表格场景

GPT-5.5 的另一个重点是“真实办公生产力”。OpenAI 官方将其能力覆盖到创建文档、分析信息、生成表格、处理复杂办公任务等场景。官方评测显示，GPT-5.5 在 GDPval、Investment Banking Modeling Tasks、OfficeQA Pro 等专业任务上相比 GPT-5.4 有不同程度提升。

这意味着 GPT-5.5 不只是给你一段文字，而是更适合做完整工作流，例如：

• 根据资料生成一份分析报告；
• 把会议纪要整理成行动项；
• 分析 Excel / CSV 数据；
• 生成销售方案或项目方案；
• 根据业务需求生成 PRD；
• 辅助财务建模和投资分析；
• 根据长文档提炼重点并生成结构化摘要。

对于企业用户来说，这类能力比单纯“聊天更聪明”更有价值。

2.3 工具调用与 Agent 能力增强

GPT-5.5 官方介绍中多次强调“real work”“tools”“computer use”等关键词。OpenAI 的系统卡也提到，GPT-5.5 相比早期模型更能理解任务、更少依赖用户反复指导、更有效使用工具，并能检查工作、持续推进直到完成。

这点对开发者尤其重要。未来使用 GPT-5.5 构建应用时，不应该只把它当成一个文本生成模型，而应该把它设计成一个可以连接工具的智能控制层。

典型架构可以是：

用户自然语言需求
        ↓
GPT-5.5 理解与任务拆解
        ↓
调用工具 / API / 数据库 / 搜索 / 文件系统
        ↓
模型检查中间结果
        ↓
生成最终答案或执行下一步操作

比如：

• 接入 CRM：自动生成客户跟进方案；
• 接入数据库：把自然语言转成 SQL 并解释结果；
• 接入浏览器自动化：完成后台录入、表单填写；
• 接入代码仓库：分析 Issue、生成 Patch；
• 接入文档系统：自动生成知识库文章。

3. GPT-5.5 API 是否已经开放？

根据 OpenAI 官方 2026 年 4 月 24 日更新，GPT-5.5 和 GPT-5.5 Pro 已经可在 API 中使用。官方说明中提到，gpt-5.5 支持 Responses API 和 Chat Completions API，标准价格为每 100 万输入 tokens 5 美元、每 100 万输出 tokens 30 美元；gpt-5.5-pro 面向更高准确率任务，价格为每 100 万输入 tokens 30 美元、每 100 万输出 tokens 180 美元。

可以简单理解为：

对于普通开发者，建议优先从 gpt-5.5 开始。如果是法律、金融、科研、复杂代码审查、企业级高价值决策辅助，再考虑 gpt-5.5-pro。

4. OpenAI API Key 获取方法

要调用 GPT-5.5 API，首先需要获取 OpenAI API Key。

根据 OpenAI 帮助中心说明，用户可以在 OpenAI Developer Platform 的 API Keys 页面创建新的 Secret Key。创建后需要立即保存，因为出于安全原因，密钥通常不会再次完整显示；如果丢失，需要重新生成。

获取步骤

1. 登录 OpenAI 开发者平台；
2. 进入 API Keys 页面；
3. 点击 Create new secret key；
4. 选择对应项目；
5. 创建并复制 API Key；
6. 将 Key 保存到安全位置；
7. 在本地环境变量中配置 OPENAI_API_KEY。

注意：不要把 API Key 直接写进前端代码、GitHub 仓库、公开文章或截图中。

OpenAI 官方也提醒，不要与任何人共享 API Key；如果 API Key 泄露，可能导致账户额度被滥用、产生异常费用，甚至影响应用正常运行。

5. 配置环境变量

Windows PowerShell

setx OPENAI_API_KEY "你的_api_key"

设置完成后，关闭当前终端，重新打开 PowerShell，再测试：

echo $env:OPENAI_API_KEY

Windows CMD

setx OPENAI_API_KEY "你的_api_key"

重新打开 CMD 后测试：

echo %OPENAI_API_KEY%

macOS / Linux

如果你使用 zsh：

echo "export OPENAI_API_KEY='你的_api_key'" >> ~/.zshrc
source ~/.zshrc
echo $OPENAI_API_KEY

如果你使用 bash：

echo "export OPENAI_API_KEY='你的_api_key'" >> ~/.bashrc
source ~/.bashrc
echo $OPENAI_API_KEY

OpenAI 官方也推荐使用环境变量方式引用 API Key，而不是硬编码在代码中。

6. GPT-5.5 API 调用示例

下面给出几种常见调用方式。

6.1 使用 curl 调用 GPT-5.5

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "input": "请用通俗语言解释 GPT-5.5 相比 GPT-5.4 的主要升级点。"
  }'

如果你在 Windows PowerShell 中使用，可以写成：

curl https://api.openai.com/v1/responses `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer $env:OPENAI_API_KEY" `
  -d '{
    "model": "gpt-5.5",
    "input": "请用通俗语言解释 GPT-5.5 相比 GPT-5.4 的主要升级点。"
  }'

6.2 Python 调用示例

先安装 SDK：

pip install openai

然后创建 gpt55_demo.py：

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    input="请写一段 300 字左右的 GPT-5.5 模型介绍，面向开发者。"
)

print(response.output_text)

运行：

python gpt55_demo.py

如果出现 API Key 相关报错，优先检查：

echo $OPENAI_API_KEY

Windows PowerShell：

echo $env:OPENAI_API_KEY

6.3 Node.js 调用示例

先安装 SDK：

npm install openai

创建 gpt55_demo.js：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "请用表格对比 GPT-5.5 和 GPT-5.4 的主要区别。",
});

console.log(response.output_text);

运行：

node gpt55_demo.js

如果你的项目没有启用 ES Module，可以在 package.json 中加入：

{
  "type": "module"
}

6.4 Chat Completions 风格调用示例

如果你的旧项目仍然基于 Chat Completions 格式，也可以使用类似方式：

from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "system",
            "content": "你是一名专业的 AI 技术文章编辑。"
        },
        {
            "role": "user",
            "content": "帮我写一段 GPT-5.5 API 的开发者介绍。"
        }
    ]
)

print(completion.choices[0].message.content)

不过对于新项目，建议优先考虑 Responses API，因为它更适合多模态、工具调用、Agent 和复杂工作流场景。

7. 通过 uiuiAPI 接入 GPT-5.5

对于很多开发者来说，直接使用 OpenAI 官方 API 虽然标准、稳定，但在实际开发中也会遇到一些问题：

• 官方 API Key 获取门槛较高；
• 支付方式、账单管理不够方便；
• 多模型切换成本高；
• 同时接入 GPT、Claude、Gemini、DeepSeek 等模型时，需要维护多套 SDK 和接口格式；
• 国内网络环境下，接口可用性和稳定性需要额外处理；
• 不同模型的参数格式、错误返回、价格统计方式不一致。

这也是很多开发者会选择 API 聚合站 的原因。

7.1 uiuiAPI 是什么？

uiuiAPI 可以理解为一个面向 AI 开发者的多模型聚合 API 服务。它的核心价值不是简单“转发请求”，而是帮助开发者把多个大模型统一到一套更容易接入的接口规范下。

通过 uiuiAPI，开发者可以在一个平台中接入多种模型能力，例如：

• GPT-5.5；
• GPT-image-2；
• Claude Opus / Sonnet 系列；
• Gemini 系列；
• DeepSeek 系列；
• 其他 OpenAI 兼容模型；
• 图像生成模型；
• 多模态模型；
• 文本生成与代码生成模型。

对于开发者来说，最大的好处是：不用为每一个模型单独写一套调用逻辑。

7.2 为什么开发者适合使用 uiuiAPI？

如果你只是测试一个官方模型，直接使用 OpenAI 官方 API 就可以。

但如果你正在做真实项目，例如 AI 工具站、AI 写作平台、AI 编程助手、AI 绘图平台、智能客服系统、企业自动化 Agent，那么聚合 API 的优势会更明显。

第一，统一接口，降低开发成本

很多聚合站会尽量兼容 OpenAI API 格式。这样一来，你原本基于 OpenAI SDK 写好的项目，只需要修改：

base_url
api_key
model

就可以切换到不同模型。

这对开发者非常友好，因为不用重构整个项目。

第二，多模型自由切换

真实业务中，不同模型适合不同任务：

如果每个模型都单独接入，维护成本会很高。

而通过 uiuiAPI 这类聚合站，可以把模型选择变成一个参数：

{
  "model": "gpt-5.5",
  "messages": []
}

当你想切换模型时，只需要替换 model 字段即可。

第三，适合商业化 AI 工具站

如果你正在做 AI 工具站，聚合 API 的价值会更明显。

例如你的网站提供这些功能：

• AI 聊天；
• AI 写作；
• AI 编程；
• AI 绘图；
• PPT 大纲生成；
• 小红书文案生成；
• 电商图生成；
• SEO 文章生成；
• 企业知识库问答。

这类产品通常不会只依赖一个模型，而是需要根据任务类型动态分配模型。

例如：

普通文案 → 低成本模型
技术文章 → GPT-5.5
复杂代码 → GPT-5.5 / Claude
图片生成 → GPT-image-2
长文档分析 → Gemini / Claude
中文高性价比任务 → DeepSeek

通过 uiuiAPI，可以更方便地搭建这种多模型调度能力。

8. uiuiAPI 调用 GPT-5.5 示例

下面给一个 OpenAI 兼容格式的示例。实际使用时，将接口地址替换为你的 uiuiAPI 聚合站地址即可。

8.1 curl 调用示例

curl https://你的-uiuiapi-地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的_uiuiAPI_key" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "system",
        "content": "你是一名专业的 AI 技术文章编辑。"
      },
      {
        "role": "user",
        "content": "请写一段 GPT-5.5 模型介绍，面向开发者。"
      }
    ]
  }'

如果你的聚合站兼容 OpenAI 格式，那么前端或后端原来的 OpenAI 调用逻辑通常只需要改两个地方：

base_url = https://你的-uiuiapi-地址/v1
api_key = 你的_uiuiAPI_key

8.2 Python 调用 uiuiAPI

from openai import OpenAI

client = OpenAI(
    api_key="你的_uiuiAPI_key",
    base_url="https://你的-uiuiapi-地址/v1"
)

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "system",
            "content": "你是一名专业的 AI 技术文章编辑。"
        },
        {
            "role": "user",
            "content": "请用通俗语言介绍 GPT-5.5 的核心能力。"
        }
    ]
)

print(completion.choices[0].message.content)

8.3 Node.js 调用 uiuiAPI

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "你的_uiuiAPI_key",
  baseURL: "https://你的-uiuiapi-地址/v1",
});

const completion = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    {
      role: "system",
      content: "你是一名专业的 AI 技术文章编辑。",
    },
    {
      role: "user",
      content: "请生成一段 GPT-5.5 API 的开发者介绍。",
    },
  ],
});

console.log(completion.choices[0].message.content);

9. 官方 OpenAI API 与 uiuiAPI 怎么选？

官方 API 和聚合 API 并不是完全替代关系，而是适合不同场景。

简单来说：

如果你追求官方原生能力、企业合规和长期稳定，优先选择 OpenAI 官方 API。
如果你需要多模型统一接入、快速开发 AI 工具站、降低切换成本，可以考虑 uiuiAPI 聚合站。

10. uiuiAPI 适合哪些项目？

10.1 AI 工具导航站 / AI 应用站

如果你的网站同时提供 AI 聊天、AI 绘图、AI 文案、AI 编程、AI 翻译等能力，那么 uiuiAPI 很适合作为统一接口层。

典型架构：

用户请求
  ↓
你的 AI 工具站
  ↓
任务分类器
  ↓
uiuiAPI 聚合接口
  ↓
GPT / Claude / Gemini / DeepSeek / 图像模型
  ↓
返回结果给用户

10.2 企业内部 AI 助手

企业内部助手通常会同时需要：

• 文档问答；
• 报表分析；
• 客服工单；
• 代码辅助；
• 日报周报；
• 知识库检索；
• 多语言翻译。

这些任务很难只靠一个模型全部解决。通过 uiuiAPI，可以根据任务类型选择更合适的模型，提升整体性价比。

10.3 AI 绘图与多模态平台

如果你的平台包含图片生成能力，可以在文本模型之外接入 GPT-image-2 等图像模型。

例如：

{
  "model": "gpt-image-2",
  "prompt": "生成一张 OpenAI 风格的科技渐变背景，右下角带 uiuiAPI 水印",
  "size": "1024x1024"
}

这类功能非常适合做：

• 电商主图生成；
• 社媒海报；
• AI 头像；
• 产品宣传图；
• 知识付费封面；
• 技术文章配图。

11. 接入 uiuiAPI 时的注意事项

虽然聚合 API 很方便，但在真实项目中也要注意几个问题。

11.1 不要把 API Key 放在前端

错误示例：

const apiKey = "sk-xxxx";

正确做法是：

前端 → 你的后端 → uiuiAPI

也就是说，前端只请求你自己的后端接口，由后端保存和调用 API Key。

11.2 做好用户额度限制

如果你做的是商业站点，一定要限制用户使用额度，例如：

• 每日请求次数；
• 每次最大 tokens；
• 图片生成次数；
• 并发限制；
• 失败重试次数；
• 不同会员等级调用不同模型。

否则很容易出现成本失控。

11.3 记录模型调用日志

建议记录这些信息：

用户 ID
请求时间
调用模型
输入 tokens
输出 tokens
调用状态
接口耗时
错误原因
估算成本

这对后期做会员套餐、成本分析、异常排查非常重要。

11.4 做模型降级策略

真实业务中，接口偶尔可能失败。建议设计降级方案：

GPT-5.5 调用失败
  ↓
自动切换 GPT-5.5 mini / Claude / DeepSeek
  ↓
返回结果或提示用户稍后重试

这样可以提高用户体验，避免单点模型不可用导致整个服务不可用。

界智通（jieAGi）总结：GPT-5.5 不只是模型升级，更是 AI 应用开发的新底座

GPT-5.5 的价值，不只是回答更准确、代码能力更强，而是更适合作为复杂 AI 应用的核心模型底座。它可以用于 AI 编程、企业知识库、办公自动化、Agent 工作流、多工具调用、长文档分析等场景。

对于开发者来说，接入 GPT-5.5 有两条路线：

第一条是直接使用 OpenAI 官方 API，适合追求官方原生体验、企业级合规和稳定性的项目。

第二条是通过 uiuiAPI 接入，适合需要多模型统一管理、快速开发 AI 工具站、同时支持 GPT、Claude、Gemini、DeepSeek、图像模型等能力的开发者。

如果你只是做简单 Demo，官方 API 足够使用。
但如果你要做真正可商业化的 AI 产品，例如 AI 写作平台、AI 绘图站、AI 编程助手、智能客服、知识库问答、自动化 Agent，那么 uiuiAPI 这类聚合接口可以显著降低接入成本，提高模型切换灵活性，并帮助你更快完成产品闭环。

最终，GPT-5.5 代表的是模型能力的提升，而 uiuiAPI 解决的是工程接入和商业落地的问题。两者结合，才是开发者真正可以拿来构建 AI 应用的完整方案。

一、先说结论：GPT Image 2 值不值得用

从官方定位看，gpt-image-2 的核心价值不是“单纯出图”，而是更偏向 生产级图像生成与编辑。OpenAI 官方给出的重点包括：更强的指令遵循、更好的文本渲染、更适合多步骤编辑工作流、支持高保真输入图，以及更灵活的尺寸与质量控制。对于需要做电商图、营销图、带文字海报、角色一致性图、局部修改图的人来说，这一代明显比“只会生图”的旧思路更实用。

如果你的需求只是“一句话随便出张图”，Images API 足够；如果你要做“先上传图，再让模型多轮修改，再生成最终图”的产品形态，Responses API 更适合。官方文档也明确给了这两个方向的选择建议：单次生成/编辑选 Image API，多轮可编辑体验选 Responses API。

二、GPT Image 2 到底是什么

官方模型页显示，gpt-image-2 支持 文本输入、图片输入，图片输出；可用于 v1/images/generations、v1/images/edits，也可用于 v1/responses 等端点。与此同时，官方还给出了当前快照版本 gpt-image-2-2026-04-21，说明它已经进入正式可调用状态，而不是仅在 ChatGPT 内部可见。

更重要的是，OpenAI 最新图片指南已经把它列为 最新的 GPT Image 模型，并指出它可通过两套 API 访问：一套是传统的 Image API，一套是更适合会话式、多步骤图像工作流的 Responses API。

三、GPT Image 2 的核心能力，强在哪

1）文本渲染比过去更值得期待

OpenAI 在最新的 ChatGPT Images 2.0 介绍中，反复强调了 improved text rendering 和 multilingual support。这意味着做中文海报、宣传图、对比图、说明图时，模型在“图里带字”这个过去最容易翻车的地方，官方已经把它作为主打能力在推。

2）编辑能力比“重画一张”更重要

官方文档明确写到，gpt-image-2 不只是生成，还强调 editing。Image API 里有专门的 edits 端点；Responses API 还支持多轮高保真编辑，并且能接受 file ID 作为输入，不必每次都重新上传原始字节流。对做产品的人来说，这意味着你可以把“上传原图 → 局部修改 → 再调风格 → 最终导出”做成一条完整链路。

3）尺寸更自由，不再只盯着 1024

官方图片生成指南写得很明确：gpt-image-2 的 size 参数支持更灵活的分辨率，只要满足约束即可。文档列出的常见尺寸包括 1024x1024、1536x1024、1024x1536、2048x2048、3840x2160、2160x3840，而且还支持 auto。这对做电商主图、详情页长图、竖版封面、横版横幅都很实用。

4）质量与时延可以做平衡

官方 Prompting Guide 提到，这一代模型既支持高保真输出，也支持 quality-latency tradeoff。其中 low 更适合低延迟场景，medium 和 high 更适合追求成片质量的场景。对于业务系统来说，这意味着你可以把“预览图”和“正式出图”拆成两档。

四、开发前先搞明白：Image API 和 Responses API 怎么选

Image API 更像传统工具接口：你发一个 prompt，它回你图片；或者你上传图，再让它编辑。它适合做批量海报生成、商品图生成、模板化图片服务。官方说明中，gpt-image-1 及之后的模型都支持 generations 和 edits 两个核心端点。

Responses API 更像“会话式多模态工作流接口”。你可以在一个请求或多轮上下文里同时处理文本、图片输入和图片输出，还可以把图像生成作为工具来调用。官方明确写到，这一套更适合 multi-turn editing 和更灵活的输入方式。

实战上可以这么理解：

• 做“给我一句 prompt，返回一张图”服务，用 Image API。
• 做“设计助手 / 营销图编辑器 / 上传原图反复改”产品，用 Responses API。

五、OpenAI API Key 怎么获取

官方帮助中心给出的路径很直接：到 OpenAI Developer Platform 的 API Keys 页面 创建 Secret API key。官方还说明了，创建后可以进一步编辑权限。

一般流程可以写成这样：

1. 注册并登录 OpenAI Developer Platform。
2. 进入 API Keys 页面。
3. 点击 Create new secret key 创建新 key。
4. 按需设置权限，常见有 All、Restricted、Read Only。
5. 到 Billing 页面绑定支付方式或充值 credits。官方说明 API 预付费最低可先充 5 美元，并支持自动充值；已购 credits 1 年后过期且不可退款。

国内开发者获取API：UIUIAPI （国内/亚太最佳选择）

OpenAI 帮助中心写得很直接：Secret API key 可以在 API key page 获取，或者 uiuiAPI 对于国内开发者及亚太地区开发者，是目前最便捷、高性价比的gpt-image-2API 接入方案。支持 OpenAI（ gpt-image-2 ）、Claude（含 Opus 4.7）、Gemini、DeepSeek等主流模型。

UIUIAPI 获取 API Key 步骤：

1. 访问 uiuiapi 注册登录。
2. 进入令牌管理 → 添加新令牌（设置额度）。
3. 复制生成的 sk- 开头 API Key。
4. 在代码中设置 base_url 为 https://uiuiapi.com（或官方提供的节点）。

六、拿到 Key 后，先注意这几个安全点

这部分很重要，很多人一上来就把 key 写到前端页面里，风险很大。OpenAI 官方安全建议写得非常明确：

• 不要共享 API key，每个成员都应使用自己的 key。
• 不要把 key 部署到浏览器端或移动端，否则别人可以直接盗用你的 key 代你调用，带来异常扣费和数据风险。
• 不要把 key 提交进 Git 仓库。
• 优先用环境变量，官方推荐变量名就是 OPENAI_API_KEY。

一句话总结：前端只调你自己的后端，你的后端再调 OpenAI。

七、最简单的开发调用示例

示例 1：Python 生成图片

这是官方文档思路的标准写法，适合快速跑通。

import base64
from openai import OpenAI

client = OpenAI()  # 默认从环境变量 OPENAI_API_KEY 读取

prompt = """
一张高质感的电商产品海报：
主体是一瓶极简风玻璃精华液，
背景是米白色高级棚拍风，
画面中加入柔和高光、产品倒影、简洁排版留白，
右下角预留文案区。
"""

result = client.images.generate(
    model="gpt-image-2",
    prompt=prompt,
    size="1024x1536",
    quality="high"
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

with open("serum-poster.png", "wb") as f:
    f.write(image_bytes)

print("图片已保存为 serum-poster.png")

示例 2：curl 直接调用 Images API

官方文档已经给出了 v1/images/generations 的 curl 示例，核心结构就是这样。

curl -X POST "https://api.openai.com/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张适合科技产品发布会的方形视觉海报，深色背景，发光线条，中央是未来感芯片，标题留白明显。",
    "size": "1024x1024",
    "quality": "medium"
  }'

示例 3：Python 做图片编辑

如果你不是“从零生图”，而是“拿现有图改图”，那就该用 images.edit。官方文档确认 gpt-image-2 支持图片编辑与 mask 编辑。

import base64
from openai import OpenAI

client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=open("input.png", "rb"),
    prompt="保持主体构图不变，把背景改成高级感的浅灰摄影棚，并增强产品边缘光。"
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

with open("edited.png", "wb") as f:
    f.write(image_bytes)

print("编辑后的图片已保存为 edited.png")

示例 4：Node.js 走 Responses API，适合做会话式图片助手

官方文档给出的 Responses 思路是：调用 responses.create，并启用 image_generation 工具。这样很适合你做“一个聊天框，既能描述需求又能出图”的产品形态。

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await openai.responses.create({
  model: "gpt-4.1-mini",
  input: "生成一张方形运营海报：主题是 AI 效率工具，蓝白科技风，画面里要有仪表盘、数据面板和产品标题留白。",
  tools: [{ type: "image_generation", quality: "high" }],
});

console.log(response);

这里要注意一点：在 Responses API 里，负责调用图片生成工具的主模型 可以是文本模型，而图片生成由内置 image generation tool 完成。官方文档就是这样演示的。

八、可调参数有哪些

官方指南里比较关键的输出参数有这些：

• size：控制输出尺寸，如 1024x1024、1024x1536、3840x2160 等。
• quality：控制渲染质量，如 low、medium、high，也支持 auto。
• format：控制输出文件格式。
• compression：JPEG / WebP 可调压缩率。
• background：可控制背景表现，部分模型支持透明背景相关能力，具体要看模型支持情况。

如果你做生产环境，推荐策略是：

• 首屏预览：quality=low 或 medium
• 最终导出：quality=high
• 电商竖图：1024x1536
• 横版封面：1536x1024 或更高横向分辨率。

九、成本怎么理解

OpenAI 官方 API Pricing 页面已经列出了 gpt-image-2 的价格。当前标准计费中，它区分 Image 输入、Cached input、Output，同时也区分 Text 输入。官方还特别提示：图片生成成本建议结合图片生成指南中的 calculator 来估算。

你不用死记每个数字，更应该理解两个点：

第一，图像生成不是按“几张图多少钱”这种老思路简单计算，而是按模型输入/输出 token 等机制计费。

第二，如果你是产品方，影响成本的关键变量通常是：

• 生成分辨率
• 是否多轮编辑
• quality 档位
• 用户是否频繁重试
• 是否用低质预览 + 高质导出的两阶段方案。
  这些都会直接影响最终费用。

十、常见坑点

1）把 ChatGPT 订阅当成 API 权限

ChatGPT 订阅和 API 平台计费不是一回事。API 需要你到平台侧创建 key，并在 Billing 里完成支付设置或充值。

2）把 key 直接写到前端

这是最危险也最常见的问题。官方明确不建议在浏览器或移动端直挂 key。

3）一上来就做高质量大图

虽然 gpt-image-2 支持更高分辨率，但官方也提到方图通常更快，且质量档位会影响时延。很多业务更适合先出预览，再导出成片。

4）忽略组织验证

官方图片生成指南提到，使用 GPT Image 系列模型前，你可能需要完成 API Organization Verification。这点很容易被忽视，结果就是明明代码没问题，却发现权限没开全。

十一、谁适合用 GPT Image 2

如果你是下面几类人，gpt-image-2 会比传统“提示词画图工具”更有价值：

• 做 SaaS 产品、想接入 AI 出图能力的开发者。
• 做运营设计、电商海报、营销图、社媒图的人。文本渲染和版式能力更关键。
• 做图片编辑器、商品换背景、局部修图产品的人。
• 想把“聊天 + 修图 + 出图”融合到一个工作流里的团队。

十二、界智通（jieAGi）最后总结

如果把这一代模型一句话概括，我会这么写：

GPT Image 2 不只是更会画图，而是更像一个能进入生产流程的图片生成与编辑引擎。 它的真正价值，在于更强的文本渲染、更实用的图像编辑、更灵活的尺寸/质量控制，以及 Image API 与 Responses API 两条路线带来的开发自由度。官方文档也已经明确：gpt-image-2 是 OpenAI 当前主推的最新 GPT Image 模型，可用于生成和编辑图片。

如果你要写教程，文章结构最稳的方式就是：先讲模型价值，再讲 key 获取，再讲 API 选型，最后给出 Python / curl / Node.js 三套示例。这样既有搜索流量，也更符合开发者阅读习惯。

版权信息： 本文由界智通(jieagi)团队编写，图片、文本保留所有权利。未经授权，不得转载或用于商业用途。

1. 模型核心规格（一目了然）

• 模型 ID：claude-opus-4-7
• 上下文窗口：1M tokens（100 万）
• 最大输出：128k tokens
• 定价：输入 $5 / 百万 tokens，输出 $25 / 百万 tokens
• 知识截止：2026 年 1 月
• 核心能力：文本 + 高分辨率图像、工具调用（Tool Use）、自适应思考（Adaptive Thinking）、Prompt Caching、结构化输出、Memory Tool、Task Budgets
• 可用平台：Claude API、Amazon Bedrock、Google Vertex AI、Microsoft Foundry

2. 深度解析：Opus 4.7 到底强在哪儿？

Opus 4.7 的核心升级不是参数堆叠，而是自主性与可靠性的质变。用户实测反馈：以前需要“密切监督”的复杂编码工作，现在可以放心交给它独立完成。

主要提升亮点：

• 高级软件工程 / Agentic Coding：自主规划、验证输出、自修复代码，处理长时程多步任务几乎不半途而废。
• 视觉能力：首次支持高分辨率（最大 2576px 长边 / 3.75MP，较前代提升 3 倍以上），显著提升截图、文档、图表、UI 设计等视觉密集任务表现。
• 指令遵循与可靠性：严格按字面执行提示，更诚实、少幻觉，会主动报告自身局限性。
• 长时程 Agentic 任务：新增 xhigh 努力等级 + Task Budgets Beta，模型可自我监控 token 消耗，适合无人值守长时间运行。
• 其他：专业输出更具品味，文件系统级 Memory 更强，内置实时网络安全防护（保留合法红队测试通道）。

一句话总结：Opus 4.7 是“让 AI 真正能独立干活”的质变模型，尤其适合复杂编码、Agent 开发、长文档分析和高精度视觉场景。

3. 基准测试详解（2026年4月最新官方+第三方数据）

Opus 4.7 在编码、Agentic 工具使用、计算机使用、视觉和长上下文可靠性上实现针对性跃升。以下为按场景分类的核心基准对比（数据来源于 Anthropic 官方博客、系统卡及 Vellum、VentureBeat 等第三方验证）。

编码基准（最大亮点）

核心洞察：不仅得分高，更重要的是自主性大幅提升，结合 xhigh 努力等级，适合生产级 Agent 编码工作流。

工具使用 & Agentic 能力

推理 & 知识工作 / 视觉

• GPQA Diamond：94.2%（接近饱和）
• Humanity's Last Exam (HLE，无工具) ：46.9%（领先公开模型）
• 视觉：CharXiv 带工具 91.0% （较前代大幅提升），支持 3.75MP 高分辨率图像。

完整对比总结：Opus 4.7 在公开可用模型中重夺编码与 Agent 领域领先，尤其适合生产级复杂任务。最值得升级的场景：复杂编码、Agent 开发、UI/文档视觉分析。

4. Claude API Key 获取（官方 + UIUIAPI）

官方获取步骤（最稳方式）

1. 打开 Anthropic 开发者控制台：https://console.anthropic.com
2. 用 Google / GitHub / 邮箱注册登录。
3. 进入 Settings → Billing，绑卡并充值（建议先充 $5+）。
4. 切换到 API Keys 页面，点击 Create Key 并立即复制保存。
5. 设置环境变量：export ANTHROPIC_API_KEY="sk-ant-..."

注意：官方需绑定支付，国内用户可能遇到充值或访问不便。

国内开发者推荐：UIUIAPI （国内/亚太用户最佳选择）

对于国内开发者及亚太地区开发者，UIUIAPI 是目前最便捷、高性价比的 Claude API 接入方案。它是专业的 AI 大模型一站式聚合平台，支持 OpenAI、Claude（含 Opus 4.7）、Gemini、DeepSeek 等 300+ 主流模型。

UIUIAPI 核心优势：

• 一 Key 通所有：只需一个接口、一个 API Key，即可调用 Claude Opus 4.7 等上百种模型，无需多平台注册。
• 国内/新加坡直连：提供 uiuiapi.com 等优化节点，解决网络、支付、封号风险问题。
• 企业级高可用：支持 OpenAI 兼容格式，无缝切换官方与聚合接口，免去繁琐配置。
• 高性价比：按量付费，额度灵活（登录后添加令牌即可使用），适合个人开发者与企业项目。
• 零代码友好：支持文档理解、多模态、Claude 全系列模型，直接替换 base_url 即可。

UIUIAPI 获取 API Key 步骤：

1. 访问 uiuiapi 注册登录。
2. 进入令牌管理 → 添加新令牌（设置额度）。
3. 复制生成的 sk- 开头 API Key。
4. 在代码中设置 base_url 为 https://sg.uiuiapi.com（或官方提供的节点）。

总结：UIUIAPI 让 Claude 4.7 的强大能力真正“开箱即用”，特别适合新加坡及中文开发者。无需翻墙、无支付障碍、稳定高速，是官方 API 的最佳补充与替代方案。强烈建议立即前往 uiuiapi.com 体验！

5. 开发调用示例（Python SDK + cURL）

Python 官方 SDK（推荐）

pip install anthropic

基础调用 Opus 4.7：

import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY"),  # 或 UIUIAPI Key
    base_url="https://sg.uiuiapi.com" if using_uiuiapi else None
)

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    temperature=0.7,
    messages=[{"role": "user", "content": "帮我写一个异步爬虫..."}]
)

print(message.content[0].text)

带图片输入（高分辨率视觉）：直接传入 base64 图片即可。

cURL 示例

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-4-7", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude 4.7!"}]}'

UIUIAPI 用户：只需将 base_url 改为 https://sg.uiuiapi.com 或 https://api1.uiuiapi.com，其他代码完全兼容。

界智通（jieAGi）总结

Claude Opus 4.7 是 2026 年目前最值得投入的旗舰模型，在编码与 Agent 领域表现尤为突出。结合 UIUIAPI 的便捷接入，你可以零障碍地立即开始开发调用。无论是官方直连还是聚合平台，都能让你快速享受到 1M 上下文、高分辨率视觉和超强自主 Agent 能力。

想获取 LangChain / CrewAI 集成模板、完整 Agent 项目代码，或 UIUIAPI 具体配置细节？随时留言，我立刻提供！🚀

开篇：AI 桌面工具的真实痛点

作为开发者、运维或极客玩家，我们每天都在依赖 AI 完成代码审查、日志分析、报告生成等重复性工作。但实际使用中，痛点高度集中：

• 官方接口容易遭遇速率限制、额度封顶或访问障碍；
• 多模型切换需要反复管理不同平台的 Key、Endpoint 和计费规则，成本高昂；
• AI 通用能力强，却缺乏业务上下文和领域专业性，输出“差不多但不对”；
• 团队协作时配置难以统一共享，本地文件处理与自动化执行能力受限。

WorkBuddy（腾讯云代码助手推出的 AI Agent 桌面智能体工作台）针对这些问题提供了完整解决方案。它支持自然语言驱动本地任务执行、手机 IM 远程指挥、多 Agent 并行，并通过自定义 API 和 Skills 扩展实现“模型自由”与“知识注入”。本文将从基础配置讲到高阶玩法，帮你把 AI 从聊天工具升级为真正能落地执行的“AI 同事”。

基础上手：5 分钟完成配置

WorkBuddy 采用免部署设计，上手极简：

• 下载安装：访问 workbuddy.tencent.com，选择 Windows 10/11 或 macOS 11+ 安装包，直接运行。
• 登录授权：使用微信、企业微信或 QQ 账号登录，授予必要本地权限（建议仅限工作目录）。
• IM 远程控制：进入“个人中心 → Claw 设置”，绑定微信/企微/飞书/钉钉，即可手机下达指令并接收结果。
• 模型切换：界面直接选择内置模型（Hunyuan、DeepSeek、GLM 等），支持 Credits 或内置额度。

安装完成后，一句自然语言指令即可开始体验基础功能。无额外学习成本，适合快速验证场景。

高阶玩法一：自定义 API 接入，实现模型自由

WorkBuddy 核心高阶能力是支持 OpenAI 兼容格式的自定义模型。通过找到安装文件本地配置文件或者安装好WorkBuddy客户端设置模型中配置自定义模型，你可以自由接入任意大模型，实现按任务动态切换。

配置步骤（精炼版）推荐：

1. 创建配置目录：

   # macOS / Linux
   mkdir -p ~/.workbuddy
   # Windows：在 %USERPROFILE%\.workbuddy 创建文件夹

2. 新建 models.json 文件，写入结构（支持同时添加多个模型）：

{
     "models": [
       {
         "id": "gpt-5.4",
         "name": "gpt-5.4",
         "vendor": "OpenAI",
         "url": "https://sg.uiuiapi.com/v1/chat/completions",
         "apiKey": "sk-xxxxxx输入在uiuiAPI获取的key",
         "maxInputTokens": 128000,
         "maxOutputTokens": 4096
       },
       {
         "id": "claude-sonnet-4-6",
         "name": "claude-sonnet-4-6",
         "vendor": "OpenAI",
         "url": "https://sg.uiuiapi.com/v1/chat/completions",
         "apiKey": "sk-xxxxxx输入在uiuiAPI获取的key",
         "maxInputTokens": 200000,
         "maxOutputTokens": 8192
       }
     ],
     "availableModels": ["gpt-5.4", "claude-sonnet-4-6"]
   }

3. 保存后完全重启 WorkBuddy，自定义模型即出现在列表中。

生态推荐：UIUIAPI AI大模型聚合
在配置自定义 API 时，uiuiapi.com是高效且实用的选择。它提供一站式大模型接口聚合服务，只需一个 Endpoint 和 API Key，即可调用 OpenAI、Claude、Gemini、DeepSeek、Qwen 等上百种主流 LLM。

核心优势在于：统一管理多种模型、无需单独维护账号与 Key、稳定高并发转发、显著降低单点故障和维护成本。与 WorkBuddy 搭配使用，开发者可专注于业务逻辑，而非 API 运维琐事，模型切换成本接近于零。

高阶玩法二：Skills 扩展，注入领域专业知识

即使模型能力再强，面对具体业务场景也常因缺少上下文而输出偏差。Skills 扩展机制正是解决这一痛点的核心——它将领域 SOP、输出模板、常见坑点固化为 SKILL.md 文件，让 AI 像“拥有你 10 年经验的同事”一样工作。

Skills 加载方式（推荐顺序）：

1. SkillHub 一键安装：左侧“技能”面板 → SkillHub Tab → 搜索安装，30 秒生效。
2. 对话导入：聊天框输入“导入技能”或拖拽 SKILL.md 文件。
3. 本地手动加载（开发者首选）：

   mkdir -p ~/.workbuddy/skills

   拷贝 SKILL.md 文件 → 重启 WorkBuddy 即可。

自定义 SKILL.md 实战（最灵活方式）：
文件采用 YAML 前言 + Markdown 正文 结构：

---
name: code-review-expert
description: 专业后端代码审查技能，专注 Bug、安全、性能与规范
version: 1.3
author: yourname
tags: [code, review, security]
trigger_keywords: [代码审查, PR Review]
---

# 角色设定
你现在是拥有 10 年经验的 Senior Backend Engineer，精通 Go/Java/Python，严格遵循 Clean Code 与公司内部规范。

# 标准操作流程（SOP）
1. 通读 diff，理解变更意图。
2. 分模块检查：安全性、性能、规范、可维护性。
3. 输出固定 Markdown 格式：
   - ## 整体评分（满分 100）
   - ## 问题清单（严重/中/轻 + 行号）
   - ## 修复建议 + 代码补丁
   - ## 总结与最佳实践

# 常见坑点
- 必须考虑生产环境影响
- 拒绝模糊结论

# 示例
（粘贴 1-2 个真实输入/输出案例）

保存为 code-review-expert.md 放入 skills 目录，重启生效。支持 Git 版本控制与团队共享。

其他高阶方式还包括图形化新建、AI 自动生成、YAML 复杂工作流等。

实战场景：模型 + Skills 组合自动化代码 Review

完整流程演示（后端开发者日常场景）：

1. 配置 uiui-claude 模型 + 创建 code-review-expert Skill。
2. 选中项目目录或拖入 Git diff。
3. 下达指令：

   使用 uiui-claude 模型 + code-review-expert Skill，对 src/ 目录变更进行完整审查，重点关注安全与性能。

WorkBuddy 自动读取文件 → 调用指定模型 → 加载技能手册 → 输出结构化 Markdown 报告（含评分、问题清单、修复补丁）。

可进一步叠加 unit-test-generator Skill 实现 Review 后自动生成测试用例。类似场景还适用于日志根因分析（注入业务日志格式与错误码知识）等。

原本数小时人工工作，压缩至分钟级，结果可直接交付或通过 IM 推送。

最佳实践与工具链总结

• 粒度控制：Skills 聚焦单一领域，避免过宽；高频 Skill 常驻加载。
• 安全与迭代：优先官方 SkillHub，本地自定义仅授权必要目录；SKILL.md 放入 Git 维护。
• 完整工具链：WorkBuddy（执行层） + UIUIAPI（模型层） + Skills（知识层） + MCP Plugins（能力层） = 低维护、高扩展的桌面 AI Agent 闭环。

界智通（jieAGi）总结

WorkBuddy 通过基础配置快速上手、高阶自定义 API 实现模型自由、Skills 扩展注入专业知识，真正把 AI 变成可落地、可复用、可团队共享的工作流代理。搭配 UIUIAPI 聚合平台后，API 维护成本大幅降低，开发者可将精力聚焦在业务价值上。

建议从 1-2 个核心场景开始配置，逐步构建个人/团队技能库与模型组合。欢迎在腾讯开发者社区分享你的 models.json 配置、SKILL.md 模板或实战案例，一起完善 WorkBuddy 生态。

（本文基于 WorkBuddy 最新版本实测，配置以官方文档为准）

版权信息： 本文由界智通(jieagi)团队编写，保留所有权利。未经授权，不得转载或用于商业用途。

在2026年的生成式AI生态中，大语言模型已高度专业化：GPT系列擅长综合逻辑，Claude主导代码与长文本，Gemini 3.1 Pro 凭借百万上下文和多模态能力占据研究高地，Grok 4 则在实时数据与无审查场景表现出色。没有单一模型能通吃所有领域，用户被迫在不同平台间频繁切换。

Cherry Studio 正是在这一背景下诞生的桌面级“全栈AI工作站”。它不是简单的网页封装工具，而是跨平台AI大模型统一控制器。通过抽象统一接口，它无缝集成云端前沿模型、本地Ollama/LM Studio 离线环境，以及 Perplexity、Poe 等网络检索服务，真正实现云端算力、本地零成本推理与实时互联网数据的超级聚合。

一、开箱即用的生产力起点
Cherry Studio 内置智谱 GLM-4.5-Air（MoE架构、128K上下文、高速生成）和阿里 Qwen3-8B（119种语言+原生思维链），用户无需配置 OpenAI API Key 即可直接体验工业级AI能力。这极大降低了入门门槛，成为开发者、工程师和创作者快速上手的首选。

二、底层架构：Electron + 现代前端的极致平衡
Cherry Studio 采用 Electron 38 + Node.js 22 作为运行时，确保对操作系统底层API的完整访问权限。前端使用 React 19 + TypeScript 5.8，配合 Ant Design 5.27、TailwindCSS v4 和 styled-components，实现 Windows Mica 毛玻璃、深浅色模式无缝切换等高级视觉效果。

全局状态管理选用 Redux Toolkit + redux-persist，持久化层则采用 Dexie（IndexedDB 高级封装），支持百万级对话历史毫秒级检索。富文本编辑器基于 TipTap 3.2 + Yjs CRDT 协议，已为未来多人实时协作预留接口。

三、突破Web沙箱：原生系统级交互
“划词助手”是 Cherry Studio 的杀手级功能——在任意窗口选中文字即可唤起AI翻译、解释或摘要。为实现跨平台全局钩子，团队使用 C/C++ 编写原生插件：在 Linux 下调用 libevdev、libxtst、X11/Wayland；在 Windows 下要求开发者模式并开启符号链接权限。这些底层设计充分体现了“为极客而生”的产品哲学。

四、多模型并发与动态思考机制
核心亮点是“多模型同时对话”：同一个问题可同时发给 Grok 4、Claude Opus 4.6 等模型，通过并行对比快速消除幻觉，实现交叉验证。
@cherrystudio/ai-core 引擎支持 Thinking Mode、Token预算控制和模型ID标准化处理，让不同供应商的API差异被完全抹平。

五、本地RAG知识库：打造私有第二大脑
用户可拖拽PDF、DOCX、文件夹或网页链接构建本地知识库。文本经清洗、分块后使用 bge-m3 等嵌入模型向量化，整个过程完全在本地完成，彻底杜绝隐私泄露风险。
查询时向量片段自动注入上下文，并附带精确引用来源，支持点击溯源。v1.8.4 已开放 REST API，可作为局域网知识问答微服务。

六、Code Agent：从辅助到执行级副驾驶
v1.5.7 推出的 Code Agent 让 Cherry Studio 进入软件工程领域。
系统为 Agent 构建独立 Node.js 沙箱环境，自动注入 API Key、Proxy 等变量，并在UI内弹出原生终端接管输入输出。支持 Claude、Gemini、Qwen3 Coder 以及 OpenRouter 聚合服务自定义API Key，还原生兼容本地 LM Studio/Ollama。开发者可在本地显卡上零成本完成代码重构，同时通过严格转义与边界检查保障安全。

📢 开发者效率工具推荐：国内获取主流AI大厂Claude Opus 4.6 \ Anthropic、OpenAI \ GPT-5.4 APIKey方案uiuiAPI

在使用 Cherry Studio 构建全栈工作流时，频繁注册海外服务商、管理繁杂的 API 密钥以及应对网络连通性问题，往往会消耗开发者大量精力。

国内开发者或者AI使用的用户接入 [uiuiAPI] 。作为专业的 API 分发，uiuiAPI 完美契合了 Cherry Studio 的多模型调度需求：

• 全模型覆盖：一个接口、一个密钥，全面兼容 OpenAI、Anthropic (Claude 3.5/3.7)、Google Gemini 等主流大模型协议。
• 极客级稳定：底层采用高可用架构，完美解决廉价中转站常见的文件解析断连、请求超时等痛点。
• 无缝对接：高度兼容 OpenAI 等主流接口规范，在 Cherry Studio 的“提供商设置”中填入 uiuiAPI 的接口地址与 Key，一分钟即可点亮全网顶尖算力。

七、MCP协议：生态级指挥总线
Anthropic 提出的 Model Context Protocol（MCP）将模型“大脑”与外部工具解耦。Cherry Studio 是目前适配最完善的 MCP 客户端，支持 STDIO（本地低延迟）和 SSE（远程云端）两种传输方式。
通过 MCP，外部服务（如日历、Git、数据库、地图API）被抽象为轻量 Server 端点。阿里 Higress 等平台已推出将 RESTful API 自动转为 MCP 的中间件，MCP Marketplace 生态正在快速成型，用户可“一键安装”各种工具链。

八、安全隐私与企业级部署
Cherry Studio 将自己定位为“纯本地管理工具”，严格遵守“三不收集”原则：不回传 API Key、不中继对话内容、仅采集匿名遥测数据。
企业版（Enterprise Edition）提供中央模型路由、RBAC 权限控制、共享知识库与 SLA 支持，完美解决 Token 消耗失控、数据孤岛等问题，适合中大型团队私有化部署。

九、竞品对比与差异化定位
与 Chatbox（极简会话）、LobeChat（插件生态）、LM Studio（纯本地推理）相比，Cherry Studio 在“全栈集成 + MCP 生态 + Code Agent + 企业私有化”四个维度形成压倒性优势。它不是轻量化玩具，而是面向硬核开发者与企业 IT 部门的“AI操作系统总线”。

十、当前局限与未来展望
Electron 架构带来一定内存占用，在超长上下文多任务场景下可能出现 OOM；文件解析依赖外部模型上限，聚合接口偶尔会受限。
官方 Roadmap 显示，下一阶段将重点打造系统级全域记忆（集成 mem0.ai 等）、Deep Research 深度研究引擎，以及移动端（iOS/Android）原生移植。MCP Marketplace 的爆发式增长，将让 Cherry Studio 从桌面工具进化成真正的 AI 指挥中枢。

界智通（jieAGI）总结
Cherry Studio 以极客级架构和前瞻生态布局，解决了 AI 工具碎片化的核心痛点。无论你是需要快速原型开发的独立开发者，还是管理企业级 AI 资产的 IT 架构师，它都值得立刻上手。建议从社区开源版开始体验，感受多模型并行、本地 RAG 与 Code Agent 带来的生产力飞跃。

版权信息： 本文由界智通(jieagi)团队编写，保留所有权利。未经授权，不得转载或用于商业用途。

OpenAI Codex 作为当前极具生产力的 AI 编程助手，目前官方主推 CLI（命令行界面）、IDE 扩展、App 三种交互形态。对于习惯在终端中沉浸式开发的工程师而言，Codex CLI 无疑是最顺手的工具。

本文将基于最新的官方文档，带你从零完成 Codex CLI 的安装，并重点梳理如何配置自定义 API 网关，让工具完美契合你的本地开发环境。

一、 认识 Codex CLI

Codex CLI 是 OpenAI 官方推出的开源本地编码代理，底层基于 Rust 构建。它能够直接在当前目录下读取代码上下文、修改文件甚至执行终端命令。

在身份认证方面，Codex 提供了极大的灵活性，支持两种登录方式：

1. ChatGPT 账号登录：适合普通用户，直接调用订阅权益。
2. OpenAI API Key 登录：适合企业级 CI/CD 集成、按量计费开发者，以及需要接入自定义 API 网关的进阶玩家（按 OpenAI Platform 标准 API 计费）。

二、 下载与环境安装

1. 推荐安装方式 (Node.js 环境)

官方首推使用 npm 全局安装，确保你的设备上已安装 Node.js：

npm i -g @openai/codex

如果是 macOS 用户，也可以直接使用 Homebrew 一键安装：

brew install --cask codex

提示： GitHub 官方仓库的 Release 页面也提供了各平台的二进制包，可根据需要手动下载配置环境变量。

2. 系统兼容性说明

• macOS / Linux：官方提供主流且稳定的支持。
• Windows：目前仍处于实验性阶段。强烈建议在 WSL (Windows Subsystem for Linux) 中安装 Node.js + npm 后再运行 CLI，或者直接使用原生 Codex App / VS Code 扩展。

三、 首次登录与认证

安装完成后，在终端输入 codex 即可启动。首次运行需要进行身份验证。

方式 1：ChatGPT 网页授权（默认）

直接运行 codex，CLI 默认会唤起浏览器进入 ChatGPT 登录流程。授权成功后，凭据会缓存在本地（~/.codex/auth.json），后续使用无需重复登录。

方式 2：API Key 环境变量注入（推荐开发者使用）

针对程序化工作流，提前注入 API Key 是更高效的做法。

Windows PowerShell 侧：

$env:OPENAI_API_KEY="你的OpenAI_API_Key"
codex

macOS / Linux 侧：

export OPENAI_API_KEY="你的OpenAI_API_Key"
codex

(注：你也可以随时使用 codex login 命令，通过管道传入 API Key 或切换设备授权模式。)

四、 基础命令与开发场景

Codex CLI 并非只能单纯对话，它的核心价值在于“动作执行”。

最简启动与任务下发：
你可以直接进入交互模式，或者在启动时直接带上指令：

codex "Explain this codebase to me"
codex "帮我分析当前项目的目录结构"

核心能力清单：

• 📁 读取并解析复杂项目代码
• 📝 自动化修改并保存文件
• 💻 执行终端命令与脚本化工作流 (codex exec)
• 🔍 代码审查与 Web 搜索补全上下文
• ⚡ 连接 MCP（Model Context Protocol）

五、 进阶：配置文件与自定义 API 接入

这是国内开发者和企业用户最关心的部分。Codex 的核心配置文件位于：~/.codex/config.toml。CLI 和 IDE 扩展共用这一套配置。

如果你需要将 Codex 接入自建网关、第三方聚合 API（如 uiuiAPI），可以通过修改该文件实现。官方支持配置 base_url、env_key、http_headers 等关键字段。

以下提供三种最常见的直连与中转配置方案，可直接复制使用：

方案 A：极简模式 —— 仅覆盖默认 Base URL

如果你只是想把官方 OpenAI 的请求代理到自定义地址，可以直接覆盖内置的 openai_base_url。

~/.codex/config.toml 配置：

model = "gpt-5.4"
model_provider = "openai"

openai_base_url = "https://sg.uiuiapi.com/v1"

API_KEY 配置

1.文件配置~/.codex/auth.json 配置示例：

{
  "OPENAI_API_KEY": "输入在uiuiapi获取的sk-dxxxxxxxxxxxxxxxx"
}

2.运行环境：

export OPENAI_API_KEY="你的代理网关Key"
codex

方案 B：专业模式 —— 自定义 Provider（强烈推荐）

为了配置的清晰和后续切换的便利，官方更推荐新建一个独立的 Provider 节点。

~/.codex/config.toml 配置：

model = "gpt-5.4"
model_provider = "myproxy"

[model_providers.myproxy]
name = "My Proxy"
base_url = "https://sg.uiuiapi.com/v1"
wire_api = "responses"
env_key = "MY_PROXY_API_KEY"
env_key_instructions = "启动前请先设置环境变量 MY_PROXY_API_KEY"

运行环境：

export MY_PROXY_API_KEY="你的代理网关Key"
codex

六、 Windows 环境特殊避坑指南

如前所述，Windows 原生环境目前在支持上仍有局限。但官方已在 CLI 中加入了 Windows 沙箱模式（分 elevated 提权和 unelevated 非提权两种）。

如果你坚持在原生 Windows（非 WSL）下使用，建议在 config.toml 中强制开启提权沙箱模式以提升文件操作的稳定性：

[windows]
sandbox = "elevated"

七、 常见问题排查 (FAQ)

Q1：安装完成后提示 codex: command not found？

• 排查： 通常是因为 npm 全局安装的 bin 目录没有加入到系统的环境变量 PATH 中。可通过 npm config get prefix 查找路径并手动配置。

Q2：自定义 API 配置后不生效或请求报错？

1. 检查 config.toml 路径是否正确（用户级为 ~/.codex/config.toml，项目级为项目根目录下的 .codex/config.toml）。
2. 确认网关服务是否完全兼容 OpenAI 协议规范（目前官方 wire_api 要求支持 responses）。
3. 核对环境变量名是否与 config.toml 中的 env_key 字段完全一致。

Q3：ChatGPT 登录与 API Key 登录有何本质区别？

• ChatGPT 登录消耗的是你网页版账号的订阅额度与调用次数。
• API Key 登录则严格走 Developer Platform 的 API 计费体系，两者账单和配额独立计算。

八、 总结

OpenAI Codex 正在重塑开发者的工作流。通过合理配置 config.toml 和环境变量，我们完全可以打造一个兼顾网络稳定性与数据隐私的个人 AI 编程环境。建议优先采用自定义 Provider (方案 B) 的形式接入 API，这不仅能让配置文件更加语义化，也能在多个服务商之间实现秒级切换。