OpenClaw Tlon/Urbit 渠道插件私网 Ship 接入、群组授权与 Owner 审批流完整指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文基于 OpenClaw 仓库中的 Tlon 渠道文档 与 extensions/tlon 插件源码完整覆盖 Tlon/Urbit 渠道的安装、登录认证、私网 SSRF 放行、群组发现与授权、Owner 审批系统与设置热重载的全部配置细节并结合插件源码说明审批队列、SSRF 策略和设置存储的底层实现机制帮助你在本地或私有网络中稳定运行一个带访问控制的 Tlon 机器人。1. Tlon 渠道是什么能力边界在哪Tlon 是构建在 Urbit 上的去中心化即时通讯应用。OpenClaw 通过 Tlon 渠道插件连接到你的 Urbit ship相当于一个去中心化主机实例响应私聊DM和群组频道消息。群聊回复默认要求 mention并在其上叠加了授权规则和 Owner 审批流。能力现状来自 docs/channels/tlon.md 的能力矩阵功能状态私聊DM支持群组/频道支持默认需要 mention 才回复线程Threads支持机器人一旦参与过该线程后续消息免 mention 继续回复富文本Markdown 转换为 Tlon 原生格式粗体、斜体、代码、标题、列表图片入站下载、出站上传表情回应Reactions仅可通过捆绑的 skill 操作投票Polls不支持原生命令默认仅 Owner 可用插件为随版本捆绑发布当前 OpenClaw 的打包版本内置 Tlon无需单独安装。在较旧版本或自定义安装中可通过 npm 安装openclaw plugins install openclaw/tlon建议使用裸包名以跟踪当前发布标签只有需要可复现安装时才固定版本openclaw/tlonx.y.z。从本地检出目录安装openclaw plugins install ./path/to/local/tlon-plugin从插件清单 openclaw.plugin.json 可以看到插件声明了channels: [tlon]、configRepair的 doctor 契约并捆绑了tloncorp/tlon-skill这个技能包。2. 初始接入channels add 与配置文件两种方式最快的接入方式是 CLI 向导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, // 推荐你的 ship始终被授权 }, }, }登录 code 的获取与轮换code就是 ship 的 web 登录 code在 ship 的 dojo 里执行code打印当前值。code 会轮换一旦认证开始失败就重新读取。认证链路源码佐证从 extensions/tlon/src/urbit/auth.ts 可以看到认证实现就是向POST /~/login提交passwordcode表单成功响应后从Set-Cookie头取出会话 cookie拿不到 cookie 会抛出missing_cookie类型的UrbitAuthError。请求默认 15 秒超时、最多 3 次重定向并携带tlon-urbit-login审计上下文——这正是文档中认证失败就重新code的底层原因code 过期时登录请求会直接失败。配置修改遵循 Gateway 的 hot reload 机制。改完配置后执行openclaw channels status --probe验证Gateway 离线时先启动然后 DM 机器人或在群里 它。3. 私网 / 局域网 ShipSSRF 防护的显式放行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 保护。注意旧的扁平键channels.tlon.allowPrivateNetwork已废弃openclaw doctor --fix会自动把它迁移到channels.tlon.network.dangerouslyAllowPrivateNetwork插件通过 doctor.ts 注册的 legacy config 规则实现该迁移。源码层面的双重校验extensions/tlon/src/urbit/base-url.ts 中validateUrbitBaseUrl会拒绝非 http/https 协议、URL 内嵌凭据、把 base URL 归一化为纯 origin防止夹带路径/查询参数再调用isBlockedUrbitHostname→ 插件 SDK 的isBlockedHostnameOrIp判断主机名是否在拦截名单内拦截判断发生在urbitFetch层dangerouslyAllowPrivateNetwork: true最终转化为ssrfPolicy: { allowPrivateNetwork: true }透传给每次请求——extensions/tlon/src/urbit/auth.ssrf.test.ts 等测试专门验证了默认拦截私网、开启后放行的行为边界。4. 群组频道手动固定与自动发现两种管理群组频道的方式可并用{ channels: { tlon: { groupChannels: [chat/~host-ship/general, chat/~host-ship/support], autoDiscoverChannels: true, }, }, }groupChannels是手动固定的频道 nest 列表格式为chat/~host-ship/channelautoDiscoverChannels在配置文件未显式设置时默认为false而 setup 向导会把该提示的默认回答设为 yes 并显式写入true。开启后插件在启动时 scry 已加入的群组、监听随群组邀请被接受而新出现的频道并且每 2 分钟复查一次。频道 nest 的解析规则可以在 extensions/tlon/src/targets.ts 中确认parseChannelNest用正则^chat\/([^/])\/([^/])$提取 host ship 与频道名ship 名会自动补~前缀归一化。5. 访问控制DM 白名单与逐频道授权DM 白名单空 除ownerShip外任何 DM 都不允许{ 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, }, }, }, }, }, }源码级解析逻辑extensions/tlon/src/monitor/authorization.ts 的resolveChannelAuthorization实现了三级回退——先取设置存储settings store中的channelRules没有再取文件配置中的channelRulesmode未匹配规则时回落到restricted即文档说的默认 restrictedallowedShips未指定时回落到defaultAuthorizedShips同样是设置存储优先、文件配置兜底的顺序。线程续答与 mention 门控机器人一旦在某个线程里回复过后续该线程内的消息就无需再次 mention 也会继续响应。想强制每次显式 mention 时{ channels: { tlon: { implicitMentions: { threadParticipation: false }, }, }, }多账号场景用channels.tlon.accounts.id.implicitMentions覆盖。另外 Tlon 目前不产生replyToBot/quotedBot事实这两个 flag 在 Tlon 渠道上不生效。6. Owner 与审批系统配置ownerShip{ channels: { tlon: { ownerShip: ~your-main-ship, }, }, }Owner ship 处处被授权DM 邀请总是自动接受、群组邀请总是自动接受、频道消息总是通过授权——它不需要出现在dmAllowlist、defaultAuthorizedShips或groupInviteAllowlist里。关键在于设置ownerShip后未授权请求不会被直接丢弃而是排队等待审批并 DM 通知 Owner。会触发待审批请求的场景来自不在dmAllowlist中的 ship 的 DM 请求在发送者未通过授权的频道中的 mention来自不在groupInviteAllowlist中的 ship 的群组邀请在自动接受关闭、或开启但邀请人不在白名单时。Owner 在 DM 中回复即可处理请求Owner 回复效果approve/deny/block作用于最近一条待审批请求approve id/deny id按 id 处理指定请求block同时以 Tlon 原生方式封禁该 ship使其无法重连unblock ~ship解除原生封禁blocked列出当前被封禁的 shippending列出现有待审批请求审批机制源码实现extensions/tlon/src/monitor/approval.ts待审批对象带唯一 id格式为{type}-{timestamp}-{shortHash}generateApprovalIdL38-L42type为dm/channel/group三类parseApprovalResponseL113-L126用正则^(approve|deny|block)(?:\s(.))?$解析 Owner 回复支持带 id 与不带 id取最近一条见findPendingApprovalL140-L149parseAdminCommandL209-L229解析unblock ~ship、blocked、pending三类管理命令ship 名正则限定为~[\w-]每个PendingApproval除了 id、类型、请求方 ship 外还保留originalMessage完整上下文消息 id、文本、内容、时间戳、父消息 id、是否线程回复用于审批通过后的消息补发。未配置ownerShip时未授权 DM 和频道 mention 只会被丢弃并记日志没有任何审批提示。7. 自动接受Auto-accept策略自动接受 DM 邀请仅针对已在dmAllowlist中的 shipOwner 无论该 flag 如何都总是自动接受{ channels: { tlon: { autoAcceptDmInvites: true, }, }, }自动接受群组邀请fails closed 语义autoAcceptGroupInvites: true且groupInviteAllowlist为空时任何非 Owner 邀请都不会被接受{ channels: { tlon: { autoAcceptGroupInvites: true, groupInviteAllowlist: [~zod], }, }, }8. 入站持久化与投递语义这部分常被忽略但对生产部署很重要来自 docs/channels/tlon.md 的 Inbound durability 一节OpenClaw 在把已接受的 Tlon DM/群事件派发给 agent 之前先持久化pending 或可重试的轮次能扛过 Gateway 重启工作按群组频道或DM 对端为单位串行处理稳定的 Urbit 消息 id 会在队列记录或保留的完成记录存在时抑制重复投递的事件从队列到 agent 的边界是at-least-once投递handoff 期间崩溃可能重放一个轮次因此产生外部副作用的 agent 动作应尽量保持幂等。9. 通过 Urbit 设置存储实现配置热重载上面大部分设置dmAllowlist、groupInviteAllowlist、groupChannels、defaultAuthorizedShips、autoDiscoverChannels、autoAcceptDmInvites、autoAcceptGroupInvites、ownerShip、showModelSignature首次运行时会被镜像写入 ship 的%settingsagentdeskmoltbotbuckettlon之后从那里实时读取——所以经由 Landscape 客户端或捆绑 skill 的设置命令所做的修改无需重启 Gateway即生效。channelRules和待审批列表也作为 JSON 持久化在该处文件配置对从未写入设置存储的值仍是唯一事实来源。实现细节extensions/tlon/src/settings.ts初始加载通过scry(/settings/all.json)响应形状为{ all: { [desk]: { [bucket]: { [key]: value } } } }L332-L349变更监听通过 SSE 订阅settings应用的/desk/moltbot路径处理put-entry/del-entry两类事件parseSettingsEventL200-L232每次命中后增量更新本地状态并通知监听器由于 Urbit settings store 不支持嵌套对象channelRules和pendingApprovals以 JSON 字符串形式存储读回时做容错解析与逐条结构校验parseChannelRules/parsePendingApprovalsL70-L95、L162-L195设置 desk 尚不存在时load()静默回退为空设置——插件不会因此启动失败。10. 出站投递目标CLI / cron配合openclaw message send或 cron 投递使用DM~sampel-palnet或dm/~sampel-palnet群组chat/~host-ship/channel或group:~host-ship/channelextensions/tlon/src/targets.ts 中的parseTlonTarget实际比文档列出的更多还支持room:前缀、group:~host/channel两段式简写自动拼成chat/~host/channelnest、可选的tlon:渠道前缀ship 名缺~前缀时自动补齐。出错时提示的标准写法为dm/~sampel-palnet | ~sampel-palnet | chat/~host-ship/channel | group:~host-ship/channel。11. 图片媒体限制mediaMaxMbchannels.tlon.mediaMaxMb以 MiB 为单位限制每张入站图片的下载和出站图片的加载。多账号下可用accounts.id.mediaMaxMb覆盖未设置时依次回落渠道根、再回落agents.defaults.mediaMaxMb。图片下载与上传存在 6 MiB 的硬上限。行为差异配置了 cap 时尺寸检查失败或下载失败会让发送失败而不是内嵌一个未经检查的 URL有界下载成功后若上传失败仍可使用原始 URL未配置 cap 时即使图片无法在限制内下载仍保留原有的直接发链接回退。12. 捆绑 Skilltlon-skill插件捆绑了tloncorp/tlon-skill一个用于直接 Urbit 操作的 CLI安装插件后即可自动使用能力覆盖Activitymentions、replies、unreadsChannels列出、创建、重命名Contacts列出/获取/更新 profileGroups创建、加入、邀请/请求流程、rolesHooks管理频道 hooksMessages历史、搜索DMs发送、react、接受/拒绝Postsreact、删除Notebook向 diary 频道发帖Settings通过上文第 9 节的设置存储热重载插件配置13. 完整配置参考表键含义channels.tlon.enabled启用/禁用渠道启动channels.tlon.ship机器人的 Urbit ship 名如~sampel-palnetchannels.tlon.urlShip URL如https://sampel-palnet.tlon.networkchannels.tlon.codeShip 登录 codechannels.tlon.network.dangerouslyAllowPrivateNetwork允许 localhost/LAN ship URLSSRF 显式放行channels.tlon.ownerShipOwner ship处处被授权接收审批请求channels.tlon.dmAllowlist允许 DM 的 ship空 除 Owner 外都不允许channels.tlon.autoAcceptDmInvites自动接受dmAllowlist中 ship 的 DMchannels.tlon.autoAcceptGroupInvites自动接受来自groupInviteAllowlist的群组邀请channels.tlon.groupInviteAllowlist群组邀请可被自动接受的 ship 列表channels.tlon.autoDiscoverChannels自动发现已加入的群组频道默认falsechannels.tlon.implicitMentions.threadParticipation允许已参与线程的后续消息绕过 mention 门控channels.tlon.groupChannels手动固定的频道 nest 列表channels.tlon.defaultAuthorizedShips所有频道默认授权的 ship无规则匹配时使用channels.tlon.authorization.channelRules逐频道 nest 的授权模式 白名单channels.tlon.showModelSignature在回复末尾追加_[Generated by model]_channels.tlon.responsePrefix自动回复前缀字面量、auto或[{model}]模板账号覆盖优先禁用channels.tlon.accounts.id额外命名账号多 ship 部署完整的 Zod schema 定义见 extensions/tlon/src/config-schema.ts其中network为 strict 对象只接受dangerouslyAllowPrivateNetwork一个键顶层还有文档表格未列出的historyLimit整数 ≥ 0、name、configWrites等字段。14. 故障排查常用诊断命令openclaw status openclaw gateway status openclaw logs --follow openclaw doctor常见故障与定位方向DM 被忽略发送者不在dmAllowlist且未配置ownerShip没有审批流兜底群消息被忽略频道未被发现/固定或发送者未通过授权且无ownerShip排队审批连接错误确认 ship URL 可达本地 ship 需设置network.dangerouslyAllowPrivateNetwork认证错误登录 code 会轮换——回 ship 重新code获取当前值旧配置迁移出现allowPrivateNetwork扁平键时跑openclaw doctor --fix。15. 行为备注与相关文档其他值得注意的行为约定群回复需要 mention如~your-bot-ship除非机器人已加入该线程线程回复落在线程内agent 还会拿到线程最近 10 条消息作为上下文前缀富文本粗体、斜体、代码、标题、列表自动转换为 Tlon 原生格式入站消息若请求频道摘要例如 summarize this channel会触发内置的历史摘要流程而非普通回复Tlon 不属于声明 pairing 的渠道——它的 DM 认证用的是dmAllowlistownerShip审批流而不是 Pairing 机制。延伸阅读仓库相对路径渠道总览、群组行为插件机制Gateway 热重载Tlon 插件入口、SSE 客户端、审批测试【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考