Mogick
文档首页

简体中文

English

简体中文

English

配置第三方模型接入 ​

本文面向“只接入一个第三方 OpenAI-compatible 模型服务”的场景。你需要准备两份文件：config.json 写模型地址和模型名，auth.json 写 API Key。

准备两份文件 ​

文件作用
<config-dir>/config.json模型服务地址、Provider 类型和模型列表
<config-dir>/auth.jsonAPI Key、Access Token 等敏感凭据

项目也可以使用 <workspace>/.mogick/config.json 和 <workspace>/.mogick/auth.json 设置项目级配置；项目中明确填写的字段优先，未填写的字段继续继承全局配置。

写入模型配置 ​

在 <config-dir>/config.json 中写入：

此单 Provider 示例要求 llm.providers 不存在或为空；若已通过 setup 配置了 provider 数组，请按多 Provider 配置修改该数组。替换示例地址和模型 ID 时，保持默认模型、轻量模型与列表中的 ID 一致。

json
{
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://example.com/v1",
    "model": "your-model-id-1",
    "light_model": "your-model-id-2",
    "models": [
      {
        "id": "your-model-id-1",
        "name": "your-model-name-1"
      },
      {
        "id": "your-model-id-2",
        "name": "your-model-name-2"
      },
      {
        "id": "your-model-id-3",
        "name": "your-model-name-3"
      }
    ]
  }
}

其中：

字段说明
llm.provider必填；第三方 OpenAI-compatible 服务使用 openai-compatible。不填写时，/models 无法读取 llm.models[] 中的静态模型列表
llm.base_url服务商提供的 API base，通常包含 /v1
llm.model默认使用的模型 ID
llm.light_model轻量任务使用的模型；未设置时回退到默认模型
llm.models[]TUI 模型列表中展示的可选模型

models[] 可以写多个模型，llm.model 和 llm.light_model 应填写你实际要使用的模型 ID，并与服务商接受的模型名称一致。name 是显示名称，建议填写。

写入 API Key ​

在 <config-dir>/auth.json 中写入：

json
{
  "api_key": "<your-api-key>"
}

如果服务商使用网关 Token、租户 ID 或其他敏感请求头，不要写入 config.json。单 Provider 场景可以优先确认服务商是否支持直接使用 API Key；更复杂的请求头和多 Provider 凭据拆分见认证与模型。

验证接入 ​

bash
mogick doctor
mogick doctor --check-network
mogick run "Reply: provider configuration succeeded"

--check-network 会发起真实模型请求，可能消耗额度。终端结果里重点看这些检查项：

检查项含义
Config配置文件加载状态
Models当前默认模型和已配置模型数量
Auth认证凭据状态
Server模型服务地址的基础可达性
Chat非流式模型请求能力；usage present 表示响应中包含 token 用量信息
Tool calls工具调用格式支持情况
Streaming流式模型请求能力；usage present 表示流式响应中包含 token 用量信息

OK 表示该检查项通过。如果 Chat 或 Streaming 请求成功但缺少 usage，通常表示模型可用，但服务端没有返回完整 token 用量信息。

验证通过后，在 TUI 输入 /models，应能看到配置中的模型并切换。

常见问题 ​

模型列表为空 ​

检查 llm.models[] 是否存在、models[].id 是否填写，以及模型是否被设置为 enabled: false。

认证失败 ​

确认 API Key 写在 auth.json 中，而不是 config.json。如果使用项目级配置，也要确认项目级 auth.json 存在且没有被提交到版本控制。

model not found ​

确认 llm.model 和 models[].id 与服务商接受的模型名称完全一致。有些服务商的展示名和实际 API 模型 ID 不相同，应以 API 文档为准。

连接超时或证书错误 ​

先运行 mogick doctor --check-network，确认模型服务地址可达、证书可信，并核对 base_url 是否为正确的 API base。Mogick 没有公开的模型代理或自定义 CA 配置字段。

接入多个模型服务 ​

如果你需要同时接入多个模型服务，例如一个公司网关、一个本地模型和一个云端模型，请使用 llm.providers[] 和 auth.providers.<provider-id>。完整结构、合并规则和 /models 行为见认证与模型。

相关文档 ​