راهنمای استفاده از GapGPT در OpenClaw
OpenClaw یک Gateway و دستیار عاملمحور است که میتواند کانالها، ابزارها، حافظه و مدل را در یک پیکربندی واحد مدیریت کند. در این راهنما، OpenClaw را به endpoint سازگار با OpenAI گپجیپیتی وصل میکنیم.
این راهنما از custom provider در OpenClaw استفاده میکند. برای جلوگیری از لو رفتن کلید، مقدار کلید در متغیر محیطی قرار میگیرد و فقط نام آن در
openclaw.jsonنوشته میشود.
۱. پیشنیازها
- Node.js مطابق نسخهی پشتیبانیشدهی مستندات نصب OpenClaw
- یک کلید API از بخش کلیدهای API گپجیپیتی
- اعتبار کافی در کیف پول API
- شناسهی دقیق یک مدل از صفحه مدلها و قیمتها
۲. نصب OpenClaw
macOS، Linux و WSL2:
curl -fsSL https://openclaw.ai/install.sh | bash
Windows PowerShell:
iwr -useb https://openclaw.ai/install.ps1 | iex
بعد از نصب، ویزارد اولیه را اجرا کنید:
openclaw onboard
اگر در ویزارد provider پیشفرضی انتخاب کردید، بعداً میتوانید provider گپجیپیتی را با پیکربندی زیر اضافه کنید.
۳. تعریف provider گپجیپیتی
کلید را در محیط اجرای OpenClaw تعریف کنید:
export GAPGPT_API_KEY="YOUR_GAPGPT_API_KEY"
برای ماندگارشدن در macOS یا Linux، این خط را در ~/.zshrc یا ~/.bashrc قرار دهید و سپس shell را reload کنید:
export GAPGPT_API_KEY="YOUR_GAPGPT_API_KEY"
در Windows PowerShell:
$env:GAPGPT_API_KEY = "YOUR_GAPGPT_API_KEY"
سپس در openclaw.json، بخش models و مدل پیشفرض agent را اضافه کنید. محل فایل را از تنظیمات نصب خود OpenClaw بردارید؛ معمولاً فایل اصلی در ~/.openclaw/openclaw.json است.
{
models: {
mode: "merge",
providers: {
gapgpt: {
baseUrl: "https://api.gapgpt.app/v1",
apiKey: "${GAPGPT_API_KEY}",
api: "openai-completions",
models: [
{
id: "gpt-5.6-sol",
name: "GPT-5.6 Sol",
input: ["text"]
}
]
}
}
},
agents: {
defaults: {
model: {
primary: "gapgpt/gpt-5.6-sol"
},
models: {
"gapgpt/gpt-5.6-sol": {}
}
}
}
}
در این تنظیمات:
baseUrlباید بهhttps://api.gapgpt.app/v1ختم شود.- مقدار
apiبرای endpointهای سازگار با OpenAI،openai-completionsاست. gapgptنام دلخواه provider است و بخش اول شناسهی مدل را میسازد.- مقدار
idباید با نام مدل در GapGPT یکی باشد.
اگر مدل دیگری میخواهید، مقدار id و primary را همزمان با شناسهی دقیق آن عوض کنید. برای چند مدل، مدلهای دیگر را به آرایهی models اضافه کنید و برای هرکدام مسیر gapgpt/<model-id> را در allowlist قرار دهید.
۴. انتخاب و تست مدل
بعد از ذخیرهی پیکربندی، مدل provider را بررسی کنید:
openclaw models list --provider gapgpt
openclaw models set gapgpt/gpt-5.6-sol
سپس یک درخواست کوتاه از رابط یا channel فعال OpenClaw بفرستید. برای تست مستقیم endpoint هم میتوانید از این فرمان استفاده کنید:
curl https://api.gapgpt.app/v1/chat/completions \
-H "Authorization: Bearer $GAPGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"messages": [{"role": "user", "content": "سلام! خودت را در یک جمله معرفی کن."}]
}'
۵. استفاده از ابزارها و کانالها
OpenClaw مدل را برای تصمیمگیری agent استفاده میکند، اما کانالها و ابزارها در Gateway خود OpenClaw اجرا میشوند. بعد از موفقیت تست مدل، میتوانید:
- کانالهای پیامرسان و WebChat را طبق مستندات channelهای OpenClaw فعال کنید.
- policy ابزارها را در
tools.profileوtools.allow/tools.denyمحدود کنید. - برای حافظه، فقط وقتی endpoint embedding سازگار دارید بخش
memory.searchرا جداگانه تنظیم کنید؛ مدل چت بهتنهایی embedding تولید نمیکند. - برای مدلهای دارای ورودی تصویر، در metadata مدل مقدار
inputرا به["text", "image"]تغییر دهید و پشتیبانی همان مدل را در صفحه مدلها بررسی کنید.
۶. نکات مهم دربارهی tool calling
- OpenClaw برای agentهای ابزارمحور به مدلی با پشتیبانی مناسب از tools/function calling نیاز دارد.
- اگر پاسخ متنی ساده کار میکند اما اجرای ابزار خطا میدهد، ابتدا مدل دیگری از صفحه قیمتها را امتحان کنید.
- از افزودن
openai-responsesخودداری کنید مگر اینکه endpoint انتخابی واقعاً/v1/responsesرا پشتیبانی کند؛ اتصال معمول GapGPT در این راهنما بر پایهی/v1/chat/completionsاست. - بعد از تغییر
openclaw.json، Gateway یا session را طبق روش اجرای OpenClaw restart کنید تا تنظیمات جدید خوانده شوند.
۷. مدیریت هزینه و امنیت
- کلید API را در
openclaw.jsonبه صورت متن ساده ننویسید؛${GAPGPT_API_KEY}یا SecretRef را ترجیح دهید. - دسترسی ابزارهای فایل، ترمینال، مرورگر و کانالها را حداقلی نگه دارید.
- مصرف را در نمودار مصارف گپجیپیتی و هزینهی مدل را در صفحه مدلها و قیمتها بررسی کنید.
- اگر OpenClaw را روی سرور عمومی اجرا میکنید، Gateway را با احراز هویت و شبکهی محدود اجرا کنید و endpoint مدیریت را روی اینترنت باز نگذارید.
۸. عیبیابی سریع
مدل در فهرست OpenClaw دیده نمیشود
- وجود
models.providers.gapgpt.models[]و تطابقidباagents.defaults.model.primaryرا بررسی کنید. - دستور
openclaw models list --provider gapgptرا اجرا کنید. GAPGPT_API_KEYباید در همان محیطی باشد که Gateway اجرا میشود، نه فقط در یک ترمینال دیگر.
خطای 401
- کلید را دوباره از بخش کلیدهای API بسازید یا مقدار متغیر محیطی را بررسی کنید.
- در
apiKeyفقط${GAPGPT_API_KEY}بنویسید وBearerرا داخل آن قرار ندهید؛ OpenClaw هدر احراز هویت را میسازد.
خطای ابزار یا پاسخ نامعتبر
apiرا رویopenai-completionsنگه دارید.- مدل انتخابی را با یک مدل دارای tool calling جایگزین کنید.
- برای تشخیص، ابتدا همان model id را با
curlروی/v1/chat/completionsامتحان کنید.