Reasonix 自定义 API 教程：TOML 提供商与全局密钥存储

本文对应 reasonix.io 官方文档链接的 Reasonix 项目。官方提供终端、桌面和浏览器入口；本页只解释自定义模型配置，不启动其服务。2026 年 9 月 30 日核对了使用指南和工程规范，尚未做任何真实接口测试。

图中连线用于说明配置关系，不是接口测试结果。

把设置和密钥放在正确位置

初次配置可使用 reasonix setup。官方区分用户配置 config.toml、项目配置 reasonix.toml 与全局秘密文件 .env：macOS、Linux 的用户目录通常为 ~/.reasonix，Windows 使用 %APPDATA%\reasonix。若设置 REASONIX_HOME，应以该目录为准。

Provider 里写的是 api_key_env 变量名，实际凭据由设置入口保存到 Reasonix 全局 .env，不要误放进项目文件。

定义一个兼容服务

工程规范将 kind = "openai" 定义为 Chat Completions 实现，也提供 request_url 指定完整请求目标。 下例仅为 TOML 片段；地址是占位，本站未提供对应真实接口、Key 创建或充值服务。保留已有提供商，只合并新条目。

default_model = "tutorial-gateway"

[[providers]]
name = "tutorial-gateway"
kind = "openai"
base_url = "https://80321.cn/v1"
request_url = "https://80321.cn/v1/chat/completions"
model = "YOUR_MODEL_ID"
api_key_env = "TUTORIAL_API_KEY"

对应的秘密值示意为 TUTORIAL_API_KEY=YOUR_API_KEY，实际值保存到上述全局秘密文件并限制读取权限，不提交到仓库。只有服务方确认完整 Chat 路径时才使用上述格式；其他协议须采用版本对应的官方配置。

注意项目覆盖和凭据来源

普通配置的优先顺序为命令行、当前项目、用户配置、内置默认值。项目中已有 reasonix.toml 时，默认模型可能不来自你刚修改的用户文件。

官方还说明，项目 .env、继承的 shell 变量和旧凭据文件并不是 Provider Key 的运行时回退来源。遇到“已导出变量却找不到密钥”，先查全局设置，不要复制 Key 到越来越多目录。

先验证短回复，再检查只读任务

取得正式地址后，在测试目录启动新会话，明确选择新增提供商。先只问一句普通问题，再用只读任务检查工具返回是否能进入下一轮。官方提供 /docs 查询版本匹配文档；安装版字段与网页示例不一致时，优先核对该版本说明。

验证记录只保留模型、协议、脱敏状态码和错误类别。路径错误先核对基础地址与完整目标；认证错误检查保存的变量名和凭据归属，避免连续重试造成费用。

权限与浏览器服务的限制

首次验证选择“仅可查看”权限，确认文件与工具范围后再开放写入。官方提醒 reasonix serve 保留配置驱动的默认认证行为，向其他机器开放前必须审核并启用认证。

不要为了排错改用完全权限、公开服务或取消证书验证。发现文档和版本的安全边界不一致，应暂停任务，收集脱敏版本信息再核对；本文没有更改任何已有运行配置。