Settings 模块（账号设置）¶

settings 模块提供账号设置的查询和修改功能。v2.0.0 重构为端点级命令，8 个 action 与 4 个 Twitter API 端点一一对应。

目录¶

命令总览
get-account — 查询完整账号设置
update-account — 批量更新账号设置
get-search-safety — 查询搜索安全设置
set-search-safety — 设置搜索安全
get-audience — 查询受众设置
set-protect-videos — 设置视频下载保护
get-explore — 查询 Explore 设置
set-explore — 更新 Explore 设置
常见错误

命令总览¶

命令	参数	功能
`settings get-account`	—	查询完整账号设置（18 个字段）
`settings update-account`	多个可选 flag	批量更新账号设置（一次 POST，只传要改的字段）
`settings get-search-safety`	—	查询搜索安全设置（filtering + blocking 两字段）
`settings set-search-safety`	`--filtering BOOL --blocking BOOL`	同时设置两项搜索安全参数
`settings get-audience`	—	查询受众设置（视频保护）
`settings set-protect-videos`	`--enabled BOOL`	开启/关闭视频下载保护（GraphQL）
`settings get-explore`	—	查询 Explore 个性化设置
`settings set-explore`	`[--personalized-trends BOOL] [--current-location BOOL]`	更新 Explore 设置

所有命令均返回 Envelope JSON 格式（success、data、error、meta 四个顶层字段）。

get-account — 查询完整账号设置¶

语法¶

twitter-cli [全局 flags] settings get-account

参数¶

无需额外参数。

成功示例¶

twitter-cli --cookies-file cookies.txt settings get-account

输出（格式化后）：

{
  "success": true,
  "data": {
    "screen_name": "myaccount",
    "language": "zh-cn",
    "country_code": "CN",
    "protected": false,
    "geo_enabled": false,
    "nsfw_user": false,
    "nsfw_admin": false,
    "display_sensitive_media": false,
    "allow_dms_from": "following",
    "allow_dm_groups_from": "following",
    "allow_media_tagging": "all",
    "discoverable_by_email": true,
    "discoverable_by_mobile_phone": false,
    "dm_receipt_setting": "all_enabled",
    "dm_quality_filter": "enabled",
    "mention_filter": "unfiltered",
    "allow_ads_personalization": true,
    "allow_sharing_data_for_third_party_personalization": true
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "get-account",
    "elapsed_ms": 312,
    "timestamp": "2026-06-04T10:00:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

data 字段说明¶

字段	类型	说明
`screen_name`	string	账号用户名（不含 `@`）
`language`	string	账号界面语言（如 `"zh-cn"`、`"en"`）
`country_code`	string	账号所在国家代码（如 `"CN"`、`"US"`）
`protected`	bool	帖子是否受保护（仅粉丝可见）
`geo_enabled`	bool	是否启用地理位置功能
`nsfw_user`	bool	账号是否被标记为 NSFW
`nsfw_admin`	bool	账号是否被管理员标记为 NSFW
`display_sensitive_media`	bool	是否展示他人发布的敏感媒体
`allow_dms_from`	string	DM 接收来源（`"following"` / `"verified"` / `"all"`）
`allow_dm_groups_from`	string	DM 群组邀请来源
`allow_media_tagging`	string	照片标记权限（`"all"` / `"following"` / `"none"`）
`discoverable_by_email`	bool	是否允许通过邮箱发现账号
`discoverable_by_mobile_phone`	bool	是否允许通过手机号发现账号
`dm_receipt_setting`	string	DM 已读回执（`"all_enabled"` / `"all_disabled"`）
`dm_quality_filter`	string	低质量 DM 过滤（`"enabled"` / `"disabled"`）
`mention_filter`	string	提及过滤规则（`"unfiltered"` / `"following"` / `"verified"`）
`allow_ads_personalization`	bool	是否允许广告个性化
`allow_sharing_data_for_third_party_personalization`	bool	是否允许第三方数据共享

update-account — 批量更新账号设置¶

一次 POST 请求同时修改多个账号设置字段。只传入需要修改的 flag，未传入的字段不会被修改。

语法¶

twitter-cli [全局 flags] settings update-account [flags...]

可用 Flag¶

Flag	类型	取值	说明
`--protected`	BOOL	true/false	帖子保护（仅粉丝可见）
`--nsfw-user`	BOOL	true/false	NSFW 账号标记
`--display-sensitive-media`	BOOL	true/false	展示他人的敏感媒体
`--geo-enabled`	BOOL	true/false	地理位置功能
`--allow-dms-from`	STR	following/verified/all	DM 接收来源
`--allow-dm-groups-from`	STR	following/verified/all	DM 群组邀请来源
`--allow-media-tagging`	STR	all/following/none	照片标记权限
`--discoverable-by-email`	BOOL	true/false	邮箱可发现性
`--discoverable-by-mobile`	BOOL	true/false	手机号可发现性
`--dm-receipt-setting`	STR	all_enabled/all_disabled	DM 已读回执
`--dm-quality-filter`	STR	enabled/disabled	低质量 DM 过滤
`--mention-filter`	STR	unfiltered/following/verified	提及过滤规则
`--allow-ads-personalization`	BOOL	true/false	广告个性化
`--allow-third-party-personalization`	BOOL	true/false	第三方数据共享

重要: 多个 flag 可以同时传入，SDK 将它们合并为一次 POST 请求，避免多次网络往返。

示例：一次 POST 设置 6 项¶

# 敏感账号典型配置（一次 POST）
twitter-cli --cookies-file cookies.txt settings update-account \
  --nsfw-user true \
  --display-sensitive-media true \
  --allow-dms-from all \
  --dm-receipt-setting all_disabled \
  --discoverable-by-email false \
  --discoverable-by-mobile false

输出（格式化后）：

{
  "success": true,
  "data": {
    "screen_name": "myaccount",
    "nsfw_user": true,
    "display_sensitive_media": true,
    "allow_dms_from": "all",
    "dm_receipt_setting": "all_disabled",
    "discoverable_by_email": false,
    "discoverable_by_mobile_phone": false,
    "protected": false,
    "geo_enabled": false,
    "nsfw_admin": false,
    "allow_dm_groups_from": "following",
    "allow_media_tagging": "all",
    "mention_filter": "unfiltered",
    "allow_ads_personalization": true,
    "allow_sharing_data_for_third_party_personalization": true,
    "dm_quality_filter": "enabled",
    "language": "zh-cn",
    "country_code": "CN"
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "update-account",
    "elapsed_ms": 387,
    "timestamp": "2026-06-04T10:01:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

get-search-safety — 查询搜索安全设置¶

语法¶

twitter-cli [全局 flags] settings get-search-safety

参数¶

无需额外参数。

成功示例¶

twitter-cli --cookies-file cookies.txt settings get-search-safety

输出：

{
  "success": true,
  "data": {
    "opt_in_filtering": false,
    "opt_in_blocking": true
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "get-search-safety",
    "elapsed_ms": 120,
    "timestamp": "2026-06-04T10:02:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

data 字段说明¶

字段	说明
`opt_in_filtering`	`true` = 搜索中隐藏敏感内容（Hide sensitive content）
`opt_in_blocking`	`true` = 从搜索结果中移除已屏蔽/静音账号

set-search-safety — 设置搜索安全¶

语法¶

twitter-cli [全局 flags] settings set-search-safety --filtering BOOL --blocking BOOL

参数¶

Flag	类型	必填	说明
`--filtering`	BOOL	是	`true` = 搜索中隐藏敏感内容
`--blocking`	BOOL	是	`true` = 从搜索结果中移除已屏蔽/静音账号

两个参数均为必填，API 一次写入两个字段。

示例¶

# 关闭敏感过滤 + 开启屏蔽账号过滤
twitter-cli --cookies-file cookies.txt settings set-search-safety \
  --filtering false \
  --blocking true

# 两项全关
twitter-cli --cookies-file cookies.txt settings set-search-safety \
  --filtering false \
  --blocking false

输出：

{
  "success": true,
  "data": {
    "success": true,
    "setting_name": "search_safety",
    "error_msg": ""
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "set-search-safety",
    "elapsed_ms": 185,
    "timestamp": "2026-06-04T10:03:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

get-audience — 查询受众设置¶

语法¶

twitter-cli [全局 flags] settings get-audience

参数¶

无需额外参数。

成功示例¶

twitter-cli --cookies-file cookies.txt settings get-audience

输出：

{
  "success": true,
  "data": {
    "protect_videos": false
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "get-audience",
    "elapsed_ms": 205,
    "timestamp": "2026-06-04T10:04:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

data 字段说明¶

字段	说明
`protect_videos`	`true` = 他人无法通过官方途径下载该账号的视频

set-protect-videos — 设置视频下载保护¶

使用 GraphQL API（AudienceAndTaggingAllowVideoDownloadsMutation）设置视频下载保护。

语法¶

twitter-cli [全局 flags] settings set-protect-videos --enabled BOOL

参数¶

Flag	类型	必填	说明
`--enabled`	BOOL	是	`true` = 开启保护（禁止下载）；`false` = 允许下载

示例¶

# 开启视频保护
twitter-cli --cookies-file cookies.txt settings set-protect-videos --enabled true

# 关闭视频保护（允许下载）
twitter-cli --cookies-file cookies.txt settings set-protect-videos --enabled false

输出：

{
  "success": true,
  "data": {
    "success": true,
    "setting_name": "protect_videos",
    "error_msg": ""
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "set-protect-videos",
    "elapsed_ms": 260,
    "timestamp": "2026-06-04T10:05:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

get-explore — 查询 Explore 设置¶

语法¶

twitter-cli [全局 flags] settings get-explore

参数¶

无需额外参数。

成功示例¶

twitter-cli --cookies-file cookies.txt settings get-explore

输出：

{
  "success": true,
  "data": {
    "use_personalized_trends": true,
    "use_current_location": false
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "get-explore",
    "elapsed_ms": 95,
    "timestamp": "2026-06-04T10:06:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

data 字段说明¶

字段	说明
`use_personalized_trends`	`true` = 开启个性化"Trends for you"；`false` = 显示通用趋势
`use_current_location`	`true` = 基于当前位置显示 Explore 内容

set-explore — 更新 Explore 设置¶

语法¶

twitter-cli [全局 flags] settings set-explore [--personalized-trends BOOL] [--current-location BOOL]

参数¶

Flag	类型	必填	说明
`--personalized-trends`	BOOL	否	控制"Trends for you"个性化
`--current-location`	BOOL	否	控制位置感知功能

至少需要传入其中一个 flag。

注意: 部分地区账号（如日本区）服务端可能忽略 --personalized-trends false，这是 X 平台的地区限制，SDK 层会正常发出请求但无法绕过服务端限制。

示例¶

# 关闭个性化趋势
twitter-cli --cookies-file cookies.txt settings set-explore --personalized-trends false

# 同时关闭两项
twitter-cli --cookies-file cookies.txt settings set-explore \
  --personalized-trends false \
  --current-location false

输出：

{
  "success": true,
  "data": {
    "success": true,
    "setting_name": "explore_settings",
    "error_msg": ""
  },
  "error": null,
  "meta": {
    "module": "settings",
    "action": "set-explore",
    "elapsed_ms": 142,
    "timestamp": "2026-06-04T10:07:00Z",
    "cli_version": "2.0.0",
    "schema_version": "1.0"
  }
}

常见错误¶

错误码	原因	解决方法
`AUTH_FAILED`	cookies 过期或权限不足	重新导出 cookies
`RATE_LIMIT`	查询过于频繁	等待后重试
`SERVER`	Twitter 服务端异常	稍后重试
`INVALID_ARGUMENT`	枚举参数值无效（如 `--allow-dms-from xyz`）	检查允许值（following/verified/all 等）
`UNKNOWN`	未知错误	查看 `error.details` 字段获取更多信息

Settings 模块（账号设置）¶

目录¶

命令总览¶

get-account — 查询完整账号设置¶

语法¶

参数¶

成功示例¶

data 字段说明¶

update-account — 批量更新账号设置¶

语法¶

可用 Flag¶

示例：一次 POST 设置 6 项¶

更多示例¶

get-search-safety — 查询搜索安全设置¶

语法¶

参数¶

成功示例¶

data 字段说明¶

set-search-safety — 设置搜索安全¶

语法¶

参数¶

示例¶

get-audience — 查询受众设置¶

语法¶

参数¶

成功示例¶

data 字段说明¶

set-protect-videos — 设置视频下载保护¶

语法¶

参数¶

示例¶

get-explore — 查询 Explore 设置¶

语法¶

参数¶

成功示例¶

data 字段说明¶

set-explore — 更新 Explore 设置¶

语法¶

参数¶

示例¶

常见错误¶