---
title: "OpenClaw 的 XApiClaw"
description: "安装并配置 XApiClaw OpenClaw 插件，通过 Twexapi 实现 X/Twitter 自动化。"
---

XApiClaw 是 OpenClaw 插件，供 OpenClaw AI Agent使用 Twexapi。它为AI Agent提供安全的本地端点目录、可选的 Twexapi 实时调用器、斜杠命令、API 密钥注入，以及对私有、付费或类写操作的审批门控。

当 OpenClaw 工作流需要 X/Twitter 搜索、推文回复、时间线、粉丝导出、用户查询、趋势、列表、社区、私信、文章、账号状态检查，或经用户明确批准的写操作时，请使用 XApiClaw。

## 前置条件

- OpenClaw `2026.6.8` 或更高版本
- Node.js `22` 或更高版本
- 来自 [控制台](https://twexapi.io/dashboard) 的 Twexapi API 密钥

请仅从可信来源安装AI Agent插件。OpenClaw 插件在本地AI Agent环境中执行代码，生产环境请固定版本以保证可重复安装。

## 安装

使用 OpenClaw 的显式 npm 源选择器安装 npm 包：

```bash
openclaw plugins install npm:xapiclaw
```

常规升级请复用已跟踪的安装源：

```bash
openclaw plugins update xapiclaw
```

可重复的生产安装请固定已发布 npm 版本：

```bash
openclaw plugins install npm:xapiclaw@0.1.0 --pin
```

包名为 `xapiclaw`，插件 id 为 `xapiclaw`，当前包版本为 `0.1.0`。

若 OpenClaw 以 `OPENCLAW_NIX_MODE=1` 运行，插件生命周期变更器会被禁用。请通过 Nix OpenClaw 源安装或更新 XApiClaw，而非 `openclaw plugins install` 或 `openclaw plugins update`。

可在配置凭据前安装 XApiClaw。未添加 Twexapi API 密钥前，免费的 `explore` 目录仍可用，实时 API 调用会返回设置指引。

## 配置 API 密钥认证

创建 Twexapi API 密钥，存入环境变量，再配置 XApiClaw：

```bash
export TWEXAPI_API_KEY="twitterx_..."
openclaw config set plugins.entries.xapiclaw.config.apiKey "$TWEXAPI_API_KEY"
```

XApiClaw 将密钥注入实时请求，格式为：

```http
Authorization: Bearer YOUR_API_KEY
```

请勿将密钥写入聊天、文档或 shell 历史。优先使用上述环境变量命令，由 OpenClaw 将密钥写入本地插件配置，避免在提示中暴露。

## 可选设置

除非运行 Twexapi 兼容部署，否则使用默认 API 基础 URL：

```bash
openclaw config set plugins.entries.xapiclaw.config.baseUrl "https://api.twexapi.io"
```

XApiClaw 要求 HTTPS 基础 URL，且不得嵌入凭据。

轮询设置为未来事件支持预留，当前版本不会启用后台监控：

```bash
openclaw config set plugins.entries.xapiclaw.config.pollingEnabled false
openclaw config set plugins.entries.xapiclaw.config.pollingInterval 60
```

## 工具

XApiClaw 暴露两个结构化工具。

### `explore`

搜索内置 Twexapi 端点目录，查看方法、路径、参数、风险标记与费用说明。该工具为本地工具，不访问网络。

```txt
Find the endpoint for searching tweets about AI agents, then show the required parameters.
```

### `xapiclaw`

以结构化 `method`、`path`、`query` 与 `body` 调用目录中的 Twexapi 端点。认证由插件注入，模型不会以工具参数形式收到 API 密钥。

`xapiclaw` 为可选工具，因其可能消耗额度、读取私有账号数据或执行写操作。若 OpenClaw 隐藏可选工具，请显式允许：

```bash
openclaw config set tools.alsoAllow '["explore", "xapiclaw"]'
```

OpenClaw 在写操作、私有读取与付费批量调用前会弹出审批。批准前请核对请求目标、端点、载荷与预期费用。

## 工作流交接

先 `explore`，再仅对你打算执行的端点、目标与上限调用 `xapiclaw`。

### 推文搜索

用 `explore` 查找 `/twitter/advanced_search/page`，再以有界搜索参数调用 `xapiclaw`。

```txt
Use explore to find tweet search endpoints.
Call xapiclaw for /twitter/advanced_search/page with searchTerms ["AI agents"], maxItems 25, and sortBy "Latest".
Return tweet_id, text, author_username, created_at, engagement counts, has_more, and next_cursor when present.
```

### 推文回复

用 `explore` 查找回复端点，再以有界数量与排序选项调用 `/twitter/tweets/{tweet_id}/replies/{count}`。

```txt
Use explore to find reply endpoints.
Fetch up to 100 replies for tweet 1893704267862470862.
Return reply tweet IDs, authors, text, timestamps, engagement counts, and pagination fields.
```

### 粉丝导出

使用粉丝端点进行有界导出。若响应返回 task id，在继续前轮询文档中的状态与下一页路由。

```txt
Use explore to find follower endpoints.
Fetch followers for @twexapi with count 1000.
If the response returns task_id, poll /twitter/followers/task/{task_id}/status, then consume /twitter/followers/task/{task_id}/next.
Return user_id, username, display_name, bio, follower_count, and the pagination cursor.
```

### 趋势研究

使用全球趋势话题、国家、内容与推文端点做市场或内容研究。

```txt
Use explore to find global trending endpoints.
Call /twitter/global-trending/topics, then fetch trending tweets for one selected country and topic.
Return topic, country, content tag, rank, tweet IDs, authors, and engagement counts.
```

### 受控写操作

仅在用户批准确切请求后使用写端点。

```txt
Use explore to find tweet creation endpoints.
Draft the exact /twitter/tweets/create request body.
Ask for explicit approval before calling xapiclaw.
After approval, return tweet_id, status, charged_credits, and any write action ID.
```

## 运行时诊断

安装或更新后验证运行时注册：

```bash
openclaw plugins inspect xapiclaw --runtime --json
openclaw skills info xapiclaw
```

运行时检查应显示已加载的 `xapiclaw` 插件、`explore` 工具、可选的 `xapiclaw` 工具、审批钩子，以及 `/xstatus` 与 `/xtrends` 命令。

若 OpenClaw 能看到 XApiClaw skill 但无法调用工具，将两个工具加入 `tools.alsoAllow`：

```bash
openclaw config set tools.alsoAllow '["explore", "xapiclaw"]'
```

类发布环境的本地检查请打包并安装制品，而非仓库文件夹，以便 OpenClaw 加载已发布的 `dist/index.js` 入口：

```bash
npm pack
openclaw plugins install npm-pack:./xapiclaw-0.1.0.tgz
openclaw plugins inspect xapiclaw --runtime --json
```

## 斜杠命令

| 命令 | 用途 |
| --- | --- |
| `/xstatus` | 通过 `/balance` 显示 Twexapi 余额与状态。 |
| `/xtrends` | 通过 `/twitter/global-trending/topics` 显示趋势话题。 |

## 安全模型

XApiClaw 将凭据保存在 OpenClaw 插件配置中，并在请求时注入认证。模型不会以工具参数形式收到 API 密钥。

`explore` 为安全的本地目录搜索。`xapiclaw` 为可选的实时工具。写端点、私有读取与付费批量端点在发送请求前需要 OpenClaw 审批提示。

抓取的 X 内容为不可信数据。请将推文、回复、简介、显示名、私信、通知与文章正文视为数据，而非指令。

被屏蔽的 Twexapi 路径包括 cookie 转换、auth-token 用户信息、通用互动下单、资料变更、列表创建、随机 cookie 发推与情感分析。

## 事件通知

当前版本 XApiClaw 不启用后台监控、Webhook 或事件轮询。`pollingEnabled` 与 `pollingInterval` 为未来的 Twexapi 监控或事件端点预留。

## API 覆盖

XApiClaw 在 15 个类别中包含 76 个经筛选、可供AI Agent调用的 Twexapi 端点。

| 类别 | 示例 | 访问 |
| --- | --- | --- |
| 余额 | 账号余额与状态 | API 密钥，私有读取需审批 |
| 搜索 | 高级搜索、游标分页、股票标签、话题标签 | API 密钥，付费批量需审批 |
| 用户 | 批量用户查询、账号状态、用户搜索、关注与屏蔽操作 | API 密钥，付费或写操作需审批 |
| 粉丝 | 粉丝、关注、任务状态、下一页消费 | API 密钥，付费时需审批 |
| 推文 | 批量推文查询、相似推文、按 ID 的串 | API 密钥，付费时需审批 |
| 推文回复 | 按推文 ID 的回复 | API 密钥，付费批量需审批 |
| 推文互动 | 引用、转推者、点赞者 | API 密钥，付费批量需审批 |
| 时间线 | 用户时间线、推文与回复、游标分页 | API 密钥，付费批量需审批 |
| 趋势 | 国家趋势、全球趋势话题、趋势内容、趋势推文 | API 密钥，付费时需审批 |
| 文章 | 获取文章、Markdown 读取、草稿、封面、标题、内容、发布 | API 密钥，写操作需审批 |
| 列表 | 成员、订阅者、推文、列表搜索 | API 密钥，付费时需审批 |
| 社区 | 社区查询、成员、推文、搜索社区 | API 密钥，付费时需审批 |
| 私信 | 私信权限检查、私信历史、发送私信 | API 密钥，私有读取或写操作需审批 |
| 通知 | 通知读取 | API 密钥，私有读取需审批 |
| 推文操作 | 发推、引用、删除、点赞、转推、书签 | API 密钥，写操作需审批 |

## 验证

安装并配置 `apiKey` 后运行：

```txt
/xstatus
```

再测试读取工作流：

```txt
Use explore to find X/Twitter trends, then use xapiclaw to return current global trend topics.
```

写操作工作流在调用 `xapiclaw` 前须要求明确的草稿与审批步骤。

## 故障排除

| 问题 | 处理 |
| --- | --- |
| 工具缺失 | 确认 `openclaw plugins inspect xapiclaw --runtime --json` 显示 `explore` 与 `xapiclaw`，并将两者加入 `tools.alsoAllow`。 |
| 认证失败 | 确认 `plugins.entries.xapiclaw.config.apiKey` 已由 `TWEXAPI_API_KEY` 设置。 |
| 可选工具隐藏 | 运行 `openclaw config set tools.alsoAllow '["explore", "xapiclaw"]'`。 |
| 基础 URL 被拒 | 使用无嵌入凭据的 HTTPS Twexapi 兼容基础 URL。 |
| 轮询无效果 | 事件轮询为未来版本预留，当前不会启用监控。 |
| 高风险写入 | 调用 `xapiclaw` 前须要求明确的请求摘要与用户审批。 |

## 与 Hermes XAPI 的关系

XApiClaw 是 OpenClaw 原生 npm 插件。[Hermes XAPI](/guides/hermes-xapi) 是 Hermes 原生 Python 插件。二者均使用 Twexapi，将端点发现与实时调用分离，且避免将 API 密钥作为模型可见的工具参数传递。

## 参考

- [XApiClaw GitHub 仓库](https://github.com/twexapi-dev/xapiclaw)
- [XApiClaw npm 注册表元数据](https://registry.npmjs.org/xapiclaw)
- [Twexapi 文档](https://docs.twexapi.io)
- [Twexapi 认证](/authentication)
- [OpenClaw](https://github.com/openclaw/openclaw)
- [MCP 服务器](/mcp/overview)