用 Claude Code + x-cli 操作 X/Twitter

讓你的 Claude Code 直接讀取、搜尋、發文、留言 X（Twitter），透過官方 API v2。

概覽

這份教學使用兩層架構：

X API v2（官方）— X/Twitter 提供的 REST API，所有操作的底層
x-cli（第三方開源）— INFATOSHI/x-cli，用 Python 包裝 X API v2，讓你在 terminal 一行指令完成操作

Auth 機制（OAuth 1.0a / Bearer Token）是 X 官方標準，Credentials 從 X Developer Portal 取得。x-cli 只是方便 Claude Code 呼叫的工具層。

Claude Code 可以直接在 terminal 呼叫 x-cli，完成搜尋、讀文、發文、回覆等操作。

核心能力：

功能	指令	說明
搜尋推文	`x-cli tweet search`	搜近 7 天的推文
讀取推文	`x-cli tweet get`	取得單篇推文完整內容
發文	`x-cli tweet post`	發推文（含投票）
回覆	`x-cli tweet reply`	回覆指定推文
引用轉推	`x-cli tweet quote`	引用推文並加上自己的評論
按讚 / 轉推	`x-cli like` / `x-cli retweet`	互動
查看用戶	`x-cli user get` / `user timeline`	查 profile 和近期推文
書籤	`x-cli me bookmarks`	管理自己的書籤

Step 1：申請 X API

前往 X Developer Portal
建立一個 App（或用既有的）
記錄以下 5 個值：
- API Key（Consumer Key）
- API Secret（Consumer Secret）
- Bearer Token
- Access Token
- Access Token Secret
在 App 設定的 User authentication settings 中，將權限設為 Read and write
如果 Access Token 是在開寫入權限之前產生的，必須 重新產生（Regenerate）

⚠️ 如果發文時遇到 403 oauth1-permissions，就是 Access Token 沒有寫入權限，重新產生即可。

Step 2：安裝 x-cli

# 方法 1：用 uv 安裝（推薦）
git clone https://github.com/INFATOSHI/x-cli.git
cd x-cli
uv tool install .

# 方法 2：pip 安裝
pip install git+https://github.com/INFATOSHI/x-cli.git

Dependencies：click、httpx、rich、python-dotenv（Python ≥ 3.11）

Step 3：設定 Credentials

建立設定檔 ~/.config/x-cli/.env：

mkdir -p ~/.config/x-cli
cat > ~/.config/x-cli/.env << 'EOF'
X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret
EOF

# 鎖定權限
chmod 600 ~/.config/x-cli/.env

驗證安裝成功：

x-cli user get elonmusk

應該會顯示 Elon Musk 的 profile 資訊。

Step 4：寫 Claude Code Skill

在你的 Claude Code 設定檔（CLAUDE.md 或 skill 檔案）中加入以下內容，讓 Claude Code 知道怎麼用：

## X/Twitter

CLI: `x-cli`（X API v2，已安裝）
Credentials: `~/.config/x-cli/.env`（權限 600）

**絕對不要在回覆或 log 中顯示 API key。**

### 搜尋推文
x-cli tweet search "關鍵字" --max 20

Search 支援 X 的完整查詢語法：
- `from:username` — 某人的推文
- `to:username` — 回覆某人的推文
- `#hashtag` — 含特定 hashtag
- `"exact phrase"` — 精確比對
- `has:media` — 含圖片/影片
- `is:reply` / `-is:retweet` — 過濾回覆/轉推
- `lang:en` / `lang:zh` — 指定語言
- 多條件用空格（AND）或 `OR` 組合

### 讀取推文
x-cli tweet get <tweet-id-or-url>

接受完整 URL（https://x.com/user/status/123）或純 ID（123）

### 發文
x-cli tweet post "你的推文內容"
x-cli tweet post --poll "選項1,選項2,選項3" "投票問題？"

### 回覆
x-cli tweet reply <tweet-id-or-url> "回覆內容"

### 引用轉推
x-cli tweet quote <tweet-id-or-url> "你的評論"

### 其他操作
x-cli like <tweet-id-or-url>          # 按讚
x-cli retweet <tweet-id-or-url>       # 轉推
x-cli tweet delete <tweet-id-or-url>  # 刪除自己的推文
x-cli tweet metrics <tweet-id-or-url> # 查看互動數據

### 用戶操作
x-cli user get <username>              # 查 profile
x-cli user timeline <username> --max 10 # 某人近期推文
x-cli user followers <username>         # 粉絲列表
x-cli user following <username>         # 追蹤列表

### 自己的帳號
x-cli me mentions --max 20    # 被提及的推文
x-cli me bookmarks            # 書籤
x-cli me bookmark <url>       # 加入書籤
x-cli me unbookmark <url>     # 移除書籤

### Output 格式
x-cli tweet get <id>              # 預設：彩色面板（human-readable）
x-cli -j tweet get <id>           # JSON（適合 pipe 給 jq）
x-cli -p tweet get <id>           # TSV（適合 pipe 給 awk）
x-cli -md tweet get <id>          # Markdown
x-cli -v tweet get <id>           # Verbose（含時間戳、metrics、metadata）

實戰範例

範例 1：搜尋某個話題的最新討論

# 搜「AI agent」相關的英文推文，排除轉推，最多 20 則
x-cli tweet search "AI agent lang:en -is:retweet" --max 20

# 搜尋特定用戶關於某主題的推文
x-cli tweet search "from:kaborofficial product strategy" --max 10

範例 2：讀取一篇推文並回覆

# 讀推文
x-cli tweet get https://x.com/someuser/status/1234567890

# 回覆
x-cli tweet reply https://x.com/someuser/status/1234567890 "Great insight! Thanks for sharing."

範例 3：發一篇推文

# 純文字
x-cli tweet post "Just shipped a new feature 🚀"

# 含投票
x-cli tweet post --poll "React,Vue,Svelte" --poll-duration 1440 "What's your frontend framework of choice?"

範例 4：讓 Claude Code 自動研究一個話題

你可以這樣跟 Claude Code 說：

幫我搜尋 X 上關於 "subscription fatigue" 的最新討論，整理出 top 5 的觀點

Claude Code 會執行：

x-cli -md tweet search "subscription fatigue -is:retweet lang:en" --max 30

然後整理搜尋結果，歸納出關鍵觀點。

Rate Limits 與注意事項

Search：Basic tier 每 15 分鐘 60 次
Post/Reply/Quote：每 15 分鐘 200 次（也有每天上限）
Like：每 15 分鐘 200 次
遇到 429 Rate Limited 會顯示 reset 時間，等一下就好
Search 只能搜 近 7 天 的推文（Basic tier 限制）
web_fetch 無法抓 x.com 內容，必須用 x-cli

Troubleshooting

錯誤	原因	解法
`403 oauth1-permissions`	Access Token 是 Read-only	去 Developer Portal 開 Read+Write，重新產生 Access Token
`401 Unauthorized`	Credentials 錯誤	檢查 `.env` 五個值是否正確，注意不要有多餘空格
`429 Rate Limited`	超過速率限制	等 error 顯示的 reset 時間後再試
`Missing env var`	找不到 credentials	確認 `~/.config/x-cli/.env` 存在且包含所有 5 個值
Search 搜不到結果	查詢語法問題或無相關推文	簡化 query 試試，確認近 7 天有相關內容

完整指令速查表

x-cli tweet post TEXT [--poll OPTIONS] [--poll-duration MINS]
x-cli tweet get ID_OR_URL
x-cli tweet delete ID_OR_URL
x-cli tweet reply ID_OR_URL TEXT
x-cli tweet quote ID_OR_URL TEXT
x-cli tweet search QUERY [--max N]
x-cli tweet metrics ID_OR_URL
x-cli user get USERNAME
x-cli user timeline USERNAME [--max N]
x-cli user followers USERNAME [--max N]
x-cli user following USERNAME [--max N]
x-cli me mentions [--max N]
x-cli me bookmarks [--max N]
x-cli me bookmark ID_OR_URL
x-cli me unbookmark ID_OR_URL
x-cli like ID_OR_URL
x-cli retweet ID_OR_URL

Global flags：-j（JSON）/ -p（TSV）/ -md（Markdown）/ -v（Verbose）

Generated by Rin · 2026-03-12