认证与模型

Mogick 将非敏感的模型设置放在 config.json，将 API Key、OAuth Token 等凭据放在 auth.json。本页覆盖认证方式和模型配置结构。完整字段和默认值见配置参考。

从 26.9.24 版本起，交互式 TUI 提供 /connect 命令，可接入自定义模型。需要自行管理模型服务配置时，可按本页示例手动配置；已有模型可通过 /models 选择。

认证

Mogick 支持两种认证方式：OAuth 设备码认证（推荐）和手动 API Key 认证。

OAuth 设备码认证

运行交互式向导，按终端提示完成浏览器授权：

mogick setup

流程：终端显示授权 URL 和一次性设备码 → 浏览器打开 URL 并输入设备码 → 登录授权 → 终端自动检测并写入凭据。

凭据写入 <config-dir>/auth.json。Access Token 过期后 Mogick 使用 Refresh Token 自动刷新；模型服务返回 INVALID_OAUTH_TOKEN 时强制刷新并重试当前请求一次。setup 会补齐官方 Provider 和缺失的默认/轻量模型设置，并保留已有 Provider 与显式模型选择。

授权失败、浏览器未打开、Token 过期等问题的处理见 setup 无法完成或认证失败。

退出登录与切换账号

在终端运行 mogick logout；已登录 OAuth 的 TUI 中也可使用 /logout。它清除有效全局认证文件中的 OAuth 凭据，保留 API Key 和模型配置，不清除项目级认证覆盖。

/logout 成功处理后会退出 TUI。切换账号时，重新运行 mogick setup 完成授权，再启动 Mogick 并检查 /models。/exit 仅退出界面，不等于退出登录。

API Key 认证

直连 OpenAI-compatible 服务时，手动写入两份文件：

<config-dir>/auth.json — 存放凭据：

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

<config-dir>/config.json — 存放模型服务地址和模型名：

{
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://api.example.com/v1",
    "model": "your-model-id",
    "models": [
      { "id": "your-model-id", "name": "My Model" }
    ]
  }
}

运行时优先使用有效的 OAuth Access Token；没有时才使用顶层 api_key。不要把 API Key 写入 config.json、命令参数或截图。

以下单 Provider 示例要求 llm.providers 不存在或为空。如果 setup 已生成 provider 数组，请按下方多 Provider 示例修改该数组，不要叠加会被忽略的单 Provider 字段。地址、模型 ID 和 API Key 均须替换为服务实际值；默认模型和轻量模型 ID 应与 models 中的条目一致。

单 Provider 配置

只接入一个模型服务时，在 config.json 的 llm 下直接填写：

{
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://api.example.com/v1",
    "model": "model-1",
    "light_model": "model-2",
    "models": [
      { "id": "model-1", "name": "Model One" },
      { "id": "model-2", "name": "Model Two" }
    ]
  }
}

字段	说明
provider	Provider 类型：openai-compatible 或 llm-store；不填时 /models 可能无法读取模型列表
base_url	API base 地址，通常包含 /v1
model	默认使用的模型 ID
light_model	标题生成、摘要等轻量任务使用的模型；未设置时回退到 model
models	TUI /models 中展示的可选模型列表；id 为 API 模型名，name 为显示名

llm-store 类型 Provider 会从远端动态获取模型目录，不需要填写 models[]。

凭据在 auth.json 顶层：

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

完整接入示例见配置第三方模型接入。

多 Provider 配置

需要同时接入多个模型服务时，使用 llm.providers[]。每个 Provider 有独立的 ID、地址和凭据。

config.json：

{
  "llm": {
    "default_model": "private/code-model",
    "providers": [
      {
        "id": "private",
        "type": "openai-compatible",
        "base_url": "https://api.example.com/v1",
        "enabled": true,
        "models": [
          { "id": "code-model", "name": "Private Code Model" }
        ]
      },
      {
        "id": "corp",
        "type": "llm-store",
        "base_url": "https://llm.example.net",
        "enabled": true
      }
    ]
  }
}

llm 级字段：

字段	说明
default_model	默认模型，格式为 provider-id/model-id；不填时使用第一个 Provider 的默认模型

providers[] 中每个 Provider 的字段：

字段	必填	说明
id	是	Provider 唯一标识，模型通过 provider-id/model-id 引用
type	否	openai-compatible 或 llm-store；省略时默认 openai-compatible
base_url	是	服务地址；llm-store 运行时自动追加 /api/v1
enabled	否	默认 true；false 时该 Provider 及其模型不出现
models	openai-compatible 必填	静态模型列表；没有启用的模型时 Provider 初始化失败；llm-store 忽略此字段
app_id	否	llm-store 的 X-APP-ID 请求头
extra_headers	否	该 Provider 的非敏感附加请求头

auth.json — 按 Provider ID 写入独立凭据：

{
  "providers": {
    "private": {
      "api_key": "<private-api-key>"
    },
    "corp": {
      "access_token": "<corp-access-token>"
    }
  }
}

如果某 Provider 未在 auth.providers 中配置凭据，运行时回退到顶层 OAuth Token 或 api_key。

多 Provider 与单 Provider 不要混用。llm.providers[] 非空时，单 Provider 字段（llm.model、llm.base_url 等）被忽略，以多 Provider 结构为准。项目层非空的 llm.providers[] 整体替换全局数组。

配置位置与优先级

层级	config	auth
全局	<config-dir>/config.json	<config-dir>/auth.json
项目	<workspace>/.mogick/config.json	<workspace>/.mogick/auth.json

项目配置优先于全局。所有 auth.json 不应提交到版本控制。

模型列表

OpenAI-compatible Provider 在 models[] 中声明静态模型，每个模型可配置：

{
  "id": "vision-model",
  "name": "Vision Model",
  "description": "Text and image input",
  "input_modals": ["text", "image"],
  "output_modals": ["text"],
  "context_length": 128000,
  "enabled": true
}

llm-store Provider 从远端动态获取模型目录，不依赖本地 models[]。禁用的 Provider 或 enabled: false 的模型不会在 /models 中显示。

切换模型

在 TUI 输入 /models 或 Ctrl+P 打开 Models 面板。模型标题以 provider-id / model-name 格式显示来源。

切换后当前会话立即使用新模型。多 Provider 下更新 llm.default_model；单 Provider 下更新 llm.model。恢复历史会话时，会话保存的模型选择优先。

mogick doctor --check-network

--check-network 发起真实模型请求，可验证模型连接是否正常。

相关文档

• 配置参考 — 所有字段和默认值
• 配置第三方模型接入 — 第三方模型接入的完整步骤
• setup 无法完成或认证失败

通过 /efforts 选择模型支持的思考档位；图片输入及官方图像工具的条件见文件与图片。

路径占位符 <config-dir>、<db-path> 指当前 profile/通道实际生效的路径，见数据目录。