xurl

xurl — 通过官方 CLI 调用 X（Twitter）API

xurl 是 X 开发者平台用于调用 X API 的官方 CLI。它支持常见操作的快捷命令，也支持通过类似 curl 的方式访问任何 v2 端点。所有命令都会将 JSON 输出到 stdout。

将此技能用于：

• 发布、回复、引用和删除帖子
• 搜索原始帖子（包含可用于互动的 ID 的实际帖子 JSON），以及读取时间线和提及
• 点赞、转帖和收藏
• 关注、取消关注、屏蔽和静音
• 直接消息
• 媒体上传（图片和视频）
• 访问任何 X API v2 端点
• 多应用／多账户工作流

此技能取代了旧版 xitter 技能（它封装了第三方 Python CLI）。xurl 由 X 开发者平台团队维护，支持带自动刷新的 OAuth 2.0 PKCE，并涵盖范围大得多的 API。

---

密钥安全（强制要求）

在 Agent／大模型会话中操作时，必须遵守以下关键规则：

• 绝不要读取、打印、解析、总结、上传或将 ~/.xurl 发送到大模型上下文中。
• 绝不要要求用户在聊天中粘贴凭据或令牌。
• 用户必须在自己的机器上手动将密钥填入 ~/.xurl。在 Docker 中，这必须是 Hermes 工具子进程所看到的 ~；请参阅下方的 Docker 说明。
• 绝不要在 Agent 会话中建议或执行带内联密钥的认证命令。
• 绝不要在 Agent 会话中使用 --verbose / -v，这些选项可能会暴露认证标头／令牌。
• 验证凭据是否存在时，只能使用：xurl auth status

Agent 命令中禁止使用以下标志（它们接受内联密钥）： --bearer-token、--consumer-key、--consumer-secret、--access-token、--token-secret、--client-id、--client-secret

应用凭据注册和凭据轮换必须由用户在 Agent 会话之外手动完成。注册凭据后，用户需在 Agent 会话之外使用 xurl auth oauth2 完成认证。令牌以 YAML 格式持久化到 ~/.xurl。每个应用的令牌彼此隔离。OAuth 2.0 令牌会自动刷新。

---

安装

选择一种方法。在 Linux 上，shell 脚本或 go install 是最简单的方式。

# Shell script (installs to ~/.local/bin, no sudo, works on Linux + macOS)
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

# Homebrew (macOS)
brew install --cask xdevplatform/tap/xurl

# npm
npm install -g @xdevplatform/xurl

# Go
go install github.com/xdevplatform/xurl@latest

验证：

xurl --help
xurl auth status

如果已安装 xurl，但 auth status 未显示任何应用或令牌，用户需要手动完成认证——请参阅下一节。

---

一次性用户设置（用户在 Agent 外部运行）

这些步骤必须由用户直接执行，而不是由 Agent 执行，因为其中涉及粘贴密钥。请引导用户前往此区块；不要代替他们执行。

1. 在 https://developer.x.com/en/portal/dashboard 创建或打开一个应用

2. 将重定向 URI 设置为 http://localhost:8080/callback

3. 复制应用的 Client ID 和 Client Secret

4. 在本地注册应用（由用户运行）：

   xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
   

5. 进行身份验证（指定 --app，将令牌绑定到你的应用）：

   xurl auth oauth2 --app my-app
   

   （这会打开浏览器，进行 OAuth 2.0 PKCE 流程。）

   如果 X 在 OAuth 后查询 /2/users/me 时返回 UsernameNotFound 错误或 403，请明确传入你的账号名（xurl v1.1.0+）：

   xurl auth oauth2 --app my-app YOUR_USERNAME
   

   这会将令牌绑定到你的账号名，并跳过有问题的 /2/users/me 调用。

6. 将该应用设为默认应用，让所有命令都使用它：

   xurl auth default my-app
   

7. 验证：

   xurl auth status
   xurl whoami
   

完成后，Agent 无需进一步设置即可使用下方任何命令。OAuth 2.0 令牌会自动刷新。

常见问题： 如果在 xurl auth oauth2 中省略 --app my-app，OAuth 令牌会保存到内置的 default 应用配置中——该配置没有 client-id 或 client-secret。即使 OAuth 流程看起来已成功，命令也会因身份验证错误而失败。如果遇到此问题，请重新运行 xurl auth oauth2 --app my-app 和 xurl auth default my-app。

Docker HOME 问题： 在官方 Hermes Docker 布局中，/opt/data 是 HERMES_HOME，但 Hermes 工具子进程使用 /opt/data/home 作为 HOME。这意味着对于 Hermes 运行的 xurl 命令，~/.xurl 会解析为 /opt/data/home/.xurl，而不是 /opt/data/.xurl。请使用相同的 HOME 运行用户设置：

HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth status

如果 HOME=/opt/data xurl auth status 成功，但 HOME=/opt/data/home xurl auth status 显示没有应用或令牌，那么 Hermes 工具调用将无法获取这些凭据。

---

快速参考

操作	命令
发布	xurl post "Hello world!"
回复	xurl reply POST_ID "Nice post!"
引用	xurl quote POST_ID "My take"
删除帖子	xurl delete POST_ID
阅读帖子	xurl read POST_ID
搜索帖子	xurl search "QUERY" -n 10
我是谁	xurl whoami
查找用户	xurl user @handle
首页时间线	xurl timeline -n 20
提及	xurl mentions -n 10
点赞 / 取消点赞	xurl like POST_ID / xurl unlike POST_ID
转发 / 撤销转发	xurl repost POST_ID / xurl unrepost POST_ID
收藏 / 取消收藏	xurl bookmark POST_ID / xurl unbookmark POST_ID
列出收藏 / 点赞	xurl bookmarks -n 10 / xurl likes -n 10
关注 / 取消关注	xurl follow @handle / xurl unfollow @handle
正在关注 / 关注者	xurl following -n 20 / xurl followers -n 20
屏蔽 / 取消屏蔽	xurl block @handle / xurl unblock @handle
静音 / 取消静音	xurl mute @handle / xurl unmute @handle
发送私信	xurl dm @handle "message"
列出私信	xurl dms -n 10
上传媒体	xurl media upload path/to/file.mp4
媒体状态	xurl media status MEDIA_ID
列出应用	xurl auth apps list
移除应用	xurl auth apps remove NAME
设置默认应用	xurl auth default APP_NAME [USERNAME]
单次请求指定应用	xurl --app NAME /2/users/me
身份验证状态	xurl auth status

注意：

• POST_ID 也接受完整 URL（例如 https://x.com/user/status/1234567890）——xurl 会提取 ID。
• 用户名可以带或不带前导 @。

---

命令详情

发布

xurl post "Hello world!"
xurl post "Check this out" --media-id MEDIA_ID
xurl post "Thread pics" --media-id 111 --media-id 222

xurl reply 1234567890 "Great point!"
xurl reply https://x.com/user/status/1234567890 "Agreed!"
xurl reply 1234567890 "Look at this" --media-id MEDIA_ID

xurl quote 1234567890 "Adding my thoughts"
xurl delete 1234567890

阅读与搜索

xurl search 会以你已通过身份验证的账号查询 X 索引，并返回原始帖子对象，包括 ID、作者和完整文本，因此可以立即对搜索结果进行互动（回复、点赞、转发、引用）。当你需要获取实际帖子，而不是关于某个主题的摘要时，请使用它。

xurl read 1234567890
xurl read https://x.com/user/status/1234567890

xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15

对于 X Articles，请使用原始 API 模式，而不是 read 快捷方式。xurl read 需要帖子 ID 或帖子 URL；不要在 /2/tweets/... 端点前加上 read。请求 article 推文字段，并从 JSON 响应中提取 data.article.plain_text：

xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'

用户、时间线、提及

xurl whoami
xurl user elonmusk
xurl user @XDevelopers

xurl timeline -n 25
xurl mentions -n 20

互动

xurl like 1234567890
xurl unlike 1234567890

xurl repost 1234567890
xurl unrepost 1234567890

xurl bookmark 1234567890
xurl unbookmark 1234567890

xurl bookmarks -n 20
xurl likes -n 20

社交关系图

xurl follow @XDevelopers
xurl unfollow @XDevelopers

xurl following -n 50
xurl followers -n 50

# Another user's graph
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

xurl block @spammer
xurl unblock @spammer
xurl mute @annoying
xurl unmute @annoying

私信

xurl dm @someuser "Hey, saw your post!"
xurl dms -n 25

媒体上传

# Auto-detect type
xurl media upload photo.jpg
xurl media upload video.mp4

# Explicit type/category
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# Videos need server-side processing — check status (or poll)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID

# Full workflow
xurl media upload meme.png                  # returns media id
xurl post "lol" --media-id MEDIA_ID

---

原始 API 访问

快捷方式涵盖了常见操作。其他操作可使用面向任意 X API v2 端点的原始 curl 风格模式：

# GET
xurl /2/users/me

# POST with JSON body
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'

# DELETE / PUT / PATCH
xurl -X DELETE /2/tweets/1234567890

# Custom headers
xurl -H "Content-Type: application/json" /2/some/endpoint

# Force streaming
xurl -s /2/tweets/search/stream

# Full URLs also work
xurl https://api.x.com/2/users/me

---

全局标志

标志	简写	描述
--app		使用指定的已注册应用（覆盖默认应用）
--auth		强制指定身份验证类型：oauth1、oauth2 或 app
--username	-u	要使用的 OAuth2 账号（如果有多个）
--verbose	-v	禁止在 Agent 会话中使用——会泄露身份验证标头
--trace	-t	添加 X-B3-Flags: 1 跟踪标头

---

流式传输

系统会自动检测流式传输端点，包括以下已知端点：

• /2/tweets/search/stream
• /2/tweets/sample/stream
• /2/tweets/sample10/stream

使用 -s 可在任意端点上强制启用流式传输。

---

输出格式

所有命令都会将 JSON 输出到 stdout。结构与 X API v2 一致：

{ "data": { "id": "1234567890", "text": "Hello world!" } }

错误也会以 JSON 格式输出：

{ "errors": [ { "message": "Not authorized", "code": 403 } ] }

---

常见工作流

发布带图片的帖子

xurl media upload photo.jpg
xurl post "Check out this photo!" --media-id MEDIA_ID

回复对话

xurl read https://x.com/user/status/1234567890
xurl reply 1234567890 "Here are my thoughts..."

搜索并互动

xurl search "topic of interest" -n 10
xurl like POST_ID_FROM_RESULTS
xurl reply POST_ID_FROM_RESULTS "Great point!"

查看你的活动

xurl whoami
xurl mentions -n 20
xurl timeline -n 20

多个应用（手动预先配置凭据）

xurl auth default prod alice               # prod app, alice user
xurl --app staging /2/users/me             # one-off against staging

---

错误处理

• 发生任何错误时，退出码均为非零。
• API 错误仍会以 JSON 格式输出到 stdout，因此可以解析。
• 身份验证错误 → 让用户在 Agent 会话之外重新运行 xurl auth oauth2。
• 需要调用者用户 ID 的命令（例如点赞、转发、收藏、关注等）会通过 /2/users/me 自动获取该 ID。若此处身份验证失败，会显示为身份验证错误。

---

Agent 工作流

1. 验证前置条件：xurl --help 和 xurl auth status。
2. 使用 xurl search 前，先确认用户意图。只有在任务需要实际帖子对象、已通过身份验证的账号上下文，或后续需要在 X 上执行写入操作时才使用它——当用户想要可供互动的帖子，而不仅仅是主题摘要时，它才是合适的入口。
3. 检查默认应用是否有凭据。 解析 auth status 输出。默认应用旁会标有 ▸。如果默认应用显示 oauth2: (none)，而另一个应用有有效的 oauth2 用户，则告诉用户运行 xurl auth default <that-app> 来修复。最常见的配置错误就是：用户添加了一个自定义名称的应用，却没有将其设为默认应用，因此 xurl 一直尝试使用空的 default 配置。
4. 如果完全缺少身份验证，则停止操作，并引导用户查看“One-Time User Setup”部分——不要尝试注册应用或自行传递密钥。
5. 先执行开销较小的读取操作（xurl whoami、xurl user @handle、xurl search ... -n 3）以确认连接正常。
6. 在执行任何写入操作（发布、回复、点赞、转发、私信、关注、拉黑、删除）前，确认目标帖子或用户，以及用户的意图。
7. 只有 xurl 命令输出（或原始 X API 响应）能证明 X 上发生了状态变更。绝不要根据其他来源（搜索结果、摘要或先前上下文）报告写入操作已完成。
8. 直接使用 JSON 输出——每个响应都已结构化。
9. 绝不要将 ~/.xurl 的内容粘贴到对话中。

---

故障排除

症状	原因	解决方法
OAuth 流程成功后出现身份验证错误	令牌保存到了 default 应用（没有 client-id/secret），而不是你命名的应用	运行 xurl auth oauth2 --app my-app，然后运行 xurl auth default my-app
OAuth 期间出现 unauthorized_client	X 控制面板中的应用类型设置为“Native App”	在 User Authentication Settings 中改为“Web app, automated app or bot”
OAuth 后立即在 /2/users/me 上出现 UsernameNotFound 或 403	X 无法可靠地从 /2/users/me 返回用户名	重新运行 xurl auth oauth2 --app my-app YOUR_USERNAME（xurl v1.1.0+），以显式传递账号名
每个请求都返回 401	令牌已过期或默认应用错误	检查 xurl auth status——确认 ▸ 指向具有 oauth2 令牌的应用
client-forbidden / client-not-enrolled	X 平台的启用问题	Dashboard → Apps → Manage → 将套餐改为“Pay-per-use” → Production environment
CreditsDepleted	X API 余额为 $0	在 Developer Console → Billing 中购买额度（最低 $5）
上传图片时出现 media processing failed	默认类别为 amplify_video	添加 --category tweet_image --media-type image/png
X 控制面板中出现两个“Client Secret”值	UI 错误——第一个实际上是 Client ID	在“Keys and tokens”页面确认；ID 以 MTpjaQ 结尾

---

备注

• 速率限制： X 会对每个端点实施速率限制。429 表示需要等待后重试。写入端点（发帖、回复、点赞、转发）的限制比读取端点更严格。
• 权限范围： OAuth 2.0 令牌使用宽泛的权限范围。特定操作出现 403 通常表示令牌缺少某个权限范围——请让用户重新运行 xurl auth oauth2。
• 令牌刷新： OAuth 2.0 令牌会自动刷新。无需操作。
• 多个应用： 每个应用的凭据/令牌相互隔离。使用 xurl auth default 或 --app 切换。
• 每个应用使用多个账号： 使用 -u / --username 选择，或使用 xurl auth default APP USER 设置默认账号。
• 令牌存储： ~/.xurl 是 YAML 文件。在 Docker 中，使用 Hermes 子进程的 HOME（官方镜像中为 /opt/data/home），以便将令牌存放在 /opt/data/home/.xurl 下。切勿读取此文件或将其发送到大模型上下文中。
• 费用： 使用 X API 达到有意义的用量通常需要付费。许多故障是套餐/权限问题，而不是代码问题。

---

致谢

• 上游 CLI：https://github.com/xdevplatform/xurl（X 开发者平台团队、Chris Park 等）
• 上游 Agent 技能：https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
• Hermes 改编：根据 Hermes 技能规范重新排版；安全防护措施原文保留。