---
name: oneapi-custom-endpoint-setup
description: "Use when connecting Hermes Agent to a OneAPI-compatible proxy endpoint — set base_url, api_key, default model, auxiliary models, and delegation models."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [oneapi, custom-endpoint, proxy, model-config, deployment]
    related_skills: [hermes-agent]
---

# OneAPI / Custom Endpoint Setup

## Overview

OneAPI 提供了 OpenAI 兼容的 API 接口，可以作为 Hermes Agent 的模型后端。通过它可以用一个统一入口接入多个模型（如通义千问系列、嵌入模型等）。

配置项涉及三个层级：

1. **主模型** — 对话默认使用的模型
2. **辅助模型** — 压缩等后台任务使用的轻量模型
3. **子 Agent 模型** — `delegate_task` 子任务使用的模型

## When to Use

- 你有一个 OpenAI 兼容的 API 代理端点（如 OneAPI、NewAPI、LiteLLM 等）
- 需要接入私有部署的模型服务
- 想为不同任务分配不同规格的模型（大模型做主对话，小模型做压缩）

## 前置检查

确认端点可用：

```bash
# 查看可用模型列表
curl -s https://your-oneapi-domain/v1/models \
  -H "Authorization: Bearer your-api-key" \
  | python3 -m json.tool

# 测试对话
curl -s https://your-oneapi-domain/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","messages":[{"role":"user","content":"Say hi"}]}'
```

> ⚠️ **HTTPS 必须**：如果服务同时支持 HTTP 和 HTTPS，一定要用 HTTPS。HTTP 返回 301 重定向，会导致 POST 请求变成 GET 从而返回 404。

## 配置步骤

### 1. 主模型

```bash
hermes config set model.base_url https://your-oneapi-domain/v1
hermes config set model.api_key your-api-key
hermes config set model.default your-chat-model-name
hermes config set model.key_env ''   # 清除旧的 key_env 引用
```

`provider` 字段保持原值（如 `deepseek`）即可 — 实际请求由 `base_url` 决定。

### 2. 辅助压缩模型（后台任务用轻量模型）

```bash
hermes config set auxiliary.compression.model lightweight-model-name
hermes config set auxiliary.compression.base_url https://your-oneapi-domain/v1
hermes config set auxiliary.compression.api_key your-api-key
```

参考模型中对应 `auxiliary.{vision|web_extract|compression|...}` 等各个子任务，每个都支持独立配置 `model` / `base_url` / `api_key`。

推荐用轻量模型做压缩和标题生成等高频低强度任务。

### 3. 子 Agent 模型（delegation）

```bash
hermes config set delegation.model powerful-model-name
hermes config set delegation.base_url https://your-oneapi-domain/v1
hermes config set delegation.api_key your-api-key
```

子 Agent 处理高复杂度任务时可以用更大的模型。

### 4. 其他辅助任务设置

如果希望所有辅助任务也用同一个端点（而不走 `auto` 回退到 OpenRouter）：

```bash
hermes config set auxiliary.vision.base_url https://your-oneapi-domain/v1
hermes config set auxiliary.vision.api_key your-api-key
# 其他 auxiliary 子项类似：web_extract, title_generation, session_search 等
```

## 验证配置

```bash
hermes config show | grep -A5 -E "(Model|Delegat)"
```

查看输出确认 `base_url` 和 `api_key` 正确。

然后 `/reset` 新开 session 生效，输入 `Say hello` 测试。

## 典型配置示例

### 生产群场景

```yaml
model:
  default: qwen3.6-35b-64k-cuda       # 主对话用最强模型
  base_url: https://your-oneapi-domain/v1
  api_key: your-api-key

auxiliary:
  compression:
    model: qwen2.5:7b-128k            # 后台压缩用轻量模型
    base_url: https://your-oneapi-domain/v1
    api_key: your-api-key

delegation:
  model: qwen3.6-35b-64k-cuda         # 子Agent用同一大模型
  base_url: https://your-oneapi-domain/v1
  api_key: your-api-key
```

### 多模型分层场景

```yaml
model:
  default: Qwen3.6-27B-Q4_K_M         # 中等模型做日常对话
  base_url: https://oneapi-domain/v1
  api_key: your-api-key

auxiliary:
  compression:
    model: qwen2.5:7b-128k            # 轻量模型做压缩

delegation:
  model: qwen3.6-35b-64k-cuda         # 大模型做复杂子任务
  base_url: https://oneapi-domain/v1
  api_key: your-api-key
```

## 切换模型

配置完成后，在对话中用 `/model` 随时切换：
- `/model model-name` — 切换到指定模型（仅当前 session 有效）
- `/model` — 显示已支持的模型

## 注意事项

1. **必须用 HTTPS** — HTTP 请求会出现 301 重定向导致 POST→GET 引发 404
2. **OneAPI 的模型名区分大小写** — 需与 `/v1/models` 返回的 `id` 完全一致
3. **嵌入模型**（如 `bge-m3`）不能用于对话，如果作为主模型会报 500
4. **子任务的 model 字段仅一个字符串** — delegation 不支持配置多个模型
5. **配置后需 `/reset`** — tool/skill 变更需新 session 生效