> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tlon

Tlon 是建構於 Urbit 上的去中心化通訊軟體。OpenClaw 會連線至你的 Urbit ship，並
回覆私訊和群組聊天訊息。群組回覆預設需要 @ 提及，並在此基礎上套用
授權規則和擁有者核准流程。

狀態：隨附外掛。支援私訊、群組提及、討論串、富文字、圖片上傳／下載，以及
擁有者核准系統。不支援表情回應和投票。

## 隨附外掛

目前的 OpenClaw 版本隨附 Tlon；封裝版本不需要另行安裝。

若是未包含此外掛的舊版建置或自訂安裝，請從 npm 安裝：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/tlon
```

使用不含版本的套件名稱以追蹤目前的發行標籤。只有需要可重現安裝時，才固定版本（`@openclaw/tlon@x.y.z`）。

從本機簽出的版本安裝：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install ./path/to/local/tlon-plugin
```

詳細資訊：[外掛](/zh-TW/tools/plugin)

## 設定

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels add --channel tlon --ship ~sampel-palnet --url https://your-ship-host --code lidlut-tabwed-pillex-ridrup
```

或直接編輯設定：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    tlon: {
      enabled: true,
      ship: "~sampel-palnet",
      url: "https://your-ship-host",
      code: "lidlut-tabwed-pillex-ridrup",
      ownerShip: "~your-main-ship", // 建議：你的 ship，永遠具有授權
    },
  },
}
```

直接編輯設定後，請重新啟動閘道。接著私訊機器人，或在群組
頻道中 @ 提及它。

## 傳入訊息的持久性

OpenClaw 會在分派給代理程式前，持久儲存已接受的 Tlon 私訊和群組聊天事件。待處理或可重試的回合可在閘道重新啟動後保留，且每個群組頻道或直接通訊對象的工作仍會依序處理。只要穩定的 Urbit 訊息 ID 所對應的佇列記錄或保留的完成記錄仍存在，也會抑制重新傳送的事件。

從佇列到代理程式的邊界採至少一次傳遞：交接期間發生當機可能會重播某個回合。因此，在可行情況下，會產生外部副作用的代理程式動作應維持等冪性。

## 私有／區域網路 ship

為防範 SSRF，OpenClaw 預設會封鎖私有／內部主機名稱和 IP 範圍。如果你的
ship 在私有網路上執行（localhost、區域網路 IP、內部主機名稱），請明確選擇啟用：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`。
</Note>

## 群組頻道

手動固定頻道，或開啟自動探索：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    tlon: {
      groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
      autoDiscoverChannels: true,
    },
  },
}
```

若設定中未指定 `autoDiscoverChannels`，其預設值為 `false`；設定精靈會將
提示的預設值設為「是」，並明確寫入 `true`。啟用後，OpenClaw 會在啟動時探查已加入的群組，
在接受群組邀請時監看新頻道，並每 2 分鐘重新檢查一次。

## 存取控制

私訊允許清單（空白 = 除非傳送者是 `ownerShip`，否則不允許私訊）：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    tlon: {
      dmAllowlist: ["~zod", "~nec"],
    },
  },
}
```

每個頻道的群組授權預設為 `restricted`。設定 `defaultAuthorizedShips` 作為
基準，並依各頻道 nest 覆寫：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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` 事實，因此這些旗標在此不會生效。

## 擁有者和核准系統

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    tlon: {
      ownerShip: "~your-main-ship",
    },
  },
}
```

擁有者 ship 在所有位置都具有授權：私訊邀請一律自動接受、群組邀請一律
自動接受，且頻道訊息一律通過授權。擁有者不需要列在
`dmAllowlist`、`defaultAuthorizedShips` 或 `groupInviteAllowlist` 中。

設定 `ownerShip` 後，未授權的要求不會只是遭到捨棄，而是會排入待處理
核准佇列，並私訊擁有者：

* 來自未列於 `dmAllowlist` 中之 ship 的私訊要求
* 傳送者未通過授權的頻道提及
* 來自未列於 `groupInviteAllowlist` 中之 ship 的群組邀請（當自動接受關閉，或已開啟但
  邀請者未列於允許清單時）

擁有者可透過私訊回覆來處理要求：

| 擁有者回覆                        | 效果                       |
| ---------------------------- | ------------------------ |
| `approve` / `deny` / `block` | 處理最近一筆待核准要求              |
| `approve <id>` / `deny <id>` | 依 ID 處理特定核准要求            |
| `block`                      | 同時以原生方式封鎖該 ship，使其無法重新連線 |
| `unblock ~ship`              | 解除原生封鎖                   |
| `blocked`                    | 列出目前遭封鎖的 ship            |
| `pending`                    | 列出待處理的核准要求               |

若未設定 `ownerShip`，未授權的私訊和頻道提及只會遭到捨棄並記錄；
不會顯示核准提示。

## 自動接受設定

自動接受來自已列於 `dmAllowlist` 中之 ship 的私訊邀請（無論此旗標為何，
擁有者一律會自動接受）：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    tlon: {
      autoAcceptDmInvites: true,
    },
  },
}
```

自動接受允許清單中 ship 的群組邀請（失敗時採封閉策略：當 `autoAcceptGroupInvites: true` 且
`groupInviteAllowlist` 為空白時，不接受任何非擁有者邀請）：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    tlon: {
      autoAcceptGroupInvites: true,
      groupInviteAllowlist: ["~zod"],
    },
  },
}
```

## 透過 Urbit 設定儲存區熱重新載入

上述大多數設定（`dmAllowlist`、`groupInviteAllowlist`、`groupChannels`、
`defaultAuthorizedShips`、`autoDiscoverChannels`、`autoAcceptDmInvites`、
`autoAcceptGroupInvites`、`ownerShip`、`showModelSignature`）會在第一次執行時鏡像到 ship 的
`%settings` 代理程式（desk `moltbot`、bucket `tlon`），之後再從該處即時讀取，
因此透過 Landscape 用戶端或隨附 Skill 的設定命令所做的變更，不必重新啟動
閘道即可套用。`channelRules` 和待處理的核准要求也會以 JSON 格式持久儲存於該處。對於
從未寫入設定儲存區的值，檔案設定仍是事實來源。

## 傳遞目標（命令列介面／排程）

搭配 `openclaw message send` 或排程傳遞使用：

* 私訊：`~sampel-palnet` 或 `dm/~sampel-palnet`
* 群組：`chat/~host-ship/channel` 或 `group:~host-ship/channel`

## 隨附 Skill

此外掛隨附 [`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)，這是一個用於
直接執行 Urbit 操作的命令列介面，安裝外掛後即可自動使用：

* **動態**：提及、回覆、未讀項目
* **頻道**：列出、建立、重新命名
* **聯絡人**：列出／取得／更新個人檔案
* **群組**：建立、加入、邀請／申請流程、角色
* **鉤子**：管理頻道鉤子
* **訊息**：歷史記錄、搜尋
* **私訊**：傳送、回應、接受／拒絕
* **貼文**：回應、刪除
* **筆記本**：發佈至日記頻道
* **設定**：透過上述設定儲存區熱重新載入外掛設定

## 功能

| 功能    | 狀態                             |
| ----- | ------------------------------ |
| 私訊    | 支援                             |
| 群組／頻道 | 支援（預設須提及）                      |
| 討論串   | 支援（加入後會持續回覆）                   |
| 富文字   | Markdown 轉換為 Tlon 的原生格式        |
| 圖片    | 下載傳入圖片，上傳傳出圖片                  |
| 表情回應  | 僅能透過[隨附 Skill](#bundled-skill) |
| 投票    | 不支援                            |
| 原生命令  | 預設僅限擁有者                        |

## 疑難排解

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
```

常見失敗：

* **私訊遭忽略**：傳送者不在 `dmAllowlist` 中，且未設定用於核准流程的 `ownerShip`。
* **群組訊息遭忽略**：頻道未被探索／固定，或傳送者未通過授權，且沒有
  `ownerShip` 可將核准要求排入佇列。
* **連線錯誤**：檢查 ship URL 是否可連線；若是本機 ship，請設定
  `network.dangerouslyAllowPrivateNetwork`。
* **驗證錯誤**：登入碼會輪替，請從你的 ship 複製目前的代碼。

## 設定參考

完整設定：[設定](/zh-TW/gateway/configuration)

| 鍵                                                      | 意義                                                 |
| ------------------------------------------------------ | -------------------------------------------------- |
| `channels.tlon.enabled`                                | 啟用／停用頻道啟動。                                         |
| `channels.tlon.ship`                                   | 機器人的 Urbit ship 名稱（例如 `~sampel-palnet`）。           |
| `channels.tlon.url`                                    | Ship URL（例如 `https://sampel-palnet.tlon.network`）。 |
| `channels.tlon.code`                                   | Ship 登入碼。                                          |
| `channels.tlon.network.dangerouslyAllowPrivateNetwork` | 允許 localhost／區域網路 ship URL（選擇啟用 SSRF）。             |
| `channels.tlon.ownerShip`                              | 擁有者 ship：永遠具有授權，並接收核准要求。                           |
| `channels.tlon.dmAllowlist`                            | 允許私訊的 ship（空白 = 除擁有者外皆不允許）。                        |
| `channels.tlon.autoAcceptDmInvites`                    | 自動接受來自 `dmAllowlist` 中 ship 的私訊。                   |
| `channels.tlon.autoAcceptGroupInvites`                 | 自動接受來自 `groupInviteAllowlist` 的群組邀請。               |
| `channels.tlon.groupInviteAllowlist`                   | 群組邀請會被自動接受的 ship。                                  |
| `channels.tlon.autoDiscoverChannels`                   | 自動探索已加入的群組頻道（預設：`false`）。                          |
| `channels.tlon.implicitMentions.threadParticipation`   | 允許已參與討論串的後續訊息略過提及限制。                               |
| `channels.tlon.groupChannels`                          | 手動固定的頻道 nest。                                      |
| `channels.tlon.defaultAuthorizedShips`                 | 所有頻道皆授權的 ship（沒有符合規則時使用）。                          |
| `channels.tlon.authorization.channelRules`             | 各頻道 nest 的驗證模式與允許清單。                               |
| `channels.tlon.showModelSignature`                     | 將 `_[Generated by <model>]_` 附加至回覆。                |
| `channels.tlon.responsePrefix`                         | 加在傳出回覆之前的靜態前置字串。                                   |
| `channels.tlon.accounts.<id>`                          | 其他具名帳號（多 ship 設定）。                                 |

## 備註

* 群組回覆需要 @ 提及（例如 `~your-bot-ship`），除非機器人已加入該討論串。
* 討論串回覆會送至討論串內；系統也會將討論串內容的最後 10 則訊息附加在前面，
  提供給代理程式。
* 富文字（粗體、斜體、程式碼、標題、清單）會轉換為 Tlon 的原生格式。
* 傳送要求頻道摘要的傳入訊息（例如「摘要此
  頻道」），會觸發內建的歷史記錄摘要功能，而非一般回覆流程。

## 相關內容

* [頻道概覽](/zh-TW/channels) — 所有支援的頻道
* [配對](/zh-TW/channels/pairing) — 私訊驗證與配對流程
* [群組](/zh-TW/channels/groups) — 群組聊天行為與提及門檻
* [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
* [安全性](/zh-TW/gateway/security) — 存取模型與強化措施