---
title: "设置 API：模型、版本与诊断"
description: "Halo HTTP API 设置与模型接口：版本、模型来源与模型切换、安全策略、Agent 引擎和 MCP 服务器诊断。"
type: "reference"
audience: ["developer"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/developers/api/settings.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API：设置与模型

Halo HTTP API 设置与模型接口：版本、模型来源与模型切换、安全策略、Agent 引擎和 MCP 服务器诊断。

读取这台 Halo 的配置和能力：版本、模型来源与模型、安全策略、Agent 引擎和 MCP 服务器诊断，并切换模型来源与模型。API Key 等凭据不通过这套 API 写入，请在 Halo 的 **设置** 中填写。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 `$HALO_URL` 和 `$HALO_TOKEN` 按[快速上手](https://hello-halo.cc/docs/developers/quickstart.html)设置；地址、鉴权和错误约定见 [HTTP API 概览](https://hello-halo.cc/docs/developers/api/)。

| 操作 | 端点 |
| --- | --- |
| [列出已安装的 Agent 引擎及当前使用的引擎](#get-api-agent-engine-availability) | `GET /api/agent/engine-availability` |
| [读取当前 Agent 引擎的能力](#get-api-agent-engine-capabilities) | `GET /api/agent/engine-capabilities` |
| [探测一个已安装 MCP 服务器的连通性和工具](#post-api-agent-probe-mcp) | `POST /api/agent/probe-mcp` |
| [测试所有已配置 MCP 服务器的连接](#post-api-agent-test-mcp) | `POST /api/agent/test-mcp` |
| [在当前模型来源内切换模型](#post-api-ai-sources-set-model) | `POST /api/ai-sources/set-model` |
| [修改一个已配置的模型来源](#put-api-ai-sources-sources-sourceid) | `PUT /api/ai-sources/sources/:sourceId` |
| [删除一个已配置的模型来源](#delete-api-ai-sources-sources-sourceid) （不可撤销） | `DELETE /api/ai-sources/sources/:sourceId` |
| [切换到另一个已配置的模型来源](#post-api-ai-sources-switch-source) | `POST /api/ai-sources/switch-source` |
| [列出本版本提供的登录方式和模型提供商](#get-api-auth-providers) | `GET /api/auth/providers` |
| [读取全局配置](#get-api-config) | `GET /api/config` |
| [列出解密失败的凭据字段](#get-api-config-credential-failures) | `GET /api/config/credential-failures` |
| [重新读取所有模型来源并返回刷新后的配置](#post-api-config-refresh-ai-sources) | `POST /api/config/refresh-ai-sources` |
| [列出所有已知模型支持的能力（视觉、工具、上下文）](#get-api-model-capabilities-all) | `GET /api/model-capabilities/all` |
| [读取某个模型内置的能力预设](#get-api-model-capabilities-preset-modelid) | `GET /api/model-capabilities/preset/:modelId` |
| [解析某个模型实际生效的能力](#post-api-model-capabilities-resolve) | `POST /api/model-capabilities/resolve` |
| [读取本版本的安全策略](#get-api-security-policy) | `GET /api/security/policy` |
| [读取正在运行的 Halo 版本](#get-api-system-version) | `GET /api/system/version` |

## 列出已安装的 Agent 引擎及当前使用的引擎 {#get-api-agent-engine-availability}

`GET /api/agent/engine-availability` （助手可调用）

- degradedFrom is non-null when Halo fell back off the engine the user picked — that is the thing worth telling them about.

**响应**

```ts
{success:true,data:{engines:[{engineId:"anthropic"|"halo"|"codex",available:boolean,version:string,fingerprint:string}],activeEngine,degradedFrom}}
```

**示例**

```bash
curl -s "$HALO_URL/api/agent/engine-availability" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取当前 Agent 引擎的能力 {#get-api-agent-engine-capabilities}

`GET /api/agent/engine-capabilities` （助手可调用）

- Describes the agent engine in use: which streaming and tool features it provides natively and which Halo emulates. Always answers; falls back to the active engine's defaults.

**响应**

```ts
{success:true,data:{engineId,displayName,streaming:{text,reasoning,toolInput,toolOutput},tools:{native,synthetic,shellHeuristics},todo:{states,hasActiveForm},subAgent:{...}}}
```

**示例**

```bash
curl -s "$HALO_URL/api/agent/engine-capabilities" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 探测一个已安装 MCP 服务器的连通性和工具 {#post-api-agent-probe-mcp}

`POST /api/agent/probe-mcp` （助手可调用）

- "App is not an MCP server" = that app exists but is not an MCP-type app; probe only applies to those.

**请求体**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>"
}
```

**响应**

```ts
{success:true,result:{status:"connected"|"failed"|"needs-auth",tools?:string[],serverInfo?:{name,version},latencyMs:number}}  // result, not data
```

**错误**

- 400 if appId is missing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/agent/probe-mcp" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>"}'
```

## 测试所有已配置 MCP 服务器的连接 {#post-api-agent-test-mcp}

`POST /api/agent/test-mcp` （助手可调用）

- Starts a real query against every configured server, so it is slow and it costs tokens. Say so before running it.
- "Test already in progress" = another test is running; wait and retry.
- "No MCP servers configured" comes back with success:true and nothing to report.

**响应**

```ts
{success:true,servers:[{name,status:"connected"|"failed"|"needs-auth"|"pending",tools?:string[],serverInfo?:{name,version},error?}]}  // servers, not data
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/agent/test-mcp" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 在当前模型来源内切换模型 {#post-api-ai-sources-set-model}

`POST /api/ai-sources/set-model` （可撤销） （助手可调用）

- Applies to what Halo runs next, including this assistant. Switch back the same way.

**请求体**

```json
{
  "modelId": "deepseek-chat"
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "currentId": "<uuid>",
    "currentModel": "deepseek-chat"
  }
}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/ai-sources/set-model" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"deepseek-chat"}'
```

## 修改一个已配置的模型来源 {#put-api-ai-sources-sources-sourceid}

`PUT /api/ai-sources/sources/:sourceId` （可撤销） （助手可调用）

- 逐个字段合并，只发送要改的字段。不带 `apiKey` 时已保存的密钥保持不变：改名或换模型都不需要它。
- 不要通过这里发送 `apiKey`。密钥在 **设置 › AI 模型** 中管理。

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `sourceId` | 模型来源 ID，来自 [`GET /api/config`](#get-api-config)。 |

**请求体**

```json
{
  "name": "Work account"
}
```

**响应**

```ts
{"success":true,"data":{...the full sources config, secret fields redacted}}
```

**示例**

```bash
curl -sX PUT "$HALO_URL/api/ai-sources/sources/<sourceId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Work account"}'
```

## 删除一个已配置的模型来源 {#delete-api-ai-sources-sources-sourceid}

`DELETE /api/ai-sources/sources/:sourceId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
只想做范围更小的操作时，改用 [`POST /api/ai-sources/switch-source`](#post-api-ai-sources-switch-source)
:::

- The stored API key goes with it, and no endpoint here can put one back — only the user can, in Settings &gt; AI Model. Confirm before deleting.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `sourceId` | 模型来源 ID，来自 [`GET /api/config`](#get-api-config)。 |

**响应**

```ts
{"success":true,"data":{...the remaining sources config, secret fields redacted}}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/ai-sources/sources/<sourceId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 切换到另一个已配置的模型来源 {#post-api-ai-sources-switch-source}

`POST /api/ai-sources/switch-source` （可撤销） （助手可调用）

- Picks among sources the user already configured. It cannot create one or change a key.
- Applies to what Halo runs next, including this assistant. Switch back the same way.
- "Source not found" = wrong sourceId; read the configured list from [`GET /api/config`](#get-api-config) first.

**请求体**

```json
{
  "sourceId": "<sourceId — a uuid from GET /api/config>"
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "currentId": "<uuid>",
    "currentModel": "..."
  }
}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/ai-sources/switch-source" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"<sourceId — a uuid from GET /api/config>"}'
```

## 列出本版本提供的登录方式和模型提供商 {#get-api-auth-providers}

`GET /api/auth/providers` （助手可调用）

- What this build could be configured with, not what the user has configured — read [`GET /api/config`](#get-api-config) for that. On an enterprise build the preset field carries deployment-internal endpoints; do not repeat them back.

**响应**

```json
{
  "success": true,
  "data": [
    {
      "type": "…",
      "displayName": "…",
      "enabled": true,
      "recommended": false,
      "platforms": [
        "darwin"
      ]
    }
  ]
}
```

**示例**

```bash
curl -s "$HALO_URL/api/auth/providers" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取全局配置 {#get-api-config}

`GET /api/config` （助手可调用）

- Read-only here. The write side is not opened to the assistant. configEpoch -1 means the config file could not be read and data holds the built-in defaults, not what the user configured. productDefaults is read-only build metadata, not user settings: a non-empty user federation.gatewayUrl overrides its gatewayUrl; an empty user value inherits it. A null build gateway with no user override means LAN-only teams.

**响应**

```ts
{"success":true,"data":{...},"configEpoch":0,"productDefaults":{"federation":{"gatewayUrl":null}}}  // secret fields come back as "***"
```

**示例**

```bash
curl -s "$HALO_URL/api/config" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出解密失败的凭据字段 {#get-api-config-credential-failures}

`GET /api/config/credential-failures` （助手可调用）

- Path and label only, never ciphertext. Non-empty means the user must re-enter that credential in the Halo app.

**响应**

```json
{
  "success": true,
  "data": [
    {
      "path": "...",
      "label": "..."
    }
  ]
}
```

**示例**

```bash
curl -s "$HALO_URL/api/config/credential-failures" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 重新读取所有模型来源并返回刷新后的配置 {#post-api-config-refresh-ai-sources}

`POST /api/config/refresh-ai-sources` （助手可调用）

- Use it when [`GET /api/config`](#get-api-config) looks stale after the user changed a source in the app. It re-reads what is stored; it cannot add or fix a credential.

**响应**

```ts
{"success":true,"data":{...}}  // same masked shape as GET /api/config
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/config/refresh-ai-sources" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出所有已知模型支持的能力（视觉、工具、上下文） {#get-api-model-capabilities-all}

`GET /api/model-capabilities/all` （助手可调用）

- Read-only presets. It does not say which model is currently in use.

**响应**

```ts
{"success":true,"data":{"<modelId>":{...capability flags}}}
```

**示例**

```bash
curl -s "$HALO_URL/api/model-capabilities/all" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取某个模型内置的能力预设 {#get-api-model-capabilities-preset-modelid}

`GET /api/model-capabilities/preset/:modelId` （助手可调用）

- An unknown model returns data:null with success:true — not a 404.
- Percent-encode a modelId that contains slashes.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `modelId` | 模型 ID，与模型来源中列出的模型一致。 |

**响应**

```json
{
  "success": true,
  "data": {
    "displayName": "...",
    "provider": "...",
    "contextWindow": 128000,
    "maxOutputTokens": 8192,
    "vision": false,
    "thinking": false
  }
}
```

**示例**

```bash
curl -s "$HALO_URL/api/model-capabilities/preset/<modelId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 解析某个模型实际生效的能力 {#post-api-model-capabilities-resolve}

`POST /api/model-capabilities/resolve` （助手可调用）

- All optional inputs are validated. Catalog data accepts only positive integer contextWindow and maxOutputTokens values within Halo runtime limits; catalogSupportsVision must be a boolean.
- Priority, highest first: user override, then a [1m] model-id suffix (contextWindow only), then an exact preset entry, then catalog data, then a model-family pattern entry, then built-in defaults. A pattern entry is only a family guess and ranks below the provider catalog; an exact entry is curated and ranks above it.
- A context window above 200K is what opts the SDK into extended context — there is no separate switch. A model id ending in [1m] does the same.
- Returns 400 for a missing modelId or malformed capability data.

**请求体**

```json
{
  "modelId": "deepseek-chat",
  "overrides": {
    "deepseek-chat": {
      "contextWindow": 128000
    }
  },
  "catalogCapability": {
    "contextWindow": 128000,
    "maxOutputTokens": 8192
  },
  "catalogSupportsVision": true
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "displayName": "...",
    "provider": "...",
    "contextWindow": 128000,
    "maxOutputTokens": 8192,
    "vision": false,
    "thinking": false
  }
}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/model-capabilities/resolve" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"deepseek-chat","overrides":{"deepseek-chat":{"contextWindow":128000}},"catalogCapability":{"contextWindow":128000,"maxOutputTokens":8192},"catalogSupportsVision":true}'
```

## 读取本版本的安全策略 {#get-api-security-policy}

`GET /api/security/policy` （助手可调用）

- Reports two switches of this build's security policy. `tunnelSafe: true` means Internet Access (the tunnel) is turned off by policy. `browserAllowlistEditable: true` means the AI Browser runs on an allowlist that users may extend.
- Needs no token and always answers.

**响应**

```ts
{"success":true,"data":{"tunnelSafe":boolean,"browserAllowlistEditable":boolean}}
```

**示例**

```bash
curl -s "$HALO_URL/api/security/policy" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取正在运行的 Halo 版本 {#get-api-system-version}

`GET /api/system/version` （助手可调用）

**响应**

```json
{
  "success": true,
  "data": "2.1.15"
}
```

**示例**

```bash
curl -s "$HALO_URL/api/system/version" \
  -H "Authorization: Bearer $HALO_TOKEN"
```