Preserve valuable content from X into an Obsidian vault to build a searchable knowledge asset.
Positioning
X's native UI is not conducive to long-term review: threads are scattered across the timeline, Article layout is messy, links easily break, and search is weak. This skill archives high-quality long-form content from X into Obsidian in one click:
- Full thread unroll
- X Article fetches the full content
content.blocks - Complete metadata (author, metrics, direct media links, created_at)
- frontmatter topic double links, convenient for MOC aggregation
- Multilingual recognition (zh / en / ja / ko)
Prerequisites
-
Obsidian vault (any structure)
-
Python 3, pure stdlib (no third-party dependencies, archiving a single tweet)
-
Optional:
pip install telethon(only for MTProto sync) -
Set environment variables:
export OBSIDIAN_VAULT=~/Documents/MyVault # 可选:自定义归档子目录(默认 "Articles") export OBSIDIAN_ARTICLES="Articles" # 可选:段标题语言,默认 zh(中文),设 en 用英文标题 export X_ARCHIVE_LANG=zh
Core API: fxtwitter
Replace x.com in the X URL with api.fxtwitter.com, then directly GET back JSON. No X API key, no login, zero cost.
| Key field | Purpose |
|---|---|
tweet.text / tweet.raw_text.text |
Tweet body |
tweet.article.title |
X Article title |
tweet.article.content.blocks[] |
Article long-form blocks |
tweet.replying_to_status |
Previous tweet (thread backtracking) |
tweet.quote |
Quoted tweet |
tweet.media[] |
Media (direct image/video links) |
tweet.created_timestamp |
UNIX timestamp |
tweet.views / likes / bookmarks / retweets |
metrics |
Fallback: fxtwitter fails → cdn.syndication.twimg.com public endpoint.
Trigger words
| User says | Invoke |
|---|---|
| "Archive this X: URL" / "archive this: URL" | archive_x.py <URL> |
| "Archive and translate: URL" | archive_x.py <URL> + AI fills the "Chinese translation" section |
| "Organize this thread: URL" | Same as above, force thread backtracking |
| "Sync my Telegram Saved Messages" + provide JSON path | sync_telegram_export.py <path> --dry-run Check first, run for real after confirmation |
| "Sync Telegram with API" (credentials already available) | sync_telegram_saved.py |
Workflow (default archiving)
- Parse URL → handle + status_id
- Call script
archive_x.py <URL> - The script checks whether the vault has already archived it (by frontmatter
url:field)- Exists → output SKIP, exit
- Otherwise → fetch fxtwitter, write to vault
- AI then supplements: 1-sentence Chinese
## 摘要+ 1-3topicsdouble links +peopledouble links - The "My thoughts" section is always left blank for the user
Two Telegram sync paths
A. JSON export (recommended, zero risk)
Telegram Desktop
→ Settings → Advanced → Export Telegram data
→ 勾「私聊」+ 选 JSON 格式
→ 得到 result.json
python3 sync_telegram_export.py <result.json> --dry-run # 看清单
python3 sync_telegram_export.py <result.json> # 实跑
Automatically deduplicates by URL and automatically skips already-archived items. Export once a month for incremental syncing.
B. MTProto API (advanced, use with caution in mainland China)
Requires:
https://my.telegram.org/authapply for api_id / api_hash- Run
generate_telegram_session.pyto get session_string - Residential IP (users in mainland China must use HK/JP residential ranges; datacenter IPs will definitely trigger ERROR)
⚠️ Users in mainland China should prefer option A. Creating an app at my.telegram.org in mainland China almost inevitably triggers IP risk control; repeated attempts will trigger an account-level 24-72h freeze.
File naming
<YYYY-MM-DD>-X-<handle>-<title前 50 字>.md
Example:
2026-05-24-X-cyrilXBT-How-to-Organize-Your-Obsidian-Vault.md2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md
Multiple posts by the same author on the same day → append at the end -<status_id 后 6 位>。
Output frontmatter
---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <显示名>
handle: "@<handle>"
published_at: YYYY-MM-DD HH:mm
captured_at: YYYY-MM-DD HH:mm
language: zh / en / ja / ko
type: tweet / thread / article
topics: ["[[xxx]]", ...] # AI 填
people: ["[[xxx]]", ...] # AI 填
media: [...] / 0
content_complete: true
metrics:
views: N
likes: N
bookmarks: N
---
Boundaries and exceptions
| Scenario | Handling |
|---|---|
| fxtwitter returns 404 | Tweet deleted/private, suggest checking archive.org |
| fxtwitter 5xx | Retry once; if it fails, fall back to the syndication endpoint |
| URL is not x.com / twitter.com | Reject, suggest using Web Clipper |
| Tweet text is empty and there is no article and no media | Warning: "Pure retweet/pure reply, may have no standalone content" |
| Duplicate filenames for the same author on the same day | Append at the end -<status_id 后 6 位> |
| Video media | frontmatter media[] Record the mp4 direct link, do not embed |
Command-line reference
# 归档单条
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force # 覆盖已归档
python3 archive_x.py <URL> --vault /path/to/vault # 覆盖环境变量
# Telegram JSON 导出同步
python3 sync_telegram_export.py <result.json>
python3 sync_telegram_export.py <result.json> --dry-run
python3 sync_telegram_export.py <result.json> --since 2026-06-01
python3 sync_telegram_export.py <result.json> --limit 30
# MTProto 同步(需先 setup)
python3 generate_telegram_session.py # 一次性
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all