English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Developer and self-hosted

IRC

當你想在傳統頻道（#room）和直接訊息中使用 OpenClaw 時，請使用 IRC。 IRC 以內建 Plugin 形式提供，但會在主要設定中的 channels.irc 下設定。

快速開始

  1. 在 ~/.openclaw/openclaw.json 中啟用 IRC 設定。
  2. 至少設定：
{
  channels: {
    irc: {
      enabled: true,
      host: "irc.example.com",
      port: 6697,
      tls: true,
      nick: "openclaw-bot",
      channels: ["#openclaw"],
    },
  },
}

建議使用私有 IRC 伺服器來協調機器人。如果你刻意使用公開 IRC 網路，常見選項包括 Libera.Chat、OFTC 和 Snoonet。避免將可預測的公開頻道用於機器人或群體後端通訊流量。

  1. 啟動/重新啟動 Gateway：
openclaw gateway run

安全預設值

  • IRC 使用 OpenClaw 操作者管理的轉送 Proxy 路由之外的原始 TCP/TLS Socket。在要求所有輸出流量都必須經過該轉送 Proxy 的部署中，除非直接 IRC 輸出已明確核准，否則請設定 channels.irc.enabled=false。
  • channels.irc.dmPolicy 預設為 "pairing"。
  • channels.irc.groupPolicy 預設為 "allowlist"。
  • 使用 groupPolicy="allowlist" 時，請設定 channels.irc.groups 來定義允許的頻道。
  • 除非你刻意接受明文傳輸，否則請使用 TLS（channels.irc.tls=true）。

存取控制

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

  1. 頻道存取（groupPolicy + groups）：機器人是否完全接受來自某個頻道的訊息。
  2. 傳送者存取（groupAllowFrom / 每個頻道的 groups["#channel"].allowFrom）：誰被允許在該頻道內觸發機器人。

設定鍵：

  • DM 允許清單（DM 傳送者存取）：channels.irc.allowFrom
  • 群組傳送者允許清單（頻道傳送者存取）：channels.irc.groupAllowFrom
  • 每個頻道的控制（頻道 + 傳送者 + 提及規則）：channels.irc.groups["#channel"]
  • channels.irc.groupPolicy="open" 允許未設定的頻道（預設仍需提及才會觸發）

允許清單項目應使用穩定的傳送者身分（nick!user@host）。 裸暱稱比對是可變的，且只有在 channels.irc.dangerouslyAllowNameMatching: true 時才會啟用。

常見陷阱：allowFrom 用於 DM，不用於頻道

如果你看到類似以下的記錄：

  • 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 鍵應使用 id: 作為 IRC 傳送者身分值： 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

IRC_HOST 無法從工作區 .env 設定；請參閱工作區 .env 檔案。

疑難排解

  • 如果機器人已連線但從不在頻道中回覆，請驗證 channels.irc.groups，並確認是否因提及閘控而丟棄訊息（missing-mention）。如果你想讓它不需 ping 也能回覆，請為該頻道設定 requireMention:false。
  • 如果登入失敗，請驗證暱稱可用性與伺服器密碼。
  • 如果 TLS 在自訂網路上失敗，請驗證主機/連接埠與憑證設定。

相關