اتصال OpenClaw و Hermes به IranRouter
تیم تحریریه ایران روتر۹ مرداد ۱۴۰۵۵ دقیقه مطالعه
اگر با OpenClaw یا Hermes کار میکنید، برای اتصال به IranRouter لازم نیست چیزی در کدتان بازنویسی شود. هر دو ابزار با API سازگار با OpenAI حرف میزنند و IranRouter هم دقیقاً همان API را ارائه میدهد. یعنی تنها دو مقدار عوض میشود: نشانی سرویس و کلید.
در این راهنما از صفر تا اولین پاسخ موفق را با هم میرویم، و بعد سراغ چیزهایی میرویم که معمولاً کسی از قبل نمیگوید: خطاهای رایج، کنترل هزینه و انتخاب مدل.
پیش از شروع، دو چیز لازم دارید
- یک حساب IranRouter با شمارهٔ موبایل ایرانی — ثبتنام با کد پیامکی است و کارت خارجی نمیخواهد.
- یک کلید API که با
ir-شروع میشود. از پنل کاربری، بخش «کلیدها»، یک کلید بسازید.
کلید فقط یک بار کامل نمایش داده میشود. همانجا کپیاش کنید؛ ما فقط اثر انگشتش را نگه میداریم و امکان نمایش دوبارهٔ آن وجود ندارد.
تعویض base_url
نشانی سرویس این است:
https://iranrouter.com/v1اگر با کتابخانهٔ رسمی OpenAI کار میکنید، تغییر در همین حد است:
from openai import OpenAI
client = OpenAI(
api_key="ir-...",
base_url="https://iranrouter.com/v1",
)
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "سلام! خودت را معرفی کن."}],
)
print(resp.choices[0].message.content)در Node هم همان دو خط:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "ir-...",
baseURL: "https://iranrouter.com/v1",
});OpenClaw
OpenClaw نشانی سرویس و کلید را از متغیرهای محیطی میخواند. کافی است پیش از اجرا این دو را ست کنید:
export OPENAI_BASE_URL="https://iranrouter.com/v1"
export OPENAI_API_KEY="ir-..."
openclawاگر ترجیح میدهید این مقادیر همیشگی باشند، همان دو خط را در فایل پیکربندی پوستهٔ خود (~/.zshrc یا ~/.bashrc) بگذارید تا در هر ترمینال جدید هم اعمال شود.
برای تأیید اینکه واقعاً از مسیر ما رد میشود، یک درخواست کوچک بزنید و بعد در پنل کاربری به بخش «مصرف» بروید. باید همان درخواست را با نام مدل، تعداد توکن و هزینه ببینید. اگر آنجا چیزی ثبت نشده، درخواست از IranRouter عبور نکرده است.
Hermes
Hermes همان الگو را دارد، با این تفاوت که پیکربندی را معمولاً در فایل نگه میدارید. بخش مربوط به سرویس را اینطور تنظیم کنید:
provider:
type: openai
base_url: https://iranrouter.com/v1
api_key: ir-...
model: claude-sonnet-4.5نکتهٔ مهم: نام مدل را دقیقاً همان چیزی بنویسید که در صفحهٔ «مدلها» میبینید. اسمهای کوتاهشده یا نام داخلی ابزارهای دیگر لزوماً با شناسهٔ ما یکی نیستند.
اگر ابزارتان با API آنتروپیک حرف میزند
بعضی ابزارها بهجای فرمت OpenAI مستقیم با فرمت Messages آنتروپیک کار میکنند. برای آنها لازم نیست دنبال آداپتور بگردید — همان نشانی، مسیر /v1/messages را هم پاسخ میدهد. کلید همان کلید ir- است.
سه خطای رایج و معنای واقعیشان
۴۰۱ — کلید پذیرفته نشد
یعنی کلید اشتباه، حذفشده یا منقضی است. اگر تازه کلید را ساختهاید، مطمئن شوید فاصله یا خط جدید اضافی هنگام کپی وارد نشده باشد؛ این شایعترین علت است.
۴۰۲ — موجودی کافی نیست
درخواست درست بوده ولی کیف پول برای پوشش هزینهٔ تخمینی آن کافی نیست. پیش از هر تماس، مبلغی معادل تخمین درخواست رزرو میشود و بعد از پاسخ، رقم واقعی جایگزین میشود. پس اگر عدد رزرو از موجودی بیشتر باشد، درخواست پیش از ارسال متوقف میشود.
۴۲۹ — سقف پر شده
یا سقف سرعت کلید پر شده، یا سقف روزانه. در پاسخ، هدر Retry-After میگوید چند ثانیه بعد دوباره تلاش کنید. سقفهای روزانه در نیمهشب به وقت تهران بازنشانی میشوند — نه به وقت گرینویچ.
قبل از اینکه ایجنت را رها کنید
یک ایجنت خودگردان میتواند در چند دقیقه صدها درخواست بزند. پیش از آنکه یک حلقهٔ اشتباه شبانه اجرا شود، این دو کار را بکنید:
- برای هر ایجنت یک کلید جداگانه بسازید. اگر لازم شد یکی را ببندید، بقیه از کار نمیافتند و در گزارش مصرف هم میدانید کدام ایجنت چقدر خرج کرده است.
- روی همان کلید سقف روزانه بگذارید. سقف توکن یا سقف ریالی، هرکدام که با پلن شما معنا دارد. سقف یعنی حتی اگر کد اشتباه کند، خرج از عدد شما بالاتر نمیرود.
قدم بعدی
اولین درخواست موفق که ثبت شد، سراغ انتخاب مدل بروید. تفاوت هزینه بین مدلها برای متن فارسی چشمگیر است و با یک تغییر ساده میشود صورتحساب را قابل توجه پایین آورد — که موضوع دو نوشتهٔ بعدی همین بلاگ است.