IRC | Docs | OpenClaw

當你想讓 OpenClaw 出現在傳統頻道（#room）和私訊中時，使用 IRC。 IRC 是一個擴充外掛，但在主設定的 channels.irc 下進行設定。

快速開始

在 ~/.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

安全預設值

channels.irc.dmPolicy 預設為 "pairing"。
channels.irc.groupPolicy 預設為 "allowlist"。
使用 groupPolicy="allowlist" 時，設定 channels.irc.groups 來定義允許的頻道。
除非你刻意接受明文傳輸，否則使用 TLS（channels.irc.tls=true）。

存取控制

IRC 頻道有兩道獨立的「閘門」：

頻道存取（groupPolicy + groups）：機器人是否接受來自某頻道的訊息。
發送者存取（groupAllowFrom / 按頻道的 groups["#channel"].allowFrom）：誰可以在該頻道中觸發機器人。

設定鍵：

私訊許可清單（私訊發送者存取）：channels.irc.allowFrom
群組發送者許可清單（頻道發送者存取）：channels.irc.groupAllowFrom
按頻道控制（頻道 + 發送者 + 提及規則）：channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" 允許未設定的頻道（仍預設需要提及）

許可清單項目應使用穩定的發送者身分（nick!user@host）。裸暱稱匹配是可變的，只在 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: ["*"] },
      },
    },
  },
}

回覆觸發（提及）

即使頻道被允許（透過 groupPolicy + groups）且發送者被允許，OpenClaw 在群組上下文中預設仍 需要提及。

這表示你可能會在日誌中看到 drop channel ... (missing-mention) 除非訊息包含匹配機器人的提及模式。

若要讓機器人在 IRC 頻道中 不需要提及 就回覆，請停用該頻道的提及過濾：

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

或允許所有 IRC 頻道（無按頻道許可清單）且不需要提及就回覆：

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

安全注意事項（建議用於公開頻道）

如果你在公開頻道中允許 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 鍵應對 IRC 發送者身分值使用 id: 前綴：id:eigen 或 id:[email protected] 以取得更強的匹配。
舊版無前綴的鍵仍可接受，僅作為 id: 匹配。
第一個匹配的發送者政策生效；"*" 是萬用字元備援。

如需更多關於群組存取與提及過濾（以及它們如何互動）的資訊，請見：/channels/groups。

NickServ

連接後向 NickServ 認證：

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

連接時選用的一次性註冊：

{
  "channels": {
    "irc": {
      "nickserv": {
        "register": true,
        "registerEmail": "[email protected]"
      }
    }
  }
}

暱稱註冊完成後請停用 register，避免重複嘗試 REGISTER。

環境變數

預設帳號支援：

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS（逗號分隔）
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

疑難排解

如果機器人連接成功但從不在頻道中回覆，請確認 channels.irc.groups 和提及過濾是否在丟棄訊息（missing-mention）。如果你希望它不需要被提及就回覆，請為該頻道設定 requireMention:false。
如果登入失敗，請確認暱稱可用性和伺服器密碼。
如果 TLS 在自訂網路上失敗，請確認主機/埠和憑證設定。