Tlon
Tlon 是一个基于 Urbit 构建的去中心化消息应用。OpenClaw 连接到你的 Urbit ship,并响应私信和群聊消息。群聊回复默认需要 @ 提及,并在此基础上叠加了授权规则和所有者审批流程。
状态:内置插件。支持私信、群聊提及、话题、富文本、图片上传/下载以及所有者审批系统。不支持表情回应和投票。
内置插件¶
Tlon 已随当前 OpenClaw 版本捆绑发布;打包构建无需单独安装。
在较旧的构建或未包含它的自定义安装中,可从 npm 安装:
使用裸包名跟踪当前发布标签。仅在进行可复现安装时才固定版本(@openclaw/tlon@x.y.z)。
从本地检出安装:
详情:插件
配置¶
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):
群组授权默认按频道设为 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 提供的规则。对于此选项,已保存的频道规则只有在设置布尔值时才覆盖文件中的值;旧的仅访问规则继承文件中的值。发送者授权仍然生效,且此选项不会改变频道顶层帖子或私信。
所有者与审批系统¶
所有者 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 邀请(无论此标志如何,所有者始终会被自动接受):
自动接受来自允许列表的群组邀请(默认拒绝:当 autoAcceptGroupInvites: true 且 groupInviteAllowlist 为空时,不接受任何非所有者的邀请):
通过 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) | 仅可通过内置技能 |
| 投票 | 不支持 |
| 原生命令 | 默认仅所有者可用 |
故障排查¶
常见故障:
- 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 的原生格式。
- 发送一条要求频道摘要的入站消息(例如“总结这个频道”)会触发内置的历史摘要,而不是正常的回复流程。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw