Hermes Agent 的 Hermes XAPI

安装并配置 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 的 Twexapi API 密钥

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

安装

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

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

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

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

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

若 Hermes Python 环境含 pip，也可：

~/.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 密钥：

export TWEXAPI_KEY="twitterx_..."

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

TWEXAPI_KEY=twitterx_...

可选环境变量：

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

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

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发现正确方法、路径、参数与响应形状。

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。

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 端点。

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。

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。无人值守会话保持操作工具禁用。

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。

hermes tools list

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

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 契约重新生成捆绑目录：

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

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

验证

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

/xstatus

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

hermes tools list

再测试只读工作流：

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安全的目录发现。