跳转至

Tlon

Tlon 是一个基于 Urbit 构建的去中心化消息应用。OpenClaw 连接到你的 Urbit ship,并响应私信和群聊消息。群聊回复默认需要 @ 提及,并在此基础上叠加了授权规则和所有者审批流程。

状态:内置插件。支持私信、群聊提及、话题、富文本、图片上传/下载以及所有者审批系统。不支持表情回应和投票。

内置插件

Tlon 已随当前 OpenClaw 版本捆绑发布;打包构建无需单独安装。

在较旧的构建或未包含它的自定义安装中,可从 npm 安装:

openclaw plugins install @openclaw/tlon

使用裸包名跟踪当前发布标签。仅在进行可复现安装时才固定版本(@openclaw/tlon@x.y.z)。

从本地检出安装:

openclaw plugins install ./path/to/local/tlon-plugin

详情:插件

配置

openclaw channels add --channel tlon --ship ~sampel-palnet --url https://your-ship-host --code lidlut-tabwed-pillex-ridrup

或直接编辑配置:

{
  channels: {
    tlon: {
      enabled: true,
      ship: "~sampel-palnet",
      url: "https://your-ship-host",
      code: "lidlut-tabwed-pillex-ridrup",
      ownerShip: "~your-main-ship", // recommended: your ship, always authorized
    },
  },
}

登录代码是你 ship 的 Web 登录代码:在 ship 的 dojo 中运行 +code 即可输出当前代码。该代码会轮换,因此每当身份验证开始失败时,请重新读取。

ship URL 支持方括号形式的 IPv6 字面量,例如 http://[::1]:8080。回环地址和私有 IPv6 地址需要启用下文中的私有网络选项。

配置更改遵循热重载。运行 openclaw channels status --probe 检查状态,如果 Gateway 离线则先启动它。然后私信机器人,或在群组频道中 @ 提及它。

入站持久性

OpenClaw 会在分发给 agent 之前持久化已接受的 Tlon 私信和群聊事件。待处理或可重试的轮次在 Gateway 重启后仍会保留,并且每个群组频道或直接对端的工作仍保持串行处理。稳定的 Urbit 消息 ID 还能在其队列记录或保留的完成记录存在时,抑制重复投递的事件。

投递在队列到 agent 边界上为至少一次:交接过程中发生崩溃可能会重放一个轮次。因此,产生外部副作用的 agent 操作应尽可能保持幂等。

私有/局域网 ship

OpenClaw 默认阻止私有/内部主机名和 IP 范围以进行 SSRF 防护。如果你的 ship 运行在私有网络(localhost、局域网 IP、内部主机名)上,请显式选择启用:

{
  channels: {
    tlon: {
      url: "http://localhost:8080",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
    },
  },
}

适用于像 http://localhost:8080、http://192.168.x.x:8080 和 http://my-ship.local:8080 这样的目标。请仅对你信任的 ship URL 启用此选项;它会禁用该账户 HTTP 请求的 SSRF 防护。

Note

channels.tlon.allowPrivateNetwork(扁平键)已弃用。openclaw doctor --fix 会自动将其迁移到 channels.tlon.network.dangerouslyAllowPrivateNetwork。

群组频道

手动固定频道,或开启自动发现:

{
  channels: {
    tlon: {
      groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
      autoDiscoverChannels: true,
    },
  },
}

autoDiscoverChannels 在配置中未设置时默认为 false;设置向导默认将提示设为 yes,并显式写入 true。开启后,OpenClaw 会在启动时 scry 已加入的群组,在接受群组邀请时监听新频道,并每 2 分钟重新检查一次。

访问控制

DM 允许列表(空列表 = 不允许任何私信,除非发送者是 ownerShip):

{
  channels: {
    tlon: {
      dmAllowlist: ["~zod", "~nec"],
    },
  },
}

群组授权默认按频道设为 restricted。设置 defaultAuthorizedShips 作为基线,并可针对每个频道 nest 进行覆盖:

{
  channels: {
    tlon: {
      defaultAuthorizedShips: ["~zod"],
      authorization: {
        channelRules: {
          "chat/~host-ship/general": {
            mode: "restricted",
            allowedShips: ["~zod", "~nec"],
          },
          "chat/~host-ship/announcements": {
            mode: "open",
          },
        },
      },
    },
  },
}

一旦机器人回复了某个话题,之后该话题中的后续消息无需再次提及,它也会继续响应。

将 channels.tlon.implicitMentions.threadParticipation 设为 false,可要求这些后续消息重新显式提及。账户级覆盖使用 channels.tlon.accounts.<id>.implicitMentions。Tlon 目前不会产生 replyToBot 或 quotedBot facts,因此这些标志在这里没有效果。

将 channels.tlon.requireMentionInBotThreads 设为 false,则当该账户的 ship 创建了话题根消息时,接受未提及的回复,包括第一条回复。设为 true 则要求这些话题中即使机器人已参与,也需要新的提及。省略该选项则保留现有的参与策略。根作者从已认证的 ship API 读取;如果根消息不可用或来自外部,则维持常规提及策略。

命名账户可以通过 accounts.<id>.requireMentionInBotThreads 覆盖该设置。按频道设置的 authorization.channelRules.<nest>.requireMentionInBotThreads 会覆盖账户默认值,包括通过 Urbit settings store 提供的规则。对于此选项,已保存的频道规则只有在设置布尔值时才覆盖文件中的值;旧的仅访问规则继承文件中的值。发送者授权仍然生效,且此选项不会改变频道顶层帖子或私信。

所有者与审批系统

{
  channels: {
    tlon: {
      ownerShip: "~your-main-ship",
    },
  },
}

所有者 ship 在所有场景下都被授权:私信邀请始终自动接受,群组邀请始终自动接受,频道消息始终通过授权。所有者无需出现在 dmAllowlist、defaultAuthorizedShips 或 groupInviteAllowlist 中。

当设置了 ownerShip 时,未授权的请求不会被直接丢弃——它们会进入待审批队列,并触发向所有者发送 DM:

  • 来自不在 dmAllowlist 中的 ship 的 DM 请求
  • 未通过授权者在频道中的提及(mention)
  • 来自不在 groupInviteAllowlist 中的 ship 的群组邀请(当自动接受关闭时,或开启但邀请者不在允许列表中时)

所有者通过 DM 回复以处理请求:

所有者回复 效果
approve / deny / block 作用于最近的待审批请求
approve <id> / deny <id> 按 id 作用于特定审批请求
block 同时以原生方式屏蔽该 ship,使其无法重新连接
unblock ~ship 撤销原生屏蔽
blocked 列出当前被屏蔽的 ship
pending 列出待处理的审批请求

未配置 ownerShip 时,未授权的 DM 和频道提及只会被丢弃并记录日志;不会有审批提示。

监控器最多接收 100 个新的待审批请求。来自旧版本的既有审批会被保留,因此在升级后,所有者的回复仍会指向同一个请求。当队列已满时,监控器会向所有者发送一次饱和通知,并且在待处理项解决之前不再接纳更多新的请求。在每个队列填满周期内,通知投递失败最多重试三次。容量恢复后接纳新请求即开启一个新的周期,因此在同一轮监控器运行期间,再次填满队列可以再次发送通知。被拒绝的请求者必须在容量可用后重试;待处理的 DM 和群组邀请更新保持可重试状态,而不会被确认。

群组邀请更新一次只应用于一个群组。被撤销、移除或已完成的邀请会清除该群组的重复抑制状态,以便后续邀请能够在当前的自动接受和允许列表设置下被处理。

自动接受设置

自动接受来自已在 dmAllowlist 中的 ship 的 DM 邀请(无论此标志如何,所有者始终会被自动接受):

{
  channels: {
    tlon: {
      autoAcceptDmInvites: true,
    },
  },
}

自动接受来自允许列表的群组邀请(默认拒绝:当 autoAcceptGroupInvites: true 且 groupInviteAllowlist 为空时,不接受任何非所有者的邀请):

{
  channels: {
    tlon: {
      autoAcceptGroupInvites: true,
      groupInviteAllowlist: ["~zod"],
    },
  },
}

通过 Urbit 设置存储实现热重载

上述大部分设置(dmAllowlist、groupInviteAllowlist、groupChannels、defaultAuthorizedShips、autoDiscoverChannels、autoAcceptDmInvites、autoAcceptGroupInvites、ownerShip、showModelSignature)会在首次运行时镜像到 ship 的 %settings agent(desk moltbot,bucket tlon),然后从那里实时读取,因此通过 Landscape 客户端或内置技能的设置命令所做的更改无需重启网关即可生效。channelRules 和待处理审批也会以 JSON 形式持久化存储在那里。对于从未写入设置存储的值,文件配置仍然是权威来源。

投递目标(CLI/cron)

与 openclaw message send 或 cron 投递一起使用:

  • DM:~sampel-palnet 或 dm/~sampel-palnet
  • 群组:chat/~host-ship/channel 或 group:~host-ship/channel

内置技能

该插件内置了 @tloncorp/tlon-skill,这是一个用于直接执行 Urbit 操作的 CLI,插件安装后即可自动使用:

  • 动态(Activity):提及、回复、未读
  • 频道(Channels):列出、创建、重命名
  • 联系人(Contacts):列出/获取/更新个人资料
  • 群组(Groups):创建、加入、邀请/请求流程、角色
  • 钩子(Hooks):管理频道钩子
  • 消息(Messages):历史记录、搜索
  • DM:发送、回应、接受/拒绝
  • 帖子(Posts):回应、删除
  • 记事本(Notebook):发布到日记频道
  • 设置(Settings):通过上述设置存储热重载插件配置

功能特性

channels.tlon.mediaMaxMb 以 MiB 为单位限制每个入站图片下载和出站图片加载。命名账户可以通过 accounts.<id>.mediaMaxMb 覆盖该限制;否则依次应用频道根配置和 agents.defaults.mediaMaxMb。现有的 6 MiB 上限适用于图片下载和上传。配置上限后,如果大小检查或下载失败,则发送失败,而不会嵌入未经检查的 URL。在成功完成有界下载后,上传失败时仍然可以使用原始 URL。未配置上限时,即使图片无法在该上限内下载,现有的链接回退仍然可用。

功能 状态
直接消息(DM) 支持
群组/频道 支持(默认需被提及才会响应)
话题(Threads) 支持(加入后会持续回复)
富文本 Markdown 会转换为 Tlon 的原生格式
图片 入站下载,出站上传
回应(Reactions) 仅可通过内置技能
投票 不支持
原生命令 默认仅所有者可用

故障排查

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

常见故障:

  • DM 被忽略:发送者不在 dmAllowlist 中,且未为审批流程配置 ownerShip。
  • 群组消息被忽略:频道未被发现或固定,或者发送者未通过授权,且没有 ownerShip 来排队审批。
  • 连接错误:检查 ship URL 是否可访问;对于本地 ship,请设置 network.dangerouslyAllowPrivateNetwork。
  • 认证错误:登录验证码会轮换——请从你的 ship 复制当前验证码。

配置参考

完整配置:配置

键 含义
channels.tlon.enabled 启用/禁用频道启动。
channels.tlon.ship 机器人的 Urbit 飞船名称(例如 ~sampel-palnet)。
channels.tlon.url 飞船 URL(例如 https://sampel-palnet.tlon.network)。
channels.tlon.code 飞船登录代码。
channels.tlon.network.dangerouslyAllowPrivateNetwork 允许 localhost/LAN 飞船 URL(SSRF 选择加入)。
channels.tlon.ownerShip 所有者飞船:始终授权,并接收审批请求。
channels.tlon.dmAllowlist 允许私聊的飞船(为空 = 除所有者外无其他飞船)。
channels.tlon.autoAcceptDmInvites 自动接受来自 dmAllowlist 中飞船的私聊。
channels.tlon.autoAcceptGroupInvites 自动接受来自 groupInviteAllowlist 的群组邀请。
channels.tlon.groupInviteAllowlist 其群组邀请会被自动接受的飞船。
channels.tlon.autoDiscoverChannels 自动发现已加入的群组频道(默认:false)。
channels.tlon.implicitMentions.threadParticipation 允许已参与线程的后续消息绕过提及限制。
channels.tlon.requireMentionInBotThreads 仅在该账户飞船创建的根消息所在的线程中覆盖提及限制;省略时保留现有行为。
channels.tlon.groupChannels 手动固定的频道嵌套。
channels.tlon.defaultAuthorizedShips 对所有频道授权的飞船(在没有规则匹配时使用)。
channels.tlon.authorization.channelRules 每个频道嵌套的授权模式、允许列表,以及可选的 requireMentionInBotThreads 覆盖。
channels.tlon.showModelSignature 在回复末尾追加 _[Generated by <model>]_。
channels.tlon.responsePrefix 自动回复前缀:字面量、"auto" 或模板(如 "[{model}]");账户级覆盖优先,"" 表示禁用。
channels.tlon.accounts.<id> 额外的命名账户(多飞船配置)。

说明

  • 群组回复需要 @ 提及(例如 ~your-bot-ship),除非线程参与或机器人拥有的线程策略允许。
  • 线程回复会落在原线程中;机器人还会将线程上下文的最后 10 条消息前置给代理。
  • 富文本(粗体、斜体、代码、标题、列表)会转换为 Tlon 的原生格式。
  • 发送一条要求频道摘要的入站消息(例如“总结这个频道”)会触发内置的历史摘要,而不是正常的回复流程。
  • 频道概览 — 所有支持的频道
  • 配对 — 为声明了该功能的频道提供 DM 身份验证;Tlon 不属于此类,而是使用上述 dmAllowlist 加 ownerShip 审批流程
  • 群组 — 群聊行为和提及限制
  • 频道路由 — 消息的会话路由
  • 安全 — 访问模型和加固

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw