Halo

简体中文

English

简体中文

English

外观

API：设置与模型 ​

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

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

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 $HALO_URL 和 $HALO_TOKEN 按快速上手设置；地址、鉴权和错误约定见 HTTP API 概览。

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

列出已安装的 Agent 引擎及当前使用的引擎 ​

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 助手可调用

  • 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 助手可调用

  • "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 助手可调用

  • 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 可撤销 助手可调用

  • 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 可撤销 助手可调用

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

路径参数

名称说明
sourceId模型来源 ID，来自 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 不可撤销 助手可调用

不可撤销

执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。 只想做范围更小的操作时，改用 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 > AI Model. Confirm before deleting.

路径参数

名称说明
sourceId模型来源 ID，来自 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 可撤销 助手可调用

  • 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 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 助手可调用

  • What this build could be configured with, not what the user has configured — read 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 助手可调用

  • 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 助手可调用

  • 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 助手可调用

  • Use it when 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 助手可调用

  • 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 助手可调用

  • 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 助手可调用

  • 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 助手可调用

  • 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 助手可调用

响应

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

示例

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

基于 MIT 协议开源 · Open source under the MIT license

© 2025 Halo · hello-halo.cc