X / Twitter

X 插件将对你机器人账号的提及转换为代理会话，并将代理的回答作为公开回复发布。默认情况下，只有允许列表中的作者才能触发回复。除非启用访客模式，否则未知作者会被静默丢弃；他们不会收到配对提示。

每个 X 会话都是由其 conversation_id 标识的群线程。代理会接收触发提及，以及可用的祖先帖子、会话帖子和引用帖子。原始提及仍然是用户可见的消息。不支持私信、原始帖子、点赞、关注以及媒体上传。

设置¶

该插件随包含 extensions/x 的构建版本一起捆绑提供。要从本地检出将其添加到 OpenClaw 2026.9.8 安装中：

openclaw plugins install --link ./extensions/x

使用 X 机密 OAuth2 应用，并授权机器人账号具有 tweet.read tweet.write users.read offline.access 权限。保留其客户端 ID、客户端密钥和用户上下文刷新令牌。插件使用 HTTP Basic 客户端身份验证刷新访问令牌。可选的独立仅应用 Bearer 令牌可启用 Activity API。

X 在签发访问令牌时可能会轮换刷新令牌。插件将最新令牌保存在私有的、由 worker 支持的插件状态（x.oauth）中，以便在重启后仍然可用。更改配置的刷新令牌种子会开始新的令牌谱系。此存储不保证静态加密；请将 Gateway 的状态目录及其备份作为凭据加以保护。

设置机器人的数字用户 ID 和用户名，然后在 allowFrom 中添加至少一个维护者的数字 X 用户 ID：

{
  channels: {
    x: {
      enabled: true,
      userId: "123456789",
      username: "example_bot",
      clientId: "example-x-client-id",
      clientSecret: { source: "env", provider: "default", id: "X_CLIENT_SECRET" },
      refreshToken: { source: "env", provider: "default", id: "X_REFRESH_TOKEN" },
      bearerToken: { source: "env", provider: "default", id: "X_BEARER_TOKEN" },
      allowFrom: ["987654321"],
      groupPolicy: "allowlist",
      dmPolicy: "disabled",
      events: { mode: "auto", pollSeconds: 60 },
      threadContext: { maxPosts: 50 },
      costLimits: { dailyUsd: 100, monthlyUsd: 1000, cycleStartDay: 1 },
    },
  },
  bindings: [{ agentId: "main", match: { channel: "x" } }],
}

替换示例 ID 和用户名。使所引用的环境变量对 Gateway 可用。省略 bearerToken 可在不使用 Activity API 的情况下使用轮询。所有三个机密字段也接受明文或受支持的 SecretRef 输入。

运行 openclaw config validate 和 openclaw channels status。从允许列表中的账号在帖子中提及机器人。成功的一轮会在该帖子下方生成一条公开回复。常规 通道绑定 选择代理和会话；插件不会覆盖会话范围。

对于多个机器人，请将特定于账号的值放在 channels.x.accounts.<accountId> 下。根字段是共享默认值；默认账号 ID 为 default。

公开工作会话¶

设置 channels.x.accounts.<accountId>.autoPublishWorkSessions: true（或共享根默认值 channels.x.autoPublishWorkSessions），以发布由已准入的维护者提及直接生成的全新、隔离的可见工作会话。访客提及仍仅限于隐藏助手，并且无法发布工作会话。此功能默认关闭。它会在相同的规范 /chat 链接上将该子会话暴露给匿名读者；它不会更改 Team 协作权限。仅对旨在公开其工作的代理启用此功能。

发布需要配置仅应用 bearerToken。在准入之前，插件使用仅应用身份验证查找所提供线程上下文中的每个帖子，并要求明确的 protected: false 作者元数据。缺失、已编辑、受保护、被扣留或不可用的帖子以及查找失败会拒绝自动发布。永久链接或成功的用户上下文查找并不是公开受众的证明。验证读取共享该账号的 X API 预算；预算不足会拒绝发布，而不会绕过成本限制。

该权限仅属于该传入调用：它不会存储在 X 会话上，不会被孙代会话继承，也不会被接受在模型生成的生成参数中。分支、私有/草稿会话、隐身会话和现有会话无法自动发布。更改账号配置或允许列表会使进行中的发布权限失效。创建所有者会在子会话的第一轮之前与其一起提交公开授权，并且生成回执仅对已提交的授权报告 publicRead。没有该回执的链接会被标记为需要登录。此通道需要实时进程内 Gateway；它不会降级为会丢失调用权限的传输方式。

手动发布仍受现有创建者/管理员共享控制管理。任何 X 身份都不会提升为 Team 个人资料或管理员。

管理允许列表¶

以管理员身份在控制 UI 中打开 X 回复。该页面显示配置 allowFrom 条目和通过页面添加的用户的生效并集。添加用户名以将其解析为稳定的数字 X 用户 ID。存储的条目会保留解析后的用户名、显示名称、添加操作者和时间戳。从页面中删除存储的条目；配置条目是只读的，必须从配置中删除。

该页面还显示该账号今天和当前计费周期的预计 X API 支出及其限制。选择 刷新 以更新只读总计。相同的支出快照包含在 x.allowlist.list 中。

本地链接安装使用 自定义插件 UI 设置。启用 设置 → 实验室 → 自定义插件 UI，然后使用 Gateway 通过 HTTPS 或受信任回环提供的控制 UI。捆绑安装不需要该设置。

Gateway 方法 x.allowlist.list、x.allowlist.add 和 x.allowlist.remove 需要 operator.admin。按数字 ID 授权发送者， 可以是 987654321 或 x:987654321；handle 应放在按 handle 添加的 UI 中，而不是 allowFrom 中。

guests.enabled 控制维护者允许列表之外的准入。旧版 groupPolicy: "open" 设置没有必要，也无法绕过访客开关。 groupPolicy: "disabled" 会关闭所有入站回合。dmPolicy 只接受 disabled。

访客模式¶

访客模式允许维护者允许列表之外的人提出仓库问题。 默认关闭。配置下面的前置代理后，使用 X replies 上的 Guest mode 开关，或运行：

openclaw config set channels.x.guests.enabled true
openclaw config set channels.x.guests.enabled false

配置监视器会重新加载 X 通道，而无需重启 Gateway。UI 使用仅限管理员的 x.guests.set 方法，并持久化相同配置。 对于显式配置的账号，开关会写入该账号的覆盖项； 否则写入 channels.x.guests.enabled。账号覆盖项会从通道根继承 其他访客设置。

访客获得核心 read、ls、sessions_spawn、sessions_yield 和 subagents 工具，并进一步受代理正常策略限制。他们可以 启动同一代理的隐藏助手。助手继承访客受限的 工具和仓库根目录；它们不能成为可见的工作会话，也不能指向 另一个代理。sessions_yield 等待助手完成，而 subagents 列出、等待或取消助手。

访客不能编辑文件、运行命令、浏览或抓取网页、使用 memory、 发送消息，或检查无关会话。可选的 guests.tools.allow 可以缩小五个默认工具的范围；空数组会禁用所有工具。 guests.tools.deny 优先。这两个设置都不能添加更强的工具。

隐藏助手需要一个声明会执行这些限制的主机。 旧版主机会保留 read 和 ls 默认值，即使它们报告相同的 OpenClaw 版本。X replies 设置页面在缺少助手 支持时会显示升级指引。在旧版主机上显式仅选择助手工具 会禁用所有访客工具；它不会恢复默认 read 工具。

每个访客提及都会获得独立的通道会话和被引用的 X 线程 上下文。它不会复用维护者的对话历史、权限模式、 根目录或已选技能。维护者保留其现有会话、 工具和工作会话回复。访客回复可以引用文档 URL，但 OpenClaw 绝不会在访客回复后附加工作会话链接。

仓库隔离¶

仅靠工具名称无法限制文件系统读取。将 X 前置 代理的 cwd 和 workspace 配置为 OpenClaw 克隆，并启用核心的 仅限工作区的文件保护。受支持的访客设置还会禁用已选 技能和 Docker/远程沙箱模式：技能目录和沙箱挂载是 核心中的显式读取例外，可能会暴露该克隆之外的文件。 例如，向你的 X 绑定所选的代理添加这些字段：

```json5 validate=false { workspace: "/srv/openclaw", cwd: "/srv/openclaw", skills: [], sandbox: { mode: "off" }, tools: { fs: { workspaceOnly: true } }, }

生效的文件系统设置是
`agents.entries.<agentId>.tools.fs.workspaceOnly`，回退到
`tools.fs.workspaceOnly`。当该设置缺失或为 false、技能已启用，或沙箱模式
处于活动状态时，X 插件会在线程展开前拒绝访客。通道状态会将所需修正报告为
`guestModeBlockedReason`；维护者提及照常继续。

访客模式还要求一种不能引导或中断活动
回合的队列模式。在启用访客之前设置通道覆盖项：

```json5
{
  messages: { queue: { byChannel: { x: "followup" } } },
}

collect 也受支持。如果没有通道覆盖项，messages.queue.mode 必须是 followup 或 collect；默认 steer 和显式 interrupt 会在线程展开前阻止访客准入。X replies 页面会在其现有的访客就绪消息中显示 所需设置。将队列模式改回任一不安全值会阻止后续访客提及。

核心负责路径和符号链接隔离，并以 Path escapes sandbox root 拒绝会话 根目录之外的读取。保持访客通道会话处于其 初始权限：不要授予完整权限、扩大其会话根目录， 或通过操作员控制附加外部技能或技能库固定项。 这些操作员操作会故意改变核心的文件系统权限。访客 回合没有可以做出这些更改的工具。当维护者工作需要更广泛的文件系统或技能时，将其放在其 正常工作会话中。

限制与身份¶

默认限制是 每位访客作者每个 UTC 日 5 次提及， 每个 bot 账号独立计算。将 guests.maxMentionsPerAuthorPerDay 设置为 0 到 1000； 0 表示不接纳访客。超限提及会在线程展开前被静默丢弃。访客线程上下文默认为 10 条帖子，由 guests.threadContextMaxPosts 控制；维护者保留 threadContext.maxPosts。 UI 和通道状态会暴露 guests.enabled、admittedToday 和 rateLimitedToday。接纳计数包括已预留回合，即使后续 线程查找或模型运行失败；重试会复用其预留。

使用情况保存在有界、由 worker 支持的插件状态（x.guest-usage）中，保留两天。容量耗尽会暂停新的访客接纳，而不是驱逐 当前作者的配额。近期被拒绝的帖子 ID 会被保留，以避免将 正常重试重复计数；在该有界历史之后异常迟到的重试可以 再次增加速率限制统计。入口队列会单独 抑制已完成事件的重放。

访客回合会产生与其他回合相同的 X API 和模型成本。线程读取 和每条回复帖子按正常计费；访客引用 URL 会适用 X 的 含 URL 回复的更高价格。作者配额不是美元预算。

安全： 主机仅根据 X 的数字 author_id 与已配置和管理员管理的允许列表条目的有效并集来确定权限层级。句柄、显示名称、帖子文本和模型输出永远不会授予维护者访问权限。每个面向代理的回合都以主机生成的发件人行开始；其下方的所有线程帖子都是引用数据。当访客模式开启时，从允许列表中移除维护者会使后续提及变为访客。

事件模式¶

默认值为 auto。流式传输使用仅限应用的 bearerToken 列出现有订阅，然后使用机器人的 OAuth2 用户访问 token（从 refreshToken 刷新）为机器人创建缺失的 post.mention.create 订阅。提及订阅要求用户授予 tweet.read。持久的 GET /2/activity/stream 连接使用仅限应用的 bearer token，如 X 的 Activity Stream API 中所述。

流式传输从 X 的 data.payload 信封中读取 post.mention.create 事件，检查帖子是否指向机器人，并忽略空白 keep-alive。其他事件类型不会创建入站回合；已送达的 post.* 事件仍会计入预算。在流停滞或断开后，它会使用退避重连。 每个连接使用用户 token 从已保存的游标运行一次提及回填，然后在流式传输期间每 events.pollSeconds × 4 重复一次（最少 60 秒，默认 240 秒）。此安全回填可恢复流中遗漏的提及。只有完成的回填页面才会推进游标，因此较新的流事件不会隐藏较早的遗漏提及。帖子 ID 对流和轮询事件进行去重。

在连续出现三个无法解析的提及事件或格式错误的行后，插件会记录一条警告，并将其显示在频道状态 message 中。空白 keep-alive 和有意忽略的事件类型不计入此警告。它包含事件类型和顶层键，但不包含帖子内容。下一个可解析的提及事件会清除该警告。

在 auto 模式下，任何订阅设置失败都会切换到轮询。在 stream 模式下，订阅 HTTP 403 会切换到轮询；其他设置错误会停止事件源。流 HTTP 401 或 403 会将任一模式切换到轮询。频道状态 message 包含失败的端点、HTTP 状态以及可用时的第一条 X 错误消息，凭据会被脱敏。例如：

X API /2/activity/subscriptions failed (HTTP 400): OauthAccessTokenRequired: OAuth user access token is required for this event type; polling

此消息解释为什么 Activity 无法启动；轮询仍保持活动。无法读取的错误主体仍会报告 HTTP 状态。网络和 token 刷新失败会报告其客户端错误，而不包含提供商响应详情。

轮询默认为 60 秒；events.pollSeconds 不能小于 15。 每个请求请求 10 条提及，这是 X 的最小页面大小，并在仍有积压时遵循分页。这使每个请求的预留保持较小，同时仍能追上所有可用提及。 入站帖子在游标推进之前会被持久化排队。已完成事件 ID 最多保留 30 天，每个账户限制 2,000 条已完成条目，从而在重连和重启后防止重复回合，只要这些条目仍被保留。

线程上下文与回复¶

插件按最旧优先的顺序渲染可用的线程帖子，格式为 @handle (time): text，并标记触发提及。它会跟踪回复祖先，读取近期对话，并包含引用帖子。threadContext.maxPosts 默认为 50；达到限制时，会保留根帖子和最新帖子。近期搜索覆盖范围限于七天，不可用或已删除的帖子无法包含。

对话搜索请求 10 到 100 条帖子，受剩余上下文配额限制；X 要求最少 10 条。达到上下文限制时分页停止。如果预算无法覆盖更多上下文，代理将收到提及和已获取的任何上下文，并标记为“线程上下文因预算被截断。”

回复被拆分为自回复链，每帖最多 280 个加权字符；每个 URL 计为 23 个字符。最后一个分块接收 replySignature，其默认值为 🤖 automated reply。将其设置为空字符串可禁用签名。

当维护者回合启动一个可见的工作会话时，除非文本已包含该 URL，否则其第一个会话 URL 会被追加到回复中。规范链接仅在创建回执确认发布时才可公开读取；否则会被标记为“工作会话（需要登录）。” 两者都使用 X 的包含 URL 的回复价格。

对于通过消息工具或 CLI 的直接回复，请使用 x: 前缀指定帖子 ID，或使用其完整的 X 状态 URL：

openclaw message send --channel x --target x:1234567890123456789 --message "Reply text"

目标必须满足 X 的回复资格：其作者提及或引用了应用账户。不支持发送媒体或创建原创帖子。

成本与限制¶

插件默认为每个账户设置 每个 UTC 日 $100 和 每个计费周期 $1,000。这些限制仅涵盖 X API 调用；模型 token 单独计算。 将 costLimits.cycleStartDay 设置为您 X 计费周期开始月份的 UTC 日期，范围为 1 到 28。例如，20 表示周期从 20 日 00:00 UTC 开始，持续到下个月的 20 日。账户条目从 channels.x 继承这些字段，并可单独覆盖它们。

这两个限制均接受非负美元金额。0 会阻止付费请求。没有无限制设置；如需更高上限，请使用较大的限制值。X 自身的每个计费周期上限仍然适用，并且可以独立拒绝请求。

这些估算使用 X 的已发布的按使用量付费费率，已于 2026 年 10 月 4 日核实：

线程展开会读取额外帖子。较长的回答会创建多个计费的回复帖子。在允许列表 UI 中添加一个 handle 会执行一次付费用户名查找。这些是 X API 成本，与 agent 的模型用量分开计算。

支出以整数微美元形式存储在插件的 worker 支持的状态中，每个账户分别具有每日和计费周期桶。插件在每次付费请求前预留最坏情况成本，并根据返回的资源进行结算，释放任何未使用的预留。并发请求共享同一账户预算。响应丢失、HTTP 5xx 或无法解析的成功响应会保留全部预留，因为请求可能已经成功发出；只有可证明未发出或明确的 HTTP 4xx 拒绝才会在不计资源的情况下释放预留。显示的支出包括待处理预留。跨越 UTC 午夜请求会保守地计入两天，但只计入共享计费周期一次。跨越计费周期边界会同时计入两个周期。中断的请求在重启后仍保留其全部预留。

会计处理有意忽略 X 在 UTC 一天内的资源去重，因此重复读取会再次计数。X 是否对展开用户计费尚未确认；插件将其计入以避免低估支出，包括随 Activity 事件返回的展开内容。所有已交付的 post.* Activity 事件均会计入，即使它们未产生 agent 回合。因此，估算值可能超过 X 的账单。X 的 Activity 页面和定价页面对于是否对 post.delete 计费存在不一致；插件保守地按与其他帖子事件相同的费率将其计入。

Activity 流使用固定的 $0.50 余量。如果任一剩余预算低于该余量，插件会关闭流，并使用受控提及轮询，直到受影响的预算重置。在流关闭前 X 已经交付的事件仍会被计费并接纳；它们可能使记录的支出超过限制。该余量可降低这种风险，但它不是对 X 已经交付的突发流量的严格上限。只有当完整预留可以容纳时，轮询请求才会继续。

当没有付费轮询可以容纳时，ingress 会暂停直到重置，且不推进其 since_id 游标。已获取的提及会被持久化接纳，其下一页令牌会保存在游标旁边，以便在重置或重启后回填可以继续处理更早的页面。如果 X 拒绝已保存的令牌，插件会从 since_id 重新开始该回填；ingress 队列会对已接纳的提及去重。通道状态会报告当前支出、限制、周期开始时间和恢复时间，并附带类似 X API daily budget of $100 reached; resumes at 2026-10-06T00:00Z 的原因。插件在达到限制时记录一次日志，在重置时记录一次日志。无法负担的回复会以不可重试错误拒绝；回复链按块计费。

当 Activity 事件省略提及实体时，插件会查找该帖子以验证其是否指向此 bot。如果预算无法覆盖验证，提及会被持久化排队，并在重置后、任何 agent 回合之前进行验证。未验证的事件以及针对其他 bot 的事件不会推进此账户的游标。如果提及实体仅提供用户名，插件会执行一次 $0.01 用户查找以验证数字接收者 ID；仅配置的用户名不能授权回复。

配置参考¶

除非另有说明，这些字段在 channels.x 和单个账户条目上均有效。

故障排除¶

无回复： 检查账户状态、数字机器人 ID 和生效的允许列表。 被丢弃提及计数器和最后被丢弃的作者解释了有意沉默。 没有配对流程。在默认策略下，空的允许列表会阻止所有作者。

流式回退： 检查状态消息中的 Activity 端点、 HTTP 状态和 X 错误详情。验证应用 bearer 和机器人的 OAuth2 授权，包括 tweet.read。如果没有应用 bearer，auto 和 stream 会使用 轮询。检查报告的事件模式、流连接/退避、最后事件 和游标。 当任一预算剩余少于 $0.50 时，流式也会切换到轮询，并在该预算重置后恢复。

预算暂停： 检查频道状态中的 spend 或 X 回复 页面。 状态消息会给出受影响的限制和重置时间。将 costLimits.cycleStartDay 与你的 X 计费周期对齐，并在需要时增加相应 限制。更改限制不会清除已记录的支出。

Token 刷新失败： 检查 client ID、client secret、refresh token 和 已授予的 OAuth2 范围。状态会报告刷新状态，而不会暴露机密。

回复被拒绝： 确认源作者提及或引用了应用 账户，并且应用具有 tweet.write。在重试部分发送的 回复链之前，检查错误。

回复 POST 之前的失败可以安全重试。如果 POST 的结果不确定， OpenClaw 会保留该不确定性，而不是自动再次发送回复。 在手动重试不确定或部分发送的回复之前，检查 X。

相关¶

• 频道路由
• 配置
• 机密
• 管理插件