canonical_url: https://yycode.net/docs/zh-TW/hermes-quickstart
lang: zh-TW
updated_at: 2026-07-04T13:33:48.616Z
source_html: https://yycode.net/docs/zh-TW/hermes-quickstart

# yycode × Hermes 快速開始指南

## 適用場景

這篇指南只解決一件事：把 yycode 的 Anthropic 相容介面接到 Hermes，並完成一次最小可用驗證。

如果你目前用的是 Hermes，而不是 OpenClaw、Cherry Studio 或其他客戶端，這篇指南就是對應的接入方式。

---

## 1. 準備事項

開始前請先確認以下幾點：

- 你已經在 [yycode 控制台](https://yycode.net/console/token) 建立好一枚 API Key
- 你知道 Hermes 目前要調用的實際模型名
- 你可以編輯 Hermes 的設定檔 `config.yaml`
- 你本次要接的是 yycode 的 Anthropic 相容端點，不是 OpenAI 相容端點

---

## 2. 支援的模型

目前這篇指南優先覆蓋 yycode 的 Anthropic 相容模型接入，常見模型名如下：

| 模型名 |
|---|
| `claude-opus-4-6` |
| `claude-sonnet-4-6` |
| `claude-haiku-4-5-20251001` |

如果你不確定自己帳號目前實際可用的模型，以控制台或你現有可調用記錄為準。

---

## 3. 推薦路徑：通過 Hermes 的 `custom_providers` 接入

Hermes 接 yycode 時，核心思路是：

1. 在 `custom_providers` 中聲明一個 yycode provider
2. 在 `model` 塊中把預設模型指向這個 provider
3. 關閉 `smart_model_routing`，避免 Hermes 自動切到別的模型

### 第一步：定義自定義 provider

```yaml
custom_providers:
  - name: custom-yycode-net-aws
    base_url: https://yycode.net
    api_key: <your-key>
    api_mode: anthropic_messages
    models:
      - claude-opus-4-6
```

這裡最關鍵的是兩點：

- `base_url` 寫 `https://yycode.net`
- `api_mode` 必須寫 `anthropic_messages`

### 第二步：把預設模型指向這個 provider

```yaml
model:
  default: claude-opus-4-6
  provider: custom-yycode-net-aws
  base_url: https://yycode.net
  api_key: <your-key>
  api_mode: anthropic_messages
```

這裡的 `provider` 必須和上面 `custom_providers` 裡的 `name` 對應上，否則 Hermes 不會走到你定義的 Dragon Code provider。

### 第三步：關閉 Smart Model Routing

```yaml
smart_model_routing:
  enabled: false
```

如果不關，Hermes 可能會因為訊息較短而自動切到更便宜的模型，導致你明明設定了 `claude-opus-4-6`，實際跑的卻不是它。

---

## 4. 可直接參考的最小可用設定

下面是一份合並後的最小可用範例。把 `<your-key>` 換成你自己的 Dragon Code API Key 即可：

```yaml
model:
  default: claude-opus-4-6
  provider: custom-yycode-net-aws
  base_url: https://yycode.net
  api_key: <your-key>
  api_mode: anthropic_messages

custom_providers:
  - name: custom-yycode-net-aws
    base_url: https://yycode.net
    api_key: <your-key>
    api_mode: anthropic_messages
    models:
      - claude-opus-4-6

smart_model_routing:
  enabled: false

fallback_providers:
  - provider: minimax-cn
    model: MiniMax-M2.7
```

如果你想切換到別的 Anthropic 相容模型，只需要把 `model.default` 和 `custom_providers[].models` 中的模型名一起改掉。

---

## 5. 成功標準

滿足下面幾項，基本就說明 Hermes 和 Dragon Code 已經接通：

- `base_url` 填寫的是 `https://yycode.net`
- `api_mode` 填寫的是 `anthropic_messages`
- `model.provider` 指向的是你在 `custom_providers` 中定義的 provider 名
- `smart_model_routing.enabled` 已關閉
- Hermes 發起訊息後，實際能正常收到模型回覆

---

## 6. 常見問題

### 為什麼不能按 OpenAI 相容方式接？

這次 Hermes 接 yycode，應該走 Anthropic 原生訊息格式，也就是 `/v1/messages`。

已知結論是：

- `/v1/messages` 可用
- `/v1/chat/completions` 不適合作為這篇 Hermes 設定方案的主路徑

所以 `api_mode` 必須寫成 `anthropic_messages`，不要按 OpenAI 相容模式去配。

### 為什麼我明明選了 `claude-opus-4-6`，實際卻跑了別的模型？

優先檢查 `smart_model_routing.enabled` 是否已經關閉。

如果 Hermes 開著智慧路由，短訊息可能會被自動切到便宜模型，導致你的介面選擇和真實請求模型不一致。

### `api_key_env` 能不能用？

基於目前這份設定記錄，Hermes v0.10.0 下的 `api_key_env` 在 `model` 和 `custom_providers` 塊裡存在不穩定情況，可能導致環境變數沒有正確展開，最後回傳 401。

如果你已經確認是這個問題，可以先退回到直接填寫 `api_key` 的方式，先把鏈路打通，再決定是否繼續排查環境變數方案。

### 為什麼回傳 401？

通常先查這幾項：

- API Key 是否有效
- `api_key` 是否填到了 `model` 和 `custom_providers` 需要的位置
- Hermes 目前是否真的載入到了你修改後的設定檔

### 為什麼回傳 503 或服務不可用？

如果你目前設定走的是 OpenAI 相容路徑，先回頭檢查是不是把 Hermes 配成了錯誤的 `api_mode`。

這篇指南的推薦路徑是 Anthropic 相容接法，不建議把它和 OpenAI 相容寫法混用。

---

## 7. API 驗證範例

如果你想先繞過 Hermes，直接驗證 Dragon Code 端點本身是否可用，可以先調用 Anthropic 原生端點：

```bash
curl -X POST "https://yycode.net/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-key>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus-4-6","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'
```

如果這個請求能正常回傳，再回頭檢查 Hermes 設定，排障會更直接。

---

## 8. 下一步

- 想繼續接其他客戶端：檢視 `OpenClaw 快速开始指南`、`Cherry Studio 快速开始指南`
- 還沒建立 Key：回到 [yycode 控制台](https://yycode.net/console/token) 先建立 API Key
- 想統一整理開發工具設定：繼續檢視站內其他快速接入指南