Raw HTTP 命令（twitter-cli raw）

twitter-cli raw 子命令提供对任意 X API 端点的直接 HTTP 访问能力，主要用于调试目的。所有请求自动复用当前账号的认证体系（Bearer Token、CSRF Token、Cookies）、JA3/H2 指纹模拟和 ClientTransaction 签名注入。

命令总览

命令	必填参数	可选参数	输出格式
raw get	--url	--param KEY=VALUE	Envelope
raw post	--url	--param KEY=VALUE, --json STR, --form KEY=VALUE	Envelope

---

raw get

发送带认证的 GET 请求到指定 URL。

语法

twitter-cli [全局选项] raw get --url <URL> [--param KEY=VALUE ...]

参数

参数	必填	说明
--url <URL>	是	目标 URL，如 https://api.x.com/1.1/account/settings.json
--param KEY=VALUE	否	URL 查询参数，可多次指定，格式为 KEY=VALUE

示例

# 获取账号设置
twitter-cli --cookies-file cookies.txt raw get \
  --url "https://api.x.com/1.1/account/settings.json"

# 带查询参数的请求
twitter-cli --cookies-file cookies.txt raw get \
  --url "https://api.x.com/1.1/account/settings.json" \
  --param "include_nsfw_user_flag=true" \
  --param "include_mention_filter=true"

# 请求 strato 只读端点
twitter-cli --cookies-file cookies.txt raw get \
  --url "https://x.com/i/api/1.1/strato/column/User/44196397/search/searchSafetyReadonly"

输出示例

{
  "success": true,
  "data": {
    "status": 200,
    "body": "{\"protected\":false,\"screen_name\":\"elonmusk\",\"nsfw_user\":false,...}",
    "headers": {
      "content-type": "application/json;charset=utf-8",
      "x-rate-limit-remaining": "14",
      "x-rate-limit-reset": "1748000000"
    }
  },
  "meta": {
    "schema_version": "1.0",
    "timestamp": "2026-06-05T10:00:00Z"
  }
}

---

raw post

发送带认证的 POST 请求到指定 URL，支持 JSON body 和 form body 两种模式。

语法

twitter-cli [全局选项] raw post --url <URL> \
  [--param KEY=VALUE ...] \
  [--json <JSON_STR>] \
  [--form KEY=VALUE ...]

参数

参数	必填	说明
--url <URL>	是	目标 URL
--param KEY=VALUE	否	URL 查询参数（附加到 URL），可多次指定
--json <JSON_STR>	否（互斥）	JSON 请求体字符串，设置 Content-Type: application/json
--form KEY=VALUE	否（互斥）	表单字段，设置 Content-Type: application/x-www-form-urlencoded，可多次指定

互斥规则：--json 和 --form 不能同时使用。当两者同时指定时，--json 优先，--form 被忽略。

示例

JSON body 请求

# 修改搜索安全设置（JSON body）
twitter-cli --cookies-file cookies.txt raw post \
  --url "https://x.com/i/api/1.1/strato/column/User/44196397/search/searchSafety" \
  --json '{"optInFiltering":true,"optInBlocking":false}'

# GraphQL mutation（JSON body）
twitter-cli --cookies-file cookies.txt raw post \
  --url "https://x.com/i/api/graphql/oe9_UzzuQUeSU4qYVtMwQg/AudienceAndTaggingAllowVideoDownloadsMutation" \
  --json '{"variables":{"isAllowed":false},"queryId":"oe9_UzzuQUeSU4qYVtMwQg"}'

form body 请求

# 修改账号设置（form body）
twitter-cli --cookies-file cookies.txt raw post \
  --url "https://api.x.com/1.1/account/settings.json" \
  --form "nsfw_user=true" \
  --form "display_sensitive_media=true"

# 单字段修改
twitter-cli --cookies-file cookies.txt raw post \
  --url "https://api.x.com/1.1/account/settings.json" \
  --form "geo_enabled=false"

空 body POST（某些端点不需要请求体）

twitter-cli --cookies-file cookies.txt raw post \
  --url "https://api.x.com/1.1/account/logout.json"

输出示例

成功响应（JSON body POST）

{
  "success": true,
  "data": {
    "status": 200,
    "body": "{\"opt_in_filtering\":true,\"opt_in_blocking\":false}",
    "headers": {
      "content-type": "application/json;charset=utf-8"
    }
  },
  "meta": {
    "schema_version": "1.0",
    "timestamp": "2026-06-05T10:00:00Z"
  }
}

成功响应（form body POST）

{
  "success": true,
  "data": {
    "status": 200,
    "body": "{\"protected\":false,\"screen_name\":\"elonmusk\",\"nsfw_user\":true,...}",
    "headers": {
      "content-type": "application/json;charset=utf-8"
    }
  },
  "meta": {
    "schema_version": "1.0",
    "timestamp": "2026-06-05T10:00:00Z"
  }
}

---

常见错误

401 / 215 Bad Authentication data

{
  "success": false,
  "error": {
    "code": "AuthenticationFailed",
    "message": "Bad Authentication data",
    "http_status": 401
  }
}

原因：Cookies 已过期或格式不正确。更新 cookies 文件后重试。

404 + code 34

{
  "success": false,
  "error": {
    "code": "ApiError",
    "message": "Sorry, that page does not exist",
    "http_status": 404
  }
}

原因： 1. URL 错误（注意区分 api.x.com vs x.com/i/api/） 2. GraphQL queryId 已轮换失效 3. 端点已弃用

403 + 226 自动化检测

{
  "success": false,
  "error": {
    "code": "ApiError",
    "message": "This request looks like it might be automated",
    "http_status": 403
  }
}

原因：账号 cookies 失效，或网络环境触发了 Twitter 的反自动化检测。

JSON 解析错误（--json 参数）

# 错误：JSON 字符串中的引号未转义
twitter-cli raw post --url "..." --json "{"key":"value"}"

# 正确：使用单引号包裹 JSON 字符串
twitter-cli raw post --url "..." --json '{"key":"value"}'

# 或在 shell 中先构造再传入
JSON=$(jq -n '{"optInFiltering":true}')
twitter-cli raw post --url "..." --json "$JSON"

---

与其他命令的对比

场景	推荐命令
修改账号设置	twitter-cli settings update-account
修改搜索安全设置	twitter-cli settings set-search-safety
调试新端点 / 探索响应结构	twitter-cli raw get / raw post
验证 GraphQL queryId 是否有效	twitter-cli raw get --url "https://x.com/i/api/graphql/<queryId>/..."

生产脚本应使用对应模块的封装命令（如 settings、dm、user），以获得语义化的输出字段和更稳定的错误处理。raw 命令主要用于调试和探索阶段。