> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.joytokens.ai/llms.txt.

# Hermes Agent

> 使用 Hermes Agent 接入 JoyToken

## 前提条件

| 项目              | 值                       |
| --------------- | ----------------------- |
| Hermes Agent 版本 | `0.15.2`                |
| 配置文件            | `~/.hermes/config.yaml` |
| 环境变量文件          | `~/.hermes/.env`        |
| Provider        | `joytoken`              |
| 模型名             | `auto`                  |
| API Key 环境变量    | `JOY_TOKEN_API_KEY`     |

Hermes Agent 支持两种协议，通过命名 custom provider 接入。`transport` 必须和所选 tab 一致。

## 第 1 步：安装

```bash
pipx install hermes-agent==0.15.2
hermes --version
```

## 第 2 步：设置 API Key 和 Base URL

#### OpenAI

```bash
export JOY_TOKEN_API_KEY="sk-xxx"
export JOY_TOKEN_OPENAI_BASE_URL="https://api-staging.joytokens.ai/openai/v1"
```

#### Anthropic

```bash
export JOY_TOKEN_API_KEY="sk-xxx"
export JOY_TOKEN_ANTHROPIC_BASE_URL="https://api-staging.joytokens.ai/anthropic/v1"
```

创建 `~/.hermes/.env` 保存 API Key，并把所选 Base URL 保留在 shell 或配置文件中。限制 env 文件权限：

```bash
mkdir -p ~/.hermes
printf '%s\n' 'JOY_TOKEN_API_KEY="sk-xxx"' > ~/.hermes/.env
chmod 600 ~/.hermes/.env
```

## 第 3 步：配置 provider

#### OpenAI

```bash
JOY_TOKEN_OPENAI_BASE_URL="${JOY_TOKEN_OPENAI_BASE_URL:-https://api-staging.joytokens.ai/openai/v1}"
mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml <<EOF
model:
  provider: joytoken
  default: auto

providers:
  joytoken:
    name: JoyToken
    base_url: $JOY_TOKEN_OPENAI_BASE_URL
    key_env: JOY_TOKEN_API_KEY
    default_model: auto
    transport: chat_completions
EOF
```

#### Anthropic

```bash
JOY_TOKEN_ANTHROPIC_BASE_URL="${JOY_TOKEN_ANTHROPIC_BASE_URL:-https://api-staging.joytokens.ai/anthropic/v1}"
mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml <<EOF
model:
  provider: joytoken
  default: auto

providers:
  joytoken:
    name: JoyToken
    base_url: $JOY_TOKEN_ANTHROPIC_BASE_URL
    key_env: JOY_TOKEN_API_KEY
    default_model: auto
    transport: anthropic_messages
EOF
```

## 第 4 步：验证

```bash
hermes config check
hermes chat \
  -q "Reply with exactly: pong" \
  --provider joytoken \
  -m auto \
  -Q \
  --ignore-rules
```

成功时，返回内容包含 `pong`。Hermes 可能在回复前打印 Python 包或 security scanner warning；只要包含 `pong`，就说明 JoyToken 请求成功。

## JoyToken 侧检查

#### OpenAI

| 位置    | 应看到                                 |
| ----- | ----------------------------------- |
| Logs  | 请求路径是 `/openai/v1/chat/completions` |
| 认证    | Bearer 认证                           |
| Usage | 本次调用产生 tokens 和 credits             |

#### Anthropic

| 位置    | 应看到                            |
| ----- | ------------------------------ |
| Logs  | 请求路径是 `/anthropic/v1/messages` |
| 认证    | `x-api-key` 认证                 |
| Usage | 本次调用产生 tokens 和 credits        |

## 常见错误

| 错误                    | 处理方式                                          |
| --------------------- | --------------------------------------------- |
| `401 Unauthorized`    | 检查 `~/.hermes/.env` 里的 `JOY_TOKEN_API_KEY`    |
| Hermes 仍调用其他 provider | 检查 `model.provider: joytoken` 和所选 `transport` |
| 配置检查失败                | 检查 `providers.joytoken.key_env` 和 `base_url`  |
| JoyToken 没有日志         | 检查 URL、transport 是否与所选协议 tab 一致               |

## 相关资源

* [JoyToken API 指南](/zh/open-api/api-guides/overview)
* [JoyToken 路由](/zh/user-guide/routing)
* [JoyToken 用量与账单](/zh/user-guide/usage-billing)