> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Hermes Agent 中使用 AIsa

> 在 Hermes Agent 中快速连接 AIsa 的模型 API 和 capability layer。

你可以用一个 model endpoint 和一个 API key，在 Hermes Agent 中使用 AIsa。

AIsa endpoint：

```txt theme={null}
https://api.aisa.one/v1
```

## Prerequisites

开始前，请确认你已经具备：

* AIsa API key
* macOS、Linux 或 Windows WSL2 上的 terminal

## 1. 安装 Hermes Agent

运行官方 installer：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

重新加载 shell：

```bash theme={null}
source ~/.zshrc
```

验证安装：

```bash theme={null}
hermes doctor
```

## 2. 添加 AIsa 作为 model provider

运行：

```bash theme={null}
hermes model
```

Hermes 会提示你选择 model provider。

选择：

```txt theme={null}
Custom Model / OpenAI-compatible endpoint
```

![Select Custom Model / OpenAI-compatible endpoint](https://assets.aisaskills.com/custom-endpoint.png)

这会让 Hermes 通过 AIsa 的 OpenAI-compatible API 连接到 AIsa。

### 2.1 配置 AIsa endpoint

当 Hermes 询问 API endpoint 和 API key 时，输入：

```txt theme={null}
API base URL: https://api.aisa.one/v1
API key: YOUR_AISA_API_KEY
```

如果 endpoint 有效，Hermes 会显示它可以从 AIsa 访问模型列表：

```txt theme={null}
Verified endpoint via https://api.aisa.one/v1/models
167 model(s) visible
```

### 2.2 选择 API mode

![Hermes API compatibility mode prompt](https://assets.aisaskills.com/api-model.png)

选择 mode `1. Auto-detect` 或 `2. Chat Completions` 都可以，因为 base URL 以 `/v1` 结尾。推荐 mode 2，因为它更明确，也更容易 debug。

| Mode                  | Required base URL                 | Use for                                            |
| --------------------- | --------------------------------- | -------------------------------------------------- |
| 1. Auto-detect        | `https://api.aisa.one/v1`         | 对 `/v1` URL 解析为 Chat Completions                   |
| 2. Chat Completions   | `https://api.aisa.one/v1`         | 标准 OpenAI-compatible endpoints                     |
| 3. Responses / Codex  | `https://api.aisa.one/v1`         | Codex CLI 和需要 server-side state 的 reasoning models |
| 4. Anthropic Messages | `https://api.aisa.one/`（不带 `/v1`） | Claude Code 和其他 Anthropic-native clients           |

> 如果选择 mode 4，请回到 step 2.1，并从 base URL 中移除 `/v1`——Anthropic clients 会自己追加 `/v1/messages`。

### 2.3 选择模型

Hermes 会显示可用模型列表。

你可以输入模型序号，也可以直接输入模型名：

```txt theme={null}
Select model [1-167] or type name: gpt-5
```

选择 text、reasoning 或 coding 模型。不要选择 image、video、embedding、Whisper 或 TTS 模型作为 Hermes 主模型。

### 2.4 设置 context length

当 Hermes 询问：

```txt theme={null}
Context length in tokens [leave blank for auto-detect]:
```

直接按 Enter，留空即可。

## 3. 连接 AIsa capabilities 并开始使用

配置 model provider 后，启动 Hermes：

```bash theme={null}
hermes
```

然后把这段 prompt 粘贴到 Hermes：

```txt theme={null}
Read https://aisa.one/docs/agent-quickstart.md and help me safely connect, configure, and use AIsa's APIs, Skills, and LLMs in this agent environment.
```

Hermes 会获取 AIsa 面向 agent 的说明，并引导你完成剩余设置。

之后，你就可以在 Hermes 中使用 AIsa 模型和 capabilities。

可以试试：

```txt theme={null}
Use AIsa capabilities to search the web and summarize the latest information about Hermes Agent.
```

## Quick reference

| Item                    | Value                                                                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Provider type           | `Custom Model / OpenAI-compatible endpoint`                                                                                                              |
| API base URL            | `https://api.aisa.one/v1`                                                                                                                                |
| API mode                | `2. Chat Completions`                                                                                                                                    |
| Context length          | 留空以 auto-detect                                                                                                                                          |
| Capability setup prompt | `Read https://aisa.one/docs/agent-quickstart.md and help me safely connect, configure, and use AIsa's APIs, Skills, and LLMs in this agent environment.` |

## Troubleshooting

| Problem                                 | Fix                                                           |
| --------------------------------------- | ------------------------------------------------------------- |
| `hermes: command not found`             | 运行 `source ~/.zshrc` 或重新打开 terminal                           |
| Endpoint verification fails             | 确认 base URL 是 `https://api.aisa.one/v1`                       |
| Authentication error                    | 重新输入 AIsa API key                                             |
| Unsure which provider to choose         | 选择 `Custom Model / OpenAI-compatible endpoint`                |
| Unsure which API mode to choose         | 选择 `2. Chat Completions`                                      |
| Unsure what to enter for context length | 留空并按 Enter                                                    |
| Selected the wrong model                | 重新运行 `hermes model`，选择 text 或 coding 模型                       |
| Hermes does not know AIsa capabilities  | 把 `curl -sL https://aisa.one/docs/llms.txt` prompt 粘贴到 Hermes |

## 相关页面

<CardGroup cols={3}>
  <Card title="Use AIsa in OpenClaw" icon="screwdriver-wrench" href="/zh/guides/tutorials/openclaw-quick-setup">
    用 OpenClaw setup path 配置另一个 agent runtime。
  </Card>

  <Card title="Authentication" icon="key" href="/zh/guides/authentication">
    API key 创建、轮换和存储最佳实践。
  </Card>

  <Card title="Model Catalog" icon="list" href="/zh/guides/models">
    选择 Hermes 默认模型前，先浏览支持的模型。
  </Card>
</CardGroup>