Reasonix 模型接入完整教程：自定义配置 uiuiAPI、模型发现与 Planner 设置

一、为什么要单独配置 Reasonix 的模型供应商

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)团队编写，图片、文本保留所有权利。未经授权，不得转载或用于商业用途。