X/Twitter 社交媒体

通过 xurl CLI 操作 X/Twitter：发帖、搜索、私信、媒体

概述

xurl 是 X 开发者平台的官方 CLI，支持 X API。它支持常见操作的快捷命令和对任意 v2 端点的原始 curl 风格访问。所有命令向 stdout 返回 JSON。 用途：

• 发布、回复、引用、删除帖子
• 搜索帖子和阅读时间线/提及
• 点赞、转发、收藏
• 关注、取关、拉黑、屏蔽
• 私信
• 媒体上传（图片和视频）
• 原始访问任意 X API v2 端点
• 多应用/多账户工作流

本技能替代旧的 xitter 技能（封装第三方 Python CLI）。xurl 由 X 开发者平台团队维护，支持 OAuth 2.0 PKCE 自动刷新，覆盖更大的 API 范围。 ---

秘密安全（强制）

在代理/LLM 会话内操作时的关键规则：

• 绝不读取、打印、解析、总结、上传或发送 ~/.xurl 到 LLM 上下文
• 绝不要求用户将凭证/令牌粘贴到聊天中
• 用户必须在自己的机器上手动填写 ~/.xurl 中的秘密
• 绝不在代理会话中推荐或执行带内联秘密的认证命令
• 绝不在代理会话中使用 --verbose / -v——可能暴露认证头/令牌
• 要验证凭证存在，只用：xurl auth status

代理会话中禁止的标志（它们接受内联秘密）： --bearer-token、--consumer-key、--consumer-secret、--access-token、--token-secret、--client-id、--client-secret 应用凭证注册和凭证轮换必须由用户在代理会话外手动完成。 凭证注册后，用户用 xurl auth oauth2 认证——也在代理会话外。 令牌持久化到 ~/.xurl YAML。每个应用有隔离令牌。OAuth 2.0 令牌自动刷新。 ---

安装

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

# Shell 脚本（安装到 ~/.local/bin，无需 sudo，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 显示无应用或令牌，用户需要手动完成认证——见下一节。 ---

一次性用户设置（用户在代理外运行）

这些步骤必须由用户直接执行，不是代理，因为涉及粘贴秘密。 引导用户到此块；不要替他们执行。 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 流程） 6. 如果 X 返回 UsernameNotFound 错误或 403（在 OAuth 后的 /2/users/me 查询），显式传入你的用户名（xurl v1.1.0+）：

   xurl auth oauth2 --app my-app YOUR_USERNAME
   

这将令牌绑定到你的用户名并跳过有问题的 /2/users/me 调用。 7. 将应用设为默认，使所有命令使用它：

   xurl auth default my-app
   

8. 验证：

   xurl auth status
   xurl whoami
   

此后，代理可以使用下方任何命令，无需进一步设置。OAuth 2.0 令牌自动刷新。 > 常见陷阱：如果从 xurl auth oauth2 省略 --app my-app，OAuth 令牌保存到内置默认应用配置——它没有 client-id 或 client-secret。即使 OAuth 流程看起来成功，命令也会因认证错误失败。如果遇到，重新运行 xurl auth oauth2 --app my-app 和 xurl auth default my-app。 ---

快速参考

操作	命令
发帖	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 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

用户、时间线、提及

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

# 其他用户的图谱
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

媒体上传

# 自动检测类型
xurl media upload photo.jpg
xurl media upload video.mp4

# 显式类型/分类
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# 视频需要服务端处理——检查状态（或轮询）
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID

# 完整流程
xurl media upload meme.png  # 返回 media id
xurl post "lol" --media-id MEDIA_ID

---

原始 API 访问

快捷方式覆盖常见操作。其他情况，对任意 X API v2 端点使用原始 curl 风格模式：

# GET
xurl /2/users/me

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

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

# 自定义头
xurl -H "Content-Type: application/json" /2/some/endpoint

# 强制流式
xurl -s /2/tweets/search/stream

# 完整 URL 也行
xurl https://api.x.com/2/users/me

---

全局标志

标志	短	描述
------	----	----
--app	使用特定注册应用（覆盖默认）
--auth	强制认证类型：oauth1、oauth2 或 app
--username	-u	使用哪个 OAuth2 账户（如存在多个）
--verbose	-v	代理会话中禁止——泄露认证头
--trace	-t	添加 X-B3-Flags: 1 追踪头

---

流式

流式端点自动检测。已知包括：

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

用 -s 强制任意端点流式。 ---

输出格式

所有命令向 stdout 返回 JSON。结构镜像 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 应用，alice 用户
xurl --app staging /2/users/me  # 一次性使用 staging

---

错误处理

任何错误返回非零退出码。API 错误仍作为 JSON 打印到 stdout，可以解析。 认证错误 → 让用户在代理会话外重新运行 xurl auth oauth2。 需要调用者用户 ID 的命令（like、repost、bookmark、follow 等）会通过 /2/users/me 自动获取。那里的认证失败会表现为认证错误。 ---

代理工作流

1. 验证前置条件：xurl --help 和 xurl auth status。检查默认应用有凭证。 2. 解析 auth status 输出。默认应用标有 ▸。 3. 如果默认应用显示 oauth2: (none) 但另一个应用有有效 oauth2 用户，告诉用户运行 xurl auth default 修复。 这是最常见的设置错误——用户添加了自定义名称的应用但从未设为默认，所以 xurl 一直尝试空的默认配置。 4. 如果认证完全缺失，停止并引导用户到"一次性用户设置"节——不要尝试自己注册应用或传递秘密。 5. 从便宜的读取开始（xurl whoami、xurl user @handle、xurl search ... -n 3）确认可达性。 6. 在任何写操作（post、reply、like、repost、DM、follow、block、delete）前确认目标帖子/用户和用户意图。 7. 直接使用 JSON 输出——每个响应已经结构化。 8. 绝不将 ~/.xurl 内容粘贴回对话。 ---

常见问题

症状	原因	修复
------	------	------
OAuth 成功后认证错误	令牌保存到 default 应用（无 client-id/secret）而非你的命名应用	xurl auth oauth2 --app my-app 然后 xurl auth default my-app
OAuth 期间 unauthorized_client	X 控制台应用类型设为"Native App"	在用户认证设置中改为"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 平台注册问题	控制台 → 应用 → 管理 → 移到"Pay-per-use"包 → 生产环境
CreditsDepleted	X API 余额 $0	在开发者控制台 → 计费购买积分（最低 $5）
图片上传 media processing failed	默认分类是 amplify_video	添加 --category tweet_image --media-type image/png
X 控制台两个"Client Secret"值	UI bug——第一个实际是 Client ID	在"Keys and tokens"页确认；ID 以 MTpjaQ 结尾

---

注意事项

• 速率限制：X 强制每端点速率限制。429 表示等待并重试。写端点（post、reply、like、repost）比读端点限制更严。
• 作用域：OAuth 2.0 令牌使用宽泛作用域。特定操作 403 通常意味着令牌缺少作用域——让用户重新运行 xurl auth oauth2。
• 令牌刷新：OAuth 2.0 令牌自动刷新。无需操作。
• 多应用：每个应用有隔离凭证/令牌。用 xurl auth default 或 --app 切换。
• 每应用多账户：用 -u / --username 选择，或用 xurl auth default APP USER 设默认。
• 令牌存储：~/.xurl 是 YAML。绝不读取或发送此文件到 LLM 上下文。
• 成本：X API 访问通常需要付费才能有意义使用。许多失败是计划/权限问题，不是代码问题。

---

致谢

• 上游 CLI：https://github.com/xdevplatform/xurl（X 开发者平台团队，Chris Park 等）
• 上游代理技能：https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
• Hermes 适配：重格式化为 Hermes 技能约定；安全护栏逐字保留