# 配置模型

> 在设置中添加预设或自定义服务商、登记模型并选择默认与思考档位。

Canonical page: /product/models



模型配置决定普通会话、知识库加工、批量任务、自动化和 Claw 等路径可用的模型。入口：**设置 → 模型配置**。

配置文件路径：`~/.vetta/agent/models.json`（开发隔离环境可能使用 `VETTA_CONFIG_DIR` 指向的目录）。

## 思考模式 [#思考模式]

页面顶部的 **思考** 为全局设置，对所有会话立即生效。可选：关闭、极低、低、中、高、极高。模型不支持时客户端会自动降级。

## 添加服务商 [#添加服务商]

<Tabs items="[&#x22;预设服务商&#x22;, &#x22;自定义服务商&#x22;]">
  <Tab value="预设服务商">
    当前内置预设包括（以应用实际列表为准）：

    * Claude
    * OpenAI
    * DeepSeek
    * Z.ai (GLM)
    * Kimi
    * Grok
    * Qwen
    * Gemini

    <Steps>
      <Step>
        ### 选择预设 [#选择预设]

        在 **预设服务商** 区域选择目标服务商。
      </Step>

      <Step>
        ### 填写 API Key [#填写-api-key]

        按服务商要求填写密钥。占位提示支持 `sk-...` 等形式。
      </Step>

      <Step>
        ### 拉取或添加模型 [#拉取或添加模型]

        使用 **从接口拉取** 勾选模型并添加，或手动 **添加模型**（模型 ID、显示名、输入能力、上下文窗口、最大输出、是否支持推理等）。
      </Step>

      <Step>
        ### 设为默认 [#设为默认]

        在模型列表中将常用模型 **设为默认模型**。
      </Step>
    </Steps>
  </Tab>

  <Tab value="自定义服务商">
    使用 **添加服务商**，至少配置：

    * 服务商名称
    * API 类型
    * Base URL
    * API Key（可用 `env:VAR` 或 `cmd:...` 等形式，以界面说明为准）
    * 可选：自定义 Headers、是否用 Authorization Header 发送 Key

    手动登记模型时，**模型 ID 必须与上游接口一致**。能力标记错误可能导致客户端发送供应商不支持的参数。

    填写 Base URL 后可 **从接口拉取** 模型列表（若该协议支持）。

    下面只展示字段关系，域名和模型 ID 是虚构占位，不能直接调用：

    | 字段       | 示例值                          | 核对重点               |
    | -------- | ---------------------------- | ------------------ |
    | 服务商名称    | `团队代理服务`                     | 只用于本机识别            |
    | API 类型   | `OpenAI Compatible`          | 必须与上游协议一致          |
    | Base URL | `https://api.example.com/v1` | 核对是否应包含 `/v1`      |
    | API Key  | `env:TEAM_MODEL_KEY`         | 环境变量需在 Vetta 进程中可见 |
    | 模型 ID    | `team-model-id`              | 使用接口接受的精确 ID，不是显示名 |
  </Tab>
</Tabs>

远程目录中的模型（若账号已登录且组织提供）可在列表中刷新获取，与本地服务商并列展示。

## 验证配置 [#验证配置]

<Steps>
  <Step>
    ### 会话探测 [#会话探测]

    新建会话并显式选择该模型，发送一条短消息。
  </Step>

  <Step>
    ### 知识库探测 [#知识库探测]

    若用于知识库加工，到 **设置 → 知识库设置** 选择处理模型后点 **测试连接**。
  </Step>
</Steps>

常见失败原因：Base URL 路径多写或少写、模型 ID 不存在、密钥无效、账户无权限、代理拦截、网络不可达。

<Checklist title="把模型用于真实任务前">
  <li>
    新建会话能够显式选择该模型，并完成一条短消息。
  </li>

  <li>
    切换默认模型后，新会话显示预期选择。
  </li>

  <li>
    模型能力标记与上游实际支持一致，没有依赖自动猜测。
  </li>

  <li>
    知识库、自动化或 Claw 使用的模型已在对应入口单独验证。
  </li>

  <li>
    配置文件和诊断信息中没有要提交到仓库的真实密钥。
  </li>
</Checklist>

<Callout title="密钥与配置文件" type="warn">
  不要把含密钥的 `models.json` 提交到仓库或粘贴到问题报告。需要排查时可在设置中导出诊断包（不含让你主动泄露密钥）。
</Callout>