xurl — X (Twitter) API 官方命令列工具
xurl 是 X 開發者平台為 X API 提供的官方命令列工具。它支援常用操作的快捷命令，以及對任何 v2 端點的原始 curl 風格存取。所有指令都會以 JSON 格式輸出到標準輸出。
使用此技能進行：
- 發文、回覆、引用、刪除貼文
- 搜尋原始貼文 (包含可進行互動的實際貼文 JSON 與 ID)，以及閱讀時間軸/提及
- 按讚、轉發、書籤
- 跟隨、取消跟隨、封鎖、靜音
- 直接訊息
- 多媒體上傳 (圖片和影片)
- 對任何 X API v2 端點的原始存取
- 多應用程式 / 多帳戶工作流程
此技能取代了舊有的 xitter 技能 (該技能包裝了第三方的 Python 命令列工具)。xurl 由 X 開發者平台團隊維護，支援 OAuth 2.0 PKCE 自動重新整理，並涵蓋了更大的 API 表面。
秘密安全 (強制執行)
在代理/LLM 會話中操作時的關鍵規則：
- 切勿讀取、列印、解析、總結、上傳或傳送
~/.xurl到 LLM 上下文。 - 切勿要求使用者在聊天中貼入憑證/令牌。
- 使用者必須手動在自己的機器上填寫
~/.xurl的秘密資訊。在 Docker 中，這必須是 Hermes 工具子程序所能看到的~目錄；請參閱下方的 Docker 注意事項。 - 切勿在代理會話中建議或執行包含內嵌秘密的驗證命令。
- 切勿在代理會話中使用
--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 腳本 (安裝到 ~/.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 未顯示任何應用程式或令牌，使用者需要手動完成驗證 —— 請參閱下一節。
一次性使用者設定 (使用者在代理外執行)
這些步驟必須由使用者直接執行，而不是由代理執行，因為它們涉及貼入秘密。請引導使用者查看此區塊；不要為他們執行此操作。
-
在 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 返回
UsernameNotFound錯誤或在 OAuth 後的/2/users/me查詢中返回 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。
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
# 另一位使用者的圖譜
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 # 返回媒體 ID
xurl post "lol" --media-id MEDIA_ID
原始 API 存取
快捷命令涵蓋常見操作。對於其他操作，請使用原始 curl 風格模式存取任何 X API v2 端點：
# GET
xurl /2/users/me
# 使用 JSON 主體的 POST
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 強制在任何端點上進行串流。
輸出格式
所有命令都以 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 格式輸出到標準輸出，因此您可以解析它們。
- 驗證錯誤 → 讓使用者在代理會話外重新執行
xurl auth oauth2。 - 需要呼叫者使用者 ID 的命令 (例如按讚、轉發、書籤、跟隨等) 會透過
/2/users/me自動擷取它。那裡的驗證失敗會顯示為驗證錯誤。
代理工作流程
- 驗證先決條件：
xurl --help和xurl auth status。 - 在使用
xurl search之前，請檢查意圖。當任務需要實際的貼文物件、已驗證帳戶上下文或導致 X 寫入操作時，請使用它 —— 當使用者想要可以互動的貼文，而不僅僅是某個主題的摘要時，這是最合適的介面。 - 檢查預設應用程式是否有憑證。 解析
auth status的輸出。預設應用程式會以▸標記。如果預設應用程式顯示oauth2: (none)，但另一個應用程式有有效的 oauth2 使用者，請告訴使用者執行xurl auth default <that-app>來修復它。這是最常見的設定錯誤 —— 使用者新增了一個自訂名稱的應用程式，但從未將其設為預設，因此 xurl 會持續嘗試空的default設定檔。 - 如果完全缺少驗證資訊，請停止並引導使用者查看「一次性使用者設定」一節 —— 不要嘗試自己註冊應用程式或傳遞秘密。
- 從低成本讀取操作 (
xurl whoami、xurl user @handle、xurl search ... -n 3) 開始，以確認可達性。 - 在執行任何寫入操作 (發文、回覆、按讚、轉發、私訊、跟隨、封鎖、刪除) 之前，確認目標貼文/使用者以及使用者的意圖。
- 只有
xurl命令的輸出 (或原始 X API 回應) 才能證明狀態更改的 X 操作已發生。切勿根據任何其他來源（搜尋結果、摘要或先前的上下文）報告寫入操作已完成。 - 直接使用 JSON 輸出 —— 每個回應都已經是結構化的。
- 切勿將
~/.xurl的內容貼回對話中。
故障排除
| 症狀 | 原因 | 修復 |
|---|---|---|
| 成功的 OAuth 流程後出現驗證錯誤 | 令牌儲存到 default 應用程式 (沒有 client-id/secret) 而不是您的命名應用程式 | xurl auth oauth2 --app my-app 然後 xurl auth default my-app |
OAuth 期間出現 unauthorized_client | 應用程式類型在 X 儀表板中設定為「原生應用程式」 | 在使用者驗證設定中變更為「網頁應用程式、自動化應用程式或機器人」 |
OAuth 後立即出現 UsernameNotFound 或 /2/users/me 的 403 錯誤 | X 未能從 /2/users/me 可靠地返回使用者名稱 | 重新執行 xurl auth oauth2 --app my-app YOUR_USERNAME (xurl v1.1.0+) 以明確傳遞使用者名稱 |
| 每個請求都出現 401 錯誤 | 令牌已過期或預設應用程式錯誤 | 檢查 xurl auth status —— 確保預設應用程式有有效的 oauth2 使用者。如果沒有，請使用 xurl auth default <正確的應用程式> 來修正 |
xurl whoami 返回錯誤或空白 | 設定檔中缺少使用者名稱綁定 | 重新執行包含使用者名稱的 xurl auth oauth2 |