IRC

وقتی می‌خواهید OpenClaw را در کانال‌های کلاسیک (#room) و پیام‌های مستقیم داشته باشید، از IRC استفاده کنید. Plugin رسمی IRC را نصب کنید، سپس آن را در channels.irc پیکربندی کنید.

شروع سریع

1. Plugin را نصب کنید:

openclaw plugins install @openclaw/irc

2. حداقل میزبان، نام مستعار و کانال‌هایی را که باید در ~/.openclaw/openclaw.json به آن‌ها بپیوندد تنظیم کنید:

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

3. Gateway را راه‌اندازی یا بازراه‌اندازی کنید:

openclaw gateway run

برای هماهنگی ربات‌ها، سرور IRC خصوصی را ترجیح دهید. اگر عمداً از یک شبکه عمومی IRC استفاده می‌کنید، گزینه‌های رایج شامل Libera.Chat،‏ OFTC و Snoonet هستند. برای ترافیک کانال پشتی ربات یا ازدحام، از کانال‌های عمومی قابل پیش‌بینی پرهیز کنید.

دوام ورودی

OpenClaw هر PRIVMSG پذیرفته‌شده IRC را پیش از بررسی‌های عادی سیاست و ارسال به عامل، در صف ورودی پایدار خود می‌نویسد. پیام‌های در انتظار یا قابل تلاش مجدد پس از بازراه‌اندازی Gateway باقی می‌مانند و برای هر کانال یا طرف پیام مستقیم همچنان به‌صورت سریالی پردازش می‌شوند.

IRC شناسه تحویل قابل بازپخش ارائه نمی‌کند و پیام‌هایی را که سرویس‌گیرنده هنگام قطع اتصال از دست داده است دوباره ارسال نمی‌کند. بنابراین OpenClaw یک شناسه محلی اختصاص می‌دهد که فقط در اتصال TCP فعلی پایدار است. صف از بازه محلی میان پذیرش تا ارسال محافظت می‌کند؛ نمی‌تواند پیامی را که هرگز به OpenClaw نرسیده است بازیابی کند یا ارسال مجدد سرور را در اتصال‌های مختلف تکراری‌زدایی کند.

تنظیمات اتصال

پیش‌فرض‌های امنیتی

• IRC از سوکت‌های خام TCP/TLS خارج از مسیریابی پراکسی جلوی مدیریت‌شده توسط اپراتور OpenClaw استفاده می‌کند. در استقرارهایی که لازم است تمام ترافیک خروجی از آن پراکسی جلو عبور کند، مگر اینکه خروجی مستقیم IRC صراحتاً تأیید شده باشد، channels.irc.enabled=false را تنظیم کنید.
• channels.irc.dmPolicy به‌طور پیش‌فرض "pairing" است: فرستندگان ناشناس پیام مستقیم یک کد جفت‌سازی دریافت می‌کنند که با openclaw pairing approve irc <code> تأیید می‌کنید.
• channels.irc.groupPolicy به‌طور پیش‌فرض "allowlist" است.
• با groupPolicy="allowlist"، برای تعریف کانال‌های مجاز channels.irc.groups را تنظیم کنید.
• مگر اینکه عمداً انتقال متن ساده را بپذیرید، از TLS (channels.irc.tls=true) استفاده کنید.

کنترل دسترسی

برای کانال‌های IRC دو «دروازه» جداگانه وجود دارد:

1. دسترسی کانال (groupPolicy + groups): آیا ربات اصولاً پیام‌های یک کانال را می‌پذیرد یا نه.
2. دسترسی فرستنده (groupAllowFrom / ‏groups["#channel"].allowFrom برای هر کانال): چه کسی مجاز است ربات را در آن کانال فعال کند.

کلیدهای پیکربندی:

• فهرست مجاز پیام مستقیم (دسترسی فرستنده پیام مستقیم): channels.irc.allowFrom
• فهرست مجاز فرستندگان گروه (دسترسی فرستنده کانال): channels.irc.groupAllowFrom
• کنترل‌های هر کانال (قواعد کانال، فرستنده و اشاره): channels.irc.groups["#channel"] با requireMention،‏ allowFrom،‏ enabled،‏ tools،‏ toolsBySender،‏ skills و systemPrompt
• 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

مثال (اجازه دادن به همه افراد در #openclaw برای صحبت با ربات):

{  channels: {    irc: {      groupPolicy: "allowlist",      groups: {        "#openclaw": { allowFrom: ["*"] },      },    },  },}

فعال‌سازی پاسخ (اشاره‌ها)

حتی اگر کانالی مجاز باشد (از طریق groupPolicy + groups) و فرستنده نیز مجاز باشد، OpenClaw در زمینه‌های گروهی به‌طور پیش‌فرض پاسخ را مشروط به اشاره می‌کند. وقتی پیام شامل نام مستعار متصل ربات باشد یا با الگوهای اشاره پیکربندی‌شده مطابقت داشته باشد، ربات اشاره‌شده محسوب می‌شود.

یعنی ممکن است گزارش‌هایی مانند drop channel … (missing-mention) ببینید، مگر اینکه پیام شامل الگوی اشاره‌ای باشد که با ربات مطابقت دارد.

برای اینکه ربات در یک کانال IRC بدون نیاز به اشاره پاسخ دهد، شرط اشاره را برای آن کانال غیرفعال کنید:

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

یا برای مجاز کردن همه کانال‌های IRC (بدون فهرست مجاز برای هر کانال) و همچنان پاسخ دادن بدون اشاره:

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

نکته امنیتی (توصیه‌شده برای کانال‌های عمومی)

اگر allowFrom: ["*"] را در یک کانال عمومی مجاز کنید، هر کسی می‌تواند به ربات دستور بدهد. برای کاهش خطر، ابزارهای آن کانال را محدود کنید.

ابزارهای یکسان برای همه افراد کانال

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

ابزارهای متفاوت برای هر فرستنده (مالک قدرت بیشتری دارد)

از toolsBySender استفاده کنید تا سیاست سخت‌گیرانه‌تری برای "*" و سیاست آسان‌گیرانه‌تری برای نام مستعار خود اعمال کنید:

{  channels: {    irc: {      groups: {        "#openclaw": {          allowFrom: ["*"],          toolsBySender: {            "*": {              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],            },            "id:alice": {              deny: ["gateway", "nodes", "cron"],            },          },        },      },    },  },}

نکته‌ها:

• کلیدهای toolsBySender باید از پیشوندهای صریح (channel:،‏ id:،‏ e164:،‏ username:،‏ name:) استفاده کنند. برای IRC، از id: همراه با مقدار هویت فرستنده استفاده کنید: برای تطبیق قوی‌تر، id:alice یا id:alice!~alice@203.0.113.7.
• کلیدهای قدیمی بدون پیشوند همچنان پذیرفته می‌شوند، فقط به‌عنوان id: تطبیق داده می‌شوند و هشدار منسوخ‌شدن صادر می‌کنند.
• نخستین سیاست فرستنده منطبق اعمال می‌شود؛ "*" حالت جایگزین عام است.

برای اطلاعات بیشتر درباره تفاوت دسترسی گروه با شرط اشاره (و نحوه تعامل آن‌ها)، به /کانال‌ها/گروه‌ها مراجعه کنید.

NickServ

برای شناسایی نزد NickServ پس از اتصال:

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

هرگاه گذرواژه‌ای تنظیم شده باشد، شناسایی NickServ به‌طور پیش‌فرض اجرا می‌شود (فقط برای انصراف لازم است enabled برابر false باشد). مقدار پیش‌فرض service برابر NickServ است؛ passwordFile جایگزینی برای password درون‌خطی است.

ثبت اختیاری و یک‌باره هنگام اتصال (register: true به registerEmail نیاز دارد):

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

پس از ثبت نام مستعار، 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) بررسی کنید. اگر می‌خواهید بدون پینگ پاسخ دهد، برای کانال requireMention:false را تنظیم کنید.
• اگر ورود ناموفق است، در دسترس بودن نام مستعار و گذرواژه سرور را بررسی کنید.
• اگر TLS در یک شبکه سفارشی ناموفق است، میزبان/درگاه و تنظیمات گواهی را بررسی کنید.

مرتبط

• نمای کلی کانال‌ها — همه کانال‌های پشتیبانی‌شده
• جفت‌سازی — احراز هویت پیام مستقیم و جریان جفت‌سازی
• گروه‌ها — رفتار گفت‌وگوی گروهی و شرط اشاره
• مسیریابی کانال — مسیریابی نشست برای پیام‌ها
• امنیت — مدل دسترسی و مقاوم‌سازی