Chuyển tới nội dung chính

{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Xurl

X/Twitter qua xurl CLI: đăng, tìm kiếm, DM, media, v2 API.

Siêu dữ liệu kỹ năng​

NguồnĐi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/social-media/xurl ` | | Phiên bản |

1.1.1 ` | | Tác giả | xdevplatform + OpenClaw + Đại lý Hermes | | Giấy phép | MIT | | Nền tảng | Linux, macOS | | Thẻ |

twitter

, `x

, `social-media

, `xurl

, official-API |

Tham khảo: đầy đủ SKILL.md​

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

xurl — API X (Twitter) thông qua CLI chính thức``xurl

` là CLI chính thức của nền tảng nhà phát triển X dành cho API X. Nó hỗ trợ các lệnh tắt cho các hành động phổ biến VÀ quyền truy cập kiểu cuộn tròn thô vào bất kỳ điểm cuối v2 nào. Tất cả các lệnh trả về JSON về thiết bị xuất chuẩn.

Sử dụng kỹ năng này để:

  • đăng, trả lời, trích dẫn, xóa bài viết
  • tìm kiếm bài viết và đọc các mốc thời gian/đề cập
  • thích, đăng lại, đánh dấu
  • theo dõi, hủy theo dõi, chặn, tắt tiếng
  • tin nhắn trực tiếp
  • tải lên phương tiện truyền thông (hình ảnh và video)
  • quyền truy cập thô vào bất kỳ điểm cuối X API v2 nào
  • quy trình làm việc đa ứng dụng / đa tài khoản

Kỹ năng này thay thế kỹ năng xitter cũ hơn (bao bọc Python CLI của bên thứ ba). xurl được nhóm nền tảng nhà phát triển X duy trì, hỗ trợ OAuth 2.0 PKCE với tính năng tự động làm mới và bao phủ bề mặt API lớn hơn đáng kể.

An toàn bí mật (BẮT BUỘC)​

Các quy tắc quan trọng khi hoạt động bên trong phiên đại lý/LLM:

  • Không bao giờ đọc, in, phân tích cú pháp, tóm tắt, tải lên hoặc gửi

~/.xurl ` tới ngữ cảnh LLM.

  • Không bao giờ yêu cầu người dùng dán thông tin đăng nhập/mã thông báo vào cuộc trò chuyện.
  • Người dùng phải điền thủ công các bí mật vào

~/.xurl ` trên máy của mình.

  • Không bao giờ đề xuất hoặc thực thi các lệnh xác thực có bí mật nội tuyến trong phiên tác nhân.
  • Không bao giờ sử dụng

--verbose ` /

-v ` trong các phiên tác nhân — nó có thể hiển thị các tiêu đề/mã thông báo xác thực.

  • Để xác minh thông tin xác thực tồn tại, chỉ sử dụng: `xurl auth status

.

Cờ bị cấm trong lệnh tác nhân (chúng chấp nhận bí mật nội tuyến):

--bearer-token

,

--consumer-key

,

--consumer-secret

,

--access-token

,

--token-secret

,

--CLIent-id

,

--CLIent-secret ``Việc đăng ký thông tin xác thực ứng dụng và xoay vòng thông tin xác thực phải được người dùng thực hiện theo cách thủ công, bên ngoài phiên đại lý. Sau khi thông tin xác thực được đăng ký, người dùng sẽ xác thực bằng xurl auth OAuth2 — cũng nằm ngoài phiên tác nhân. Mã thông báo vẫn tồn tại ở

~/.xurl ` trong YAML. Mỗi ứng dụng có mã thông báo riêng biệt. Tự động làm mới mã thông báo OAuth 2.0.

Cài đặt​

Chọn MỘT phương pháp. Trên Linux, tập lệnh shell hoặc go install là dễ nhất.


# 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

`
``Xác minh:

``` bash
xurl --help
xurl auth status

`
``Nếu 
`xurl
` được cài đặt nhưng 
`auth status
` không hiển thị ứng dụng hoặc mã thông báo nào, thì người dùng cần hoàn tất xác thực theo cách thủ công — xem phần tiếp theo.

---

## Thiết lập người dùng một lần (người dùng chạy những thứ này bên ngoài tác nhân)

Các bước này phải được người dùng trực tiếp thực hiện, KHÔNG phải bởi tác nhân, vì chúng liên quan đến việc dán các bí mật. Hướng người dùng đến khối này; không thực hiện nó cho họ.
1. Tạo hoặc mở ứng dụng tại https://developer.x.com/en/portal/dashboard

2. Đặt URI chuyển hướng thành 
`http://localhost:8080/callback

3. Sao chép ID khách hàng và Bí mật khách hàng của ứng dụng
4. Đăng ký ứng dụng cục bộ (người dùng chạy cái này):

``` bash
   xurl auth apps add my-app --CLIent-id YOUR_CLIENT_ID --CLIent-secret YOUR_CLIENT_SECRET

`

5. Xác thực (chỉ định 

--app
` để liên kết mã thông báo với ứng dụng của bạn):

``` bash
   xurl auth OAuth2 --app my-app

`
   (Thao tác này sẽ mở trình duyệt cho luồng PKCE OAuth 2.0.)

Nếu X trả về lỗi 
`UsernameNotFound
` hoặc 403 khi tra cứu 

/2/users/me
` sau OAuth, hãy chuyển mã điều khiển của bạn một cách rõ ràng (xurl v1.1.0+):

`bash
   xurl auth OAuth2 --app my-app YOUR_USERNAME

`
   Điều này liên kết mã thông báo với tay cầm của bạn và bỏ qua cuộc gọi 

/2/users/me
` bị hỏng.

6. Đặt ứng dụng làm mặc định để tất cả các lệnh đều sử dụng nó:

``` bash
   xurl auth default my-app

`

7. Xác minh:

``` bash
   xurl auth status
   xurl whoami

``Sau đó, tác nhân có thể sử dụng bất kỳ lệnh nào bên dưới mà không cần thiết lập thêm. Tự động làm mới mã thông báo OAuth 2.0.> **Cạm bẫy thường gặp:** Nếu bạn bỏ qua 

`
--app my-app
` khỏi 
`xurl auth OAuth2

, mã thông báo OAuth sẽ được lưu vào hồ sơ ứng dụng 
`default
` tích hợp sẵn — không có id khách hàng hoặc bí mật khách hàng. Các lệnh sẽ không thành công do lỗi xác thực ngay cả khi luồng OAuth có vẻ thành công. Nếu bạn gặp phải điều này, hãy chạy lại 
`xurl auth OAuth2 --app my-app
` và 
`xurl auth default my-app

.

---

## Tham khảo nhanh

| Hành động | Lệnh |
| --- | --- |
| Đăng |

xurl post "Hello world!"
` |
| Trả lời |

xurl reply POST_ID "Nice post!"
` |
| Trích dẫn |

xurl quote POST_ID "My take"
` |
| Xóa một bài viết |

xurl delete POST_ID
` |
| Đọc một bài viết |

xurl read POST_ID
` |
| Tìm kiếm bài viết |

xurl search "QUERY" -n 10
` |
| Tôi là ai |

xurl whoami
` |
| Tra cứu người dùng |

xurl user @handle
` |
| Trang chủ dòng thời gian |

xurl timeline -n 20
` |
| Đề cập |

xurl mentions -n 10
` |
| Thích / Không giống |

xurl like POST_ID
` / 
`xurl unlike POST_ID
` |
| Đăng lại / Hoàn tác |

xurl repost POST_ID
` / 
`xurl unrepost POST_ID
` |
| Đánh dấu / Xóa |

xurl bookmark POST_ID
` / 
`xurl unbookmark POST_ID
` |
| Liệt kê dấu trang / lượt thích |

xurl bookmarks -n 10
` / 
`xurl likes -n 10
` |
| Theo dõi / Hủy theo dõi |

xurl follow @handle
` / 
`xurl unfollow @handle
` |
| Đang theo dõi / Người theo dõi |

xurl following -n 20
` / 
`xurl followers -n 20
` |
| Chặn / Bỏ chặn |

xurl block @handle
` / 
`xurl unblock @handle
` |
| Tắt tiếng / Bật tiếng |

xurl mute @handle
` / 
`xurl unmute @handle
` |
| Gửi tin nhắn trực tiếp |

xurl dm @handle "message"
` |
| Liệt kê DM |

xurl dms -n 10
` |
| Tải lên phương tiện |

xurl media upload path/to/file.mp4
` |
| Trạng thái phương tiện |

xurl media status MEDIA_ID
` |
| Liệt kê ứng dụng |

xurl auth apps list
` |
| Xóa ứng dụng |

xurl auth apps remove NAME
` |
| Đặt ứng dụng mặc định |

xurl auth default APP_NAME [USERNAME]
` |
| Ứng dụng theo yêu cầu |

xurl --app NAME /2/users/me
` |
| Trạng thái xác thực |

xurl auth status
` |

Ghi chú:
- 
`POST_ID
` cũng chấp nhận các URL đầy đủ (ví dụ: 
`https://x.com/user/status/1234567890

) — xurl trích xuất ID.
- Tên người dùng hoạt động có hoặc không có 

@
` hàng đầu.

---

## Chi tiết lệnh

### Đăng bài

``` bash
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

`

### Đọc & Tìm kiếm

`bash
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

`

### Người dùng, Dòng thời gian, Lượt đề cập

`bash
xurl whoami
xurl user elonmusk
xurl user @XDevelopers`xurl timeline -n 25
xurl mentions -n 20

`

### Tương tác

`bash
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

`

### Đồ thị xã hội

`bash
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

`

### Tin nhắn trực tiếp

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

`

### Tải lên phương tiện

`bash

# 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

`

---

## Truy cập API thô

Các phím tắt bao gồm các hoạt động phổ biến. Đối với bất kỳ điều gì khác, hãy sử dụng chế độ kiểu cuộn tròn thô đối với bất kỳ điểm cuối X API v2 nào:

``` bash

# 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

`

---

## Cờ toàn cầu

| Cờ | Ngắn | Mô tả |
| --- | --- | --- |
| 

--app
` | | Sử dụng một ứng dụng đã đăng ký cụ thể (ghi đè mặc định) |
| 

--auth
` | | Buộc loại xác thực: 
`OAuth1

, 
`OAuth2
` hoặc 
`app
` |
| 

--username
` | 

-u
` | Nên sử dụng tài khoản OAuth2 nào (nếu có nhiều tài khoản) |
| 

--verbose
` | 

-v
` | **Bị cấm trong phiên đại lý** — rò rỉ tiêu đề xác thực |
| 

--trace
` | 

-t
` | Thêm tiêu đề theo dõi 
`X-B3-Flags: 1
` |

---

## Đang phát trực tuyến

Điểm cuối phát trực tuyến được tự động phát hiện. Những cái được biết đến bao gồm:
- 

/2/tweets/search/stream

- 

/2/tweets/sample/stream

- 

/2/tweets/sample10/stream
``Buộc phát trực tuyến trên bất kỳ điểm cuối nào bằng 

-s

.

---

## Định dạng đầu ra

Tất cả các lệnh trả về JSON về thiết bị xuất chuẩn. Gương cấu trúc X API v2:

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

`
``Lỗi cũng là JSON:

`JSON
{ "errors": [ { "message": "Not authoriZed", "code": 403 } ] }

`

---

## Quy trình làm việc chung

### Đăng kèm hình ảnh

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

`

### Trả lời cuộc trò chuyện

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

`

### Tìm kiếm và tương tác

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

`

### Kiểm tra hoạt động của bạn

`
`bash
xurl whoami
xurl mentions -n 20
xurl timeline -n 20

`

### Nhiều ứng dụng (thông tin xác thực được cấu hình sẵn theo cách thủ công)

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

`

---

## Xử lý lỗi
- Mã thoát khác 0 đối với bất kỳ lỗi nào.

- Lỗi API vẫn được in dưới dạng JSON ra stdout nên bạn có thể phân tích cú pháp.
- Lỗi xác thực → yêu cầu người dùng chạy lại 
`xurl auth OAuth2
` ngoài phiên đại lý.
- Các lệnh cần ID người gọi của người gọi (như, đăng lại, đánh dấu, theo dõi, v.v.) sẽ tự động tìm nạp thông qua 

/2/users/me

. Lỗi xác thực ở đó xuất hiện dưới dạng lỗi xác thực.

---

## Quy trình làm việc của đại lý1. Xác minh các điều kiện tiên quyết: 
`xurl --help
` và 
`xurl auth status

.
2. **Kiểm tra thông tin xác thực của ứng dụng mặc định.** Phân tích đầu ra 
`auth status

. Ứng dụng mặc định được đánh dấu bằng 

▸

. Nếu ứng dụng mặc định hiển thị 
`OAuth2: (none)
` nhưng ứng dụng khác có người dùng OAuth2 hợp lệ, hãy yêu cầu người dùng chạy 
`xurl auth default <that-app
` để khắc phục. Đây là lỗi thiết lập phổ biến nhất — người dùng đã thêm một ứng dụng có tên tùy chỉnh nhưng không bao giờ đặt nó làm mặc định, vì vậy xurl tiếp tục thử cấu hình 
`default
` trống.
3. Nếu thiếu hoàn toàn xác thực, hãy dừng và hướng người dùng đến phần "Thiết lập người dùng một lần" — KHÔNG cố gắng đăng ký ứng dụng hoặc tự mình chuyển bí mật.
4. Bắt đầu bằng cách đọc giá rẻ (
`xurl whoami

, 
`xurl user @handle

, 
`xurl search ... -n 3

) để xác nhận khả năng tiếp cận.
5. Xác nhận bài đăng/người dùng mục tiêu và ý định của người dùng trước bất kỳ hành động viết nào (đăng, trả lời, thích, đăng lại, DM, theo dõi, chặn, xóa).
6. Sử dụng trực tiếp đầu ra JSON - mọi phản hồi đều đã được cấu trúc sẵn.
7. Không bao giờ dán lại nội dung 

~/.xurl
` vào cuộc trò chuyện.

---

## Khắc phục sự cố

| Triệu chứng | Nguyên nhân | Sửa chữa |
| --- | --- | --- |
| Lỗi xác thực sau luồng OAuth thành công | Mã thông báo được lưu vào ứng dụng 
`default
` (không có id khách hàng/bí mật) thay vì ứng dụng được đặt tên của bạn | 
`xurl auth OAuth2 --app my-app
` rồi 
`xurl auth default my-app
` |
| 
`unauthoriZed_CLIent
` trong OAuth | Loại ứng dụng được đặt thành "Ứng dụng gốc" trong trang tổng quan X | Thay đổi thành "Ứng dụng web, ứng dụng tự động hoặc bot" trong Cài đặt xác thực người dùng |
| 
`UsernameNotFound
` hoặc 403 trên 

/2/users/me
` ngay sau OAuth | X không trả lại tên người dùng một cách đáng tin cậy từ 

/2/users/me
` | Chạy lại 
`xurl auth OAuth2 --app my-app YOUR_USERNAME
` (xurl v1.1.0+) để vượt qua phần xử lý một cách rõ ràng |
| 401 theo mọi yêu cầu | Mã thông báo đã hết hạn hoặc ứng dụng mặc định sai | Kiểm tra 
`xurl auth status

 - xác minh 

▸
` trỏ đến ứng dụng có mã thông báo OAuth2 |
| 
`CLIent-forbidden
` / 
`CLIent-not-enrolled
` | Vấn đề đăng ký nền tảng X | Bảng điều khiển → Ứng dụng → Quản lý → Chuyển sang gói “Trả tiền cho mỗi lần sử dụng” → Môi trường sản xuất |
| 
`CreditsDepleted
` | Số dư $0 trên API X | Mua tín dụng (tối thiểu $5) trong Bảng điều khiển dành cho nhà phát triển → Thanh toán |
| 
`media processing failed
` khi tải lên hình ảnh | Danh mục mặc định là 
`amplify_video
` | Thêm 

--category tweet_image --media-type image/png
` |
| Hai giá trị "Bí mật khách hàng" trong bảng điều khiển X | Lỗi giao diện người dùng - đầu tiên thực sự là ID khách hàng | Xác nhận trên trang "Khóa và mã thông báo"; ID kết thúc bằng 
`MTpjaQ
` |

---

## Ghi chú
- **Giới hạn tốc độ:** X thực thi giới hạn tốc độ trên mỗi điểm cuối. 429 có nghĩa là chờ và thử lại. Điểm cuối viết (đăng, trả lời, thích, đăng lại) có giới hạn chặt chẽ hơn so với lượt đọc.
- **Phạm vi:** Mã thông báo OAuth 2.0 sử dụng phạm vi rộng. Lỗi 403 trên một hành động cụ thể thường có nghĩa là mã thông báo thiếu phạm vi — yêu cầu người dùng chạy lại 
`xurl auth OAuth2

.
- **Làm mới mã thông báo:** Tự động làm mới mã thông báo OAuth 2.0. Không có gì để làm.
- **Nhiều ứng dụng:** Mỗi ứng dụng có thông tin xác thực/mã thông báo riêng biệt. Chuyển đổi bằng 
`xurl auth default
` hoặc 

--app

.
- **Nhiều tài khoản cho mỗi ứng dụng:** Chọn bằng 

-u / --username
` hoặc đặt mặc định bằng 
`xurl auth default APP USER

.
- **Lưu trữ mã thông báo:** 

~/.xurl
` là YAML. Không bao giờ đọc hoặc gửi tệp này tới ngữ cảnh LLM.
- **Chi phí:** Quyền truy cập API X thường được trả phí để sử dụng có ý nghĩa. Nhiều lỗi là do vấn đề về kế hoạch/quyền, không phải vấn đề về mã.

---

## Ghi công
- CLI ngược dòng: https://GitHub.com/xdevplatform/xurl (Nhóm nền tảng nhà phát triển X, Chris Park và cộng sự)
- Kỹ năng đại lý ngược dòng: https://GitHub.com/OpenClaw/OpenClaw/blob/main/skills/xurl/SKILL.md
- Chuyển thể Hermes: được định dạng lại cho các quy ước kỹ năng của Hermes; lan can an toàn được bảo tồn nguyên văn.