設定 OpenClaw IRC 插件：5 分鐘內完成頻道與私訊連接

雖然現在通訊軟體百家爭鳴，但 IRC 這種經典的頻道通訊方式在開發者圈子裡依然很有生命力。如果你想在 #room 這種傳統頻道或是透過私訊來使用 OpenClaw，這篇指南會幫你快速搞定。

IRC 在 OpenClaw 中是以擴充插件的形式存在，但你直接在主設定檔的 channels.irc 底下就能完成配置。

快速開始 (Quick start)

在 ~/.openclaw/openclaw.json 中啟用 IRC 配置。
至少設定以下項目：

{
  channels: {
    irc: {
      enabled: true,
      host: "irc.libera.chat",
      port: 6697,
      tls: true,
      nick: "openclaw-bot",
      channels: ["#openclaw"],
    },
  },
}

啟動或重啟 Gateway：

openclaw gateway run

安全性預設值 (Security defaults)

channels.irc.dmPolicy 預設為 "pairing"。
channels.irc.groupPolicy 預設為 "allowlist"。
當 groupPolicy="allowlist" 時，請設定 channels.irc.groups 來定義允許進入的頻道。
除非你刻意要使用明文傳輸，否則請務必開啟 TLS (channels.irc.tls=true)。

存取控制 (Access control)

IRC 頻道的存取有兩個獨立的「關卡」：

頻道存取 (groupPolicy + groups)：決定機器人是否接受來自該頻道的任何訊息。
發送者存取 (groupAllowFrom / 每個頻道的 groups["#channel"].allowFrom)：決定誰可以在該頻道內觸發機器人。

相關設定鍵：

DM 白名單（私訊發送者存取）：channels.irc.allowFrom
群組發送者白名單（頻道發送者存取）：channels.irc.groupAllowFrom
個別頻道控制（頻道 + 發送者 + 提及規則）：channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" 允許未經設定的頻道（預設仍受提及機制過濾）

白名單條目建議使用穩定的發送者身份格式 (nick!user@host)。單純的暱稱 (nick) 匹配很容易變動，只有在 channels.irc.dangerouslyAllowNameMatching: true 時才會啟用。

常見坑點：`allowFrom` 是給私訊用的，不是頻道

如果你在日誌中看到類似這樣的內容：

irc: drop group sender alice!ident@host (policy=allowlist)

這代表該發送者未被允許發送群組/頻道訊息。你可以透過以下兩種方式修正：

設定 channels.irc.groupAllowFrom（全域適用於所有頻道），或者
設定個別頻道的發送者白名單：channels.irc.groups["#channel"].allowFrom

範例（允許 #tuirc-dev 頻道中的任何人與機器人對話）：

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": { allowFrom: ["*"] },
      },
    },
  },
}

回覆觸發機制 (提及) (Reply triggering (mentions))

即便頻道和發送者都在允許範圍內，OpenClaw 在群組環境中預設會開啟 mention-gating（提及過濾）。

這意味著除非訊息中包含匹配機器人的提及 (mention) 模式，否則你可能會看到 drop channel … (missing-mention) 這樣的日誌。

如果你想讓機器人在 IRC 頻道中不需要被提及就能回覆，請關閉該頻道的提及限制：

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}

或者你想允許所有 IRC 頻道（不設個別白名單）且同樣不需要提及就能回覆：

{
  channels: {
    irc: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: false, allowFrom: ["*"] },
      },
    },
  },
}

安全性注意事項 (建議用於公開頻道) (Security note (recommended for public channels))

如果你在公開頻道中設定 allowFrom: ["*"]，代表任何人都可以對機器人下指令。為了降低風險，建議限制該頻道可使用的工具。

頻道內所有人共用相同工具限制

{
  channels: {
    irc: {
      groups: {
        "#tuirc-dev": {
          allowFrom: ["*"],
          tools: {
            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
          },
        },
      },
    },
  },
}

根據發送者區分工具權限（給予擁有者更多權力）

使用 toolsBySender 對 "*" 套用嚴格政策，並對你的暱稱套用較寬鬆的政策：

{
  channels: {
    irc: {
      groups: {
        "#tuirc-dev": {
          allowFrom: ["*"],
          toolsBySender: {
            "*": {
              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
            },
            "id:eigen": {
              deny: ["gateway", "nodes", "cron"],
            },
          },
        },
      },
    },
  },
}

注意：

toolsBySender 的鍵值應使用 id: 開頭來表示 IRC 發送者身份：例如 id:eigen 或更精確的 id:eigen!~eigen@174.127.248.171。
舊版沒有前綴的鍵值仍被接受，並會被視為 id: 匹配。
系統會採用第一個匹配到的發送者政策；"*" 則是最後的保底選項。

關於群組存取與提及過濾的詳細互動關係，請參考：/channels/groups。

NickServ 驗證 (NickServ)

要在連線後向 NickServ 進行身份驗證：

{
  channels: {
    irc: {
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "your-nickserv-password",
      },
    },
  },
}

連線時的一次性註冊（可選）：

{
  channels: {
    irc: {
      nickserv: {
        register: true,
        registerEmail: "bot@example.com",
      },
    },
  },
}

暱稱註冊完成後，請關閉 register 以避免重複嘗試註冊。

環境變數 (Environment variables)

預設帳號支援以下環境變數：

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS (以逗號分隔)
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

疑難排解 (Troubleshooting)

如果機器人已連線但在頻道中沒反應，請檢查 channels.irc.groups 設定，並確認是否因為提及過濾 (missing-mention) 導致訊息被丟棄。如果你希望它直接回覆，請將頻道的 requireMention 設為 false。
如果登入失敗，請檢查暱稱是否被佔用或伺服器密碼是否正確。
如果在自建網路上 TLS 連線失敗，請檢查 host/port 以及憑證設定。

Channels Overview — 所有支援的通訊管道
Pairing — 私訊驗證與配對流程
Groups — 群組聊天行為與提及過濾
Channel Routing — 訊息的對話階段路由
Security — 存取模型與安全性強化

想了解更多？試試我們的 AI Setup Assistant。

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。