---
title: "Hermes Agent 的 Hermes XAPI"
description: "安装并配置 Hermes XAPI 插件，在 Hermes Agent 中实现基于 Twexapi 的 X/Twitter 自动化。"
---

Hermes XAPI 是 Hermes Agent 原生插件，将 Twexapi 作为结构化 X/Twitter 自动化工具集。它打包 Twexapi 端点目录、读工具、可选操作工具、斜杠命令与捆绑 Hermes skill 为 Python 插件。

Hermes Agent 工作流需要 X/Twitter 搜索、账号读取、资料查询、趋势、粉丝、回复、文章、DM、发帖、点赞、转推、关注或账号状态检查时使用 Hermes XAPI。

## 前置条件

- Python `3.11` 或更新版本
- 支持插件的 Hermes Agent
- 来自 [dashboard](https://twexapi.io/dashboard) 的 Twexapi API 密钥

Hermes 插件为 opt-in。期望 `hermes-xapi` 工具集出现前须安装并启用插件。

## 安装

对公开 GitHub 仓库使用 Hermes 插件安装器：

```bash
hermes plugins install twexapi-dev/hermes-xapi --enable
```

交互式安装时 Hermes 会提示 `TWEXAPI_KEY` 并存入 `~/.hermes/.env`。非交互安装跳过提示。调用 `xapi_read` 前在进程环境或 `~/.hermes/.env` 设置密钥。

自行管理包安装时，将已发布 PyPI 包直接装到 Hermes Python 环境：

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-xapi
hermes plugins enable hermes-xapi
```

若 Hermes Python 环境含 `pip`，也可：

```bash
~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-xapi
hermes plugins enable hermes-xapi
```

当前包版本 `0.1.6`。插件名 `hermes-xapi`，Python 入口点 `hermes-xapi = hermes_xapi`。

## 配置

启动 Hermes 前设置 Twexapi API 密钥：

```bash
export TWEXAPI_KEY="twitterx_..."
```

持久 Hermes 会话在 `~/.hermes/.env` 添加：

```bash
TWEXAPI_KEY=twitterx_...
```

可选环境变量：

```bash
export TWEXAPI_BASE_URL="https://api.twexapi.io"
export HERMES_XAPI_ENABLE_ACTIONS="false"
```

无人值守会话保持 `HERMES_XAPI_ENABLE_ACTIONS=false`。仅有明确审批步骤的工作流启用操作：

```bash
export HERMES_XAPI_ENABLE_ACTIONS="true"
```

编辑 `~/.hermes/.env` 后若 Hermes 已在运行，在交互 CLI 执行 `/reload`，或重启 gateway 与 cron 会话后再调用 `xapi_read`。

## 工具

| 工具 | 用途 |
| --- | --- |
| `xapi_explore` | 搜索捆绑 Twexapi 端点目录且不发起 API 调用。每次实时端点调用前使用。 |
| `xapi_read` | 配置 `TWEXAPI_KEY` 后调用目录列出的只读端点。 |
| `xapi_action` | 仅当 `HERMES_XAPI_ENABLE_ACTIONS=true` 时调用私有、付费批量或类写端点。 |

每次实时调用前先 `xapi_explore`，以便AI Agent发现正确方法、路径、参数与响应形状。

```txt
Use xapi_explore to find the endpoint for user lookup, then call xapi_read for @username.
```

## 工作流 handoff

先 `xapi_explore`，公开读取选 `xapi_read`，经批准的创建或变更状态作业选 `xapi_action`。

### 推文搜索读取

`xapi_read` 配合 `/twitter/advanced_search/page` 或其他目录搜索端点。返回 tweet ID、文本、作者用户名、时间戳、互动指标，以及存在时的 `has_more`、`next_cursor`。

```txt
Use xapi_explore to find tweet search endpoints.
Use xapi_read for /twitter/advanced_search/page with searchTerms ["AI agents"] and maxItems 25.
Return tweet_id, text, author_username, created_at, and engagement counts.
```

### 趋势研究

`xapi_explore` 找趋势路由，再 `xapi_read` 调用 country、topic、content 或 trend 端点。

```txt
Use xapi_explore to find X/Twitter trend endpoints.
Use xapi_read to return current trends for worldwide.
Preserve the country, topic, content, rank, has_more, and next_cursor fields when present.
```

### 粉丝导出

`xapi_explore` 找粉丝端点。有界读取用 `xapi_read`；目录标记为私有、付费批量或 action-like 时仅用 `xapi_action`。

```txt
Use xapi_explore to find follower export endpoints.
Fetch followers for @username with a bounded count.
If the response returns a task_id, store it and poll the documented status and next-page routes.
```

### 受控写操作

审批后才用 `xapi_action`。无人值守会话保持操作工具禁用。

```txt
Use xapi_explore with include_actions true to find tweet posting endpoints.
Draft the exact request body.
Ask for explicit approval.
Only after approval, call xapi_action.
Return tweet_id, status, charged_credits, and any write action ID.
```

## 运行时诊断

可脚本化检查用 `hermes tools list`。裸 `hermes tools` 打开交互工具 UI 且需 TTY。

```bash
hermes tools list
```

插件启用后运行非变更 one-shot 探测：

```bash
hermes -z "Use xapi_explore, then read /twitter/elonmusk/about. Do not call xapi_action." --toolsets hermes-xapi
```

预期行为：

- 无 API 密钥时 `xapi_explore` 可检查目录端点。
- 无 `TWEXAPI_KEY` 时，非变更 Hermes 探测仅暴露 `xapi_explore`。
- 配置 `TWEXAPI_KEY` 并重载 CLI 或重启 gateway/cron 后，`xapi_read` 可读 `/twitter/elonmusk/about`。
- 除非 `HERMES_XAPI_ENABLE_ACTIONS=true`，否则 `xapi_action` 隐藏或禁用。
- `/xstatus` 与 `/xtrends` 出现在 Hermes 插件命令注册表。

Hermes one-shot prompt 不会将 `/xstatus` 当作交互斜杠命令派发。在活跃 CLI、TUI、Desktop 或 gateway 会话验证斜杠命令；工具调用探测用 `hermes -z`。

非交互安装无法提示凭证；在进程环境或 `~/.hermes/.env` 设置 `TWEXAPI_KEY`。

## 斜杠命令

| 命令 | 用途 |
| --- | --- |
| `/xstatus` | 在活跃 Hermes 会话显示 Twexapi 账号、订阅与使用状态。 |
| `/xtrends` | 从插件命令注册表显示当前 X/Twitter 趋势。 |

## 安全模型

Hermes XAPI 从环境变量读取 auth 并在请求时注入。模型不会将 API 密钥作为工具参数接收。

插件从AI Agent目录阻止 cookie/token 辅助路由、购买互动路由、自动 cookie 发帖、资料变更、列表创建与情感路由。私有读取、付费批量与类写端点走 `xapi_action`，除非 `HERMES_XAPI_ENABLE_ACTIONS=true` 否则隐藏。

无人值守作业保持操作工具禁用，仅用 `xapi_explore` 与 `xapi_read`。

## API 覆盖

Hermes XAPI 含 76 个由 OpenAPI 契约生成的可调用 Twexapi 端点。

| 领域 | 常见用途 |
| --- | --- |
| 公开读取 | 推文搜索、推文查询、用户查询、时间线、文章、回复与趋势。 |
| 私有读取 | 账号状态、余额与账号级检查。 |
| 关系数据 | 粉丝、关注、转推者、引用推文与点赞者。 |
| 社区与列表 | 社区元数据、成员、推文、列表推文、订阅者与成员。 |
| 操作 | 启用时可推文、回复、点赞、转推、关注、DM、媒体、书签、文章与账号操作。 |

## 本地开发

本地插件开发时，从 Twexapi OpenAPI 契约重新生成捆绑目录：

```bash
python scripts/build_catalog.py ../twexapi/openapi.yaml
```

Twexapi OpenAPI 文件变更后从 `hermes-xapi` 仓库运行该命令。

## 验证

安装、启用并设置 `TWEXAPI_KEY` 后运行：

```txt
/xstatus
```

可脚本化诊断列出插件工具集：

```bash
hermes tools list
```

再测试只读工作流：

```txt
Use xapi_explore to find X/Twitter trends, then use xapi_read to return current trends.
```

操作工作流在启用 `xapi_action` 前需明确草稿与审批。

## 故障排除

| 问题 | 修复 |
| --- | --- |
| 工具缺失 | 运行 `hermes plugins enable hermes-xapi`，确认 `hermes tools list` 含 `hermes-xapi`。 |
| 认证失败 | 确认 `TWEXAPI_KEY` 在启动 Hermes 的同一环境导出，或存于 `~/.hermes/.env`。 |
| 环境变更未生效 | 交互 CLI 运行 `/reload`，或重启 gateway 与 cron 会话。 |
| 操作工具隐藏 | 仅为经批准操作工作流设 `HERMES_XAPI_ENABLE_ACTIONS=true`。 |
| 端点缺失 | 本地开发从当前 Twexapi OpenAPI 重新生成目录。 |
|  risky 写操作 | 保持 `HERMES_XAPI_ENABLE_ACTIONS=false` 且仅用读工具。 |

## 与 XApiClaw 的关系

XApiClaw 是 OpenClaw 原生 npm 插件。Hermes XAPI 是 Hermes 原生 Python 插件。两者使用相同 Twexapi API 契约，并在实时端点调用前暴露AI Agent安全的目录发现。

## 参考

- [Hermes XAPI GitHub repo](https://github.com/twexapi-dev/hermes-xapi)
- [Hermes XAPI on PyPI](https://pypi.org/project/hermes-xapi/)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
- 侧边栏 API Reference
- [MCP Server](/mcp/overview)