Xurl
通過 xurl（官方 X API CLI）與 X/Twitter 進行交互。用於發佈、回覆、引用、搜索、時間線、提及、點贊、轉發、書籤、關注、私信、媒體上傳以及原始 v2 端點訪問。
技能元數據
| 來源 | 捆綁（默認安裝） |
| 路徑 | skills/social-media/xurl |
| 版本 | 1.1.1 |
| 作者 | xdevplatform + openclaw + Hermes Agent |
| 許可證 | MIT |
| 平臺 | linux, macos |
| 標籤 | twitter, x, social-media, xurl, official-api |
參考：完整 SKILL.md
信息
以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。
xurl — 通過官方 CLI 訪問 X (Twitter) API
xurl 是 X 開發者平臺提供的用於 X API 的官方 CLI。它支持常見操作的快捷命令，並支持以類似 curl 的方式原始訪問任何 v2 端點。所有命令均將 JSON 輸出到 stdout。
使用此技能執行以下操作：
- 發佈、回覆、引用、刪除帖子
- 搜索帖子和讀取時間線/提及
- 點贊、轉發、加入書籤
- 關注、取消關注、屏蔽、靜音
- 直接消息
- 媒體上傳（圖片和視頻）
- 原始訪問任何 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 進行身份驗證 — 同樣在代理會話之外進行。令牌以 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 顯示沒有應用或令牌，則用戶需要手動完成身份驗證 — 請參閱下一節。
一次性用戶設置（用戶在代理之外運行這些命令）
這些步驟必須由用戶直接執行，而不是由代理執行，因為它們涉及粘貼密鑰。引導用戶查看此塊；不要為他們執行它。
-
在 https://developer.x.com/en/portal/dashboard 創建或打開一個應用
-
將重定向 URI 設置為
http://localhost:8080/callback -
複製應用的 Client ID 和 Client Secret
-
在本地註冊應用（用戶運行此命令）：
xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET -
身份驗證（指定
--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調用。 -
將應用設置為默認值，以便所有命令都使用它：
xurl auth default my-app -
驗證：
xurl auth status
xurl whoami
此後，代理可以使用下面的任何命令而無需進一步設置。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。
快速參考
| 操作 | 命令 |
|---|---|
| 發帖 | 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
# 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 | 在代理會話中禁止使用 — 會洩露認證頭信息 |
--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，因此你可以解析它們。
- 認證錯誤 → 讓用戶在代理會話之外重新運行
xurl auth oauth2。 - 需要調用者用戶 ID 的命令（如點贊、轉發、書籤、關注等）將通過
/2/users/me自動獲取它。那裡的認證失敗將表現為認證錯誤。
代理工作流
- 驗證先決條件：
xurl --help和xurl auth status。 - 檢查默認應用是否具有憑據。 解析
auth status輸出。默認應用標記為▸。如果默認應用顯示oauth2: (none)但另一個應用具有有效的 oauth2 用戶，請告訴用戶運行xurl auth default <that-app>來修復它。這是最常見的設置錯誤 — 用戶添加了具有自定義名稱的應用，但從未將其設置為默認值，因此 xurl 一直嘗試使用空的default配置文件。 - 如果完全缺少認證，請停止並引導用戶前往“一次性用戶設置”部分 — 不要嘗試自行註冊應用或傳遞密鑰。
- 從廉價的讀取操作開始（
xurl whoami、xurl user @handle、xurl search ... -n 3）以確認可達性。 - 在執行任何寫入操作（發帖、回覆、點贊、轉發、私信、關注、屏蔽、刪除）之前，確認目標帖子/用戶和用戶意圖。
- 直接使用 JSON 輸出 — 每個響應都已經結構化。
- 切勿將
~/.xurl的內容粘貼回對話中。
故障排除
| 症狀 | 原因 | 修復方法 |
|---|---|---|
| OAuth 流程成功後出現身份驗證錯誤 | Token 被保存到了 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 | Token 過期或默認應用錯誤 | 檢查 xurl auth status — 驗證 ▸ 是否指向具有 oauth2 token 的應用 |
client-forbidden / client-not-enrolled | X 平臺註冊問題 | 儀表板 → Apps → Manage → 移至“Pay-per-use”套餐 → Production 環境 |
CreditsDepleted | X API 餘額為 $0 | 在開發者控制檯 → Billing 中購買積分（最低 $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 表示需要等待並重試。寫入端點（發帖、回覆、點贊、轉發）的限制比讀取端點更嚴格。
- 作用域（Scopes）： OAuth 2.0 token 使用廣泛的作用域。特定操作上的 403 通常意味著 token 缺少相應的作用域 — 讓用戶重新運行
xurl auth oauth2。 - Token 刷新： OAuth 2.0 token 會自動刷新。無需任何操作。
- 多個應用： 每個應用都有隔離的憑據/token。使用
xurl auth default或--app進行切換。 - 每個應用的多個賬戶： 使用
-u / --username進行選擇，或使用xurl auth default APP USER設置默認賬戶。 - Token 存儲：
~/.xurl是 YAML 文件。切勿讀取此文件或將其發送給 LLM 上下文。 - 成本： X API 訪問通常針對有意義的用量收費。許多失敗是套餐/權限問題，而非代碼問題。
歸屬
- 上游 CLI：https://github.com/xdevplatform/xurl（X 開發者平臺團隊，Chris Park 等）
- 上游 agent skill：https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
- Hermes 適配：已根據 Hermes skill 約定重新格式化；安全護欄保留原文。