Xurl

X/Twitter через xurl CLI: публикация, поиск, ЛС, медиа, API v2.

Метаданные навыка


Источник	Встроенный (устанавливается по умолчанию)
Путь	`skills/social-media/xurl`
Версия	`1.1.1`
Автор	xdevplatform + openclaw + VibeOS
Лицензия	MIT
Платформы	linux, macos
Теги	`twitter`, `x`, `social-media`, `xurl`, `official-api`

Справочник: полный SKILL.md

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Агент видит эти инструкции, когда навык активен.

xurl — X (Twitter) API через официальный CLI

xurl — это официальный CLI платформы X Developer для X API. Он поддерживает сокращённые команды для типовых действий И сырой curl-доступ к любым конечным точкам v2. Все команды возвращают JSON в stdout.

Используйте этот навык для:

публикации, ответов, цитирования, удаления постов
поиска постов и чтения ленты/упоминаний
лайков, репостов, закладок
подписки, отписки, блокировки, заглушения
личных сообщений
загрузки медиа (изображения и видео)
сырого доступа к любой конечной точке X API v2
работы с несколькими приложениями/аккаунтами

Этот навык заменяет более старый навык xitter (который оборачивал сторонний Python CLI). xurl поддерживается командой платформы X Developer, поддерживает OAuth 2.0 PKCE с автообновлением и покрывает существенно большую поверхность API.

Безопасность секретов (ОБЯЗАТЕЛЬНО)

Критические правила при работе внутри сессии агента/LLM:

Никогда не читайте, не выводите, не парсите, не обобщайте, не загружайте и не отправляйте ~/.xurl в контекст LLM.
Никогда не просите пользователя вставлять учётные данные/токены в чат.
Пользователь должен вручную заполнить ~/.xurl секретами на своей машине. В Docker это должен быть ~, видимый подпроцессами инструментов VibeOS; см. примечание о Docker ниже.
Никогда не рекомендуйте и не выполняйте команды аутентификации с встроенными секретами в сессиях агента.
Никогда не используйте --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 проще всего использовать скрипт оболочки или go install.

# Скрипт оболочки (устанавливается в ~/.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 или 403 при поиске /2/users/me после OAuth, явно передайте свой handle (xurl v1.1.0+):
```
xurl auth oauth2 --app my-app YOUR_USERNAME
```
Это привяжет токен к вашему handle и пропустит сломанный вызов /2/users/me.
Установите приложение по умолчанию, чтобы все команды использовали его:
```
xurl auth default my-app
```
Проверка:
```
xurl auth status
xurl whoami
```

После этого агент может использовать любую команду ниже без дополнительной настройки. Токены OAuth 2.0 обновляются автоматически.

Частая ошибка: Если вы опустите --app my-app в xurl auth oauth2, токен OAuth будет сохранён во встроенном профиле приложения default — у которого нет client-id или client-secret. Команды будут завершаться ошибками аутентификации, даже если поток OAuth, казалось бы, прошёл успешно. Если вы столкнулись с этим, повторно выполните xurl auth oauth2 --app my-app и xurl auth default my-app.

Проблема HOME в Docker: В официальной структуре VibeOS Docker /opt/data — это VIBEOS_HOME, но подпроцессы инструментов VibeOS используют /opt/data/home как HOME. Это означает, что ~/.xurl разрешается в /opt/data/home/.xurl для команд xurl, запускаемых VibeOS, а не в /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 не показывает приложений или токенов, вызовы инструментов VibeOS не увидят учётные данные.

Краткий справочник

Действие	Команда
Опубликовать	`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

Для X Articles используйте сырой режим API вместо сокращённой команды read. xurl read ожидает ID поста или URL поста; не ставьте read перед конечной точкой /2/tweets/.... Запросите поле твита article и извлеките data.article.plain_text из JSON-ответа:

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

# 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.

Формат вывода

Все команды возвращают 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, пользователь alice
xurl --app staging /2/users/me             # разовый запрос к 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	Токен сохранён в приложении `default` (нет client-id/secret) вместо вашего именованного приложения	`xurl auth oauth2 --app my-app` затем `xurl auth default my-app`
`unauthorized_client` во время OAuth	Тип приложения установлен как «Native App» в панели управления X	Измените на «Web app, automated app or bot» в настройках аутентификации пользователя
`UsernameNotFound` или 403 на `/2/users/me` сразу после OAuth	X ненадёжно возвращает имя пользователя из `/2/users/me`	Повторно выполните `xurl auth oauth2 --app my-app YOUR_USERNAME` (xurl v1.1.0+), чтобы явно передать handle
401 на каждом запросе	Срок действия токена истёк или неверное приложение по умолчанию	Проверьте `xurl auth status` — убедитесь, что `▸` указывает на приложение с токенами oauth2
`client-forbidden` / `client-not-enrolled`	Проблема регистрации на платформе X	Панель управления → Приложения → Управление → Переместить в пакет «Pay-per-use» → Производственная среда
`CreditsDepleted`	Нулевой баланс на X API	Купите кредиты (мин. $5) в консоли разработчика → Биллинг
`media processing failed` при загрузке изображения	Категория по умолчанию — `amplify_video`	Добавьте `--category tweet_image --media-type image/png`
Два значения «Client Secret» в панели управления X	Ошибка интерфейса — первое на самом деле Client ID	Подтвердите на странице «Keys and tokens»; ID заканчивается на `MTpjaQ`

Примечания

Лимиты запросов: X применяет лимиты запросов для каждой конечной точки. 429 означает «подождите и повторите попытку». Конечные точки записи (публикация, ответ, лайк, репост) имеют более строгие лимиты, чем чтение.
Области (Scopes): Токены OAuth 2.0 используют широкие области. 403 при конкретном действии обычно означает, что токену не хватает области — попросите пользователя повторно выполнить xurl auth oauth2.
Обновление токена: Токены OAuth 2.0 обновляются автоматически. Ничего делать не нужно.
Несколько приложений: Каждое приложение имеет изолированные учётные данные/токены. Переключайтесь с помощью xurl auth default или --app.
Несколько аккаунтов на приложение: Выбирайте с помощью -u / --username или установите значение по умолчанию с помощью xurl auth default APP USER.
Хранение токенов: ~/.xurl — это YAML. В Docker используйте HOME подпроцесса VibeOS (/opt/data/home в официальном образе), чтобы токены сохранялись в /opt/data/home/.xurl. Никогда не читайте и не отправляйте этот файл в контекст LLM.
Стоимость: Доступ к X API обычно платный для значимого использования. Многие сбои связаны с проблемами тарифа/разрешений, а не с проблемами кода.

Атрибуция

Исходный CLI: https://github.com/xdevplatform/xurl (команда платформы X Developer, Chris Park и др.)
Исходный навык агента: https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
Адаптация для VibeOS: переформатировано в соответствии с соглашениями о навыках VibeOS; защитные ограждения сохранены дословно.

Метаданные навыка​

Справочник: полный SKILL.md​

xurl — X (Twitter) API через официальный CLI

Безопасность секретов (ОБЯЗАТЕЛЬНО)​

Установка​

Одноразовая настройка пользователя (пользователь запускает это вне агента)​

Краткий справочник​

Детали команд​

Публикация​

Чтение и поиск​

Пользователи, лента, упоминания​

Вовлечённость​

Социальный граф​

Личные сообщения​

Загрузка медиа​

Сырой доступ к API​

Глобальные флаги​

Потоковая передача​

Формат вывода​

Типовые рабочие процессы​

Публикация с изображением​

Ответ в разговоре​

Поиск и вовлечение​

Проверка своей активности​

Несколько приложений (учётные данные предварительно настроены вручную)​

Обработка ошибок​

Рабочий процесс агента​

Устранение неполадок​

Примечания​

Атрибуция​