آموزش میزبانی Open Connector برای ایجنت‌های هوش مصنوعی

نقش Open Connector برای یک ایجنت هوش مصنوعی

میزبانی Open Connector یک درگاه احراز هویت بین ایجنت‌های هوش مصنوعی شما و تمام APIهای نرم‌افزار به عنوان سرویس (SaaS) که فراخوانی می‌کنند قرار می‌دهد، بنابراین ایجنت هرگز توکن ارائه‌دهنده را در اختیار نخواهد داشت. این یک درگاه متن‌باز از OOMOL Lab است که تحت مجوز Apache 2.0 منتشر شده است. این ابزار به صورت یک کانتینر اجرا می‌شود، وضعیت خود را در یک فایل SQLite واحد نگه می‌دارد و اقدامات ارائه‌دهنده را از طریق HTTP و MCP (پروتکل زمینه مدل) ارائه می‌دهد.

مشکلات از دومین یکپارچه‌سازی شروع می‌شود. هر ارائه‌دهنده، جریان OAuth (احراز هویت باز) خاص خود، طول عمر توکن رفرش منحصر به فرد و نام‌های scope مخصوص به خود را دارد. اتصال دستی پنج ارائه‌دهنده به یک ایجنت به معنای پنج هندلر تغییر مسیر (redirect)، پنج ذخیره‌ساز اعتبارنامه و پنج حلقه رفرش است که باید پیش از انقضای توکن اجرا شوند. تقریباً هیچ‌کس چنین کدی را نمی‌نویسد. آن‌ها یک توکن دسترسی شخصی با طول عمر بالا برای هر سرویس ایجاد کرده و آن را در پیکربندی ایجنت، یک فایل محیطی (environment file) یا خودِ پرامپت قرار می‌دهند. آن توکن سپس توسط هر ابزاری که ایجنت اجرا می‌کند قابل خواندن است و در متن گفتگو (transcript) ثبت می‌شود، که این همان شکستی است که در جلوگیری از نشت اسرار در ایجنت‌های هوش مصنوعی توصیف شده است.

یک درگاه احراز هویت، اعتبارنامه را به دو بخش تقسیم می‌کند. درگاه، اعتبارنامه ارائه‌دهنده را ذخیره کرده و جریان OAuth را اجرا می‌کند. ایجنت یک توکن زمان اجرا دریافت می‌کند که فقط در برابر درگاه معتبر است. هنگامی که ایجنت یک عملیات را فراخوانی می‌کند، درگاه اعتبارنامه ذخیره‌شده را بارگذاری کرده، آن را در سمت سرور به درخواست خروجی تزریق می‌کند و فقط بدنه پاسخ را برمی‌گرداند. ایجنت هرگز توکن دسترسی ارائه‌دهنده را دریافت نمی‌کند، بنابراین نشت متن گفتگوی ایجنت، تنها هزینه یک توکن زمان اجرای قابل ابطال را برای شما خواهد داشت، نه دسترسی به حساب GitHub شما.

کاتالوگ این پروژه بیش از 1000 ارائه‌دهنده و 10000 عملیات از پیش ساخته‌شده را تبلیغ می‌کند که این رقم متعلق به خود پروژه است و چیزی نیست که بتوانید از بیرون تأیید کنید. آنچه می‌توانید تأیید کنید، ساختار آن است: یک endpoint HTTP برای هر عملیات، یک اتصال ذخیره‌شده برای هر ارائه‌دهنده و یک توکن برای هر ایجنت. اگر سمت ایجنت این موضوع هنوز جدید است و اصطلاحاتی مانند tool call یا MCP server هنوز تثبیت نشده‌اند، مسیر مرحله‌بندی‌شده در چگونه ایجنت‌های هوش مصنوعی را از صفر یاد بگیریم، حلقه، ابزارها و عادت‌های ایمنی را ایجاد می‌کند که درگاهی مانند این، فرض می‌کند شما از قبل آن‌ها را دارید.

چرا به‌جای استفاده از سرویس‌های میزبانی‌شده، Open Connector را خودتان میزبانی کنید

یک سرویس connector میزبانی‌شده، همان کار را انجام می‌دهد و refresh tokenهای مربوط به تمام سرویس‌دهندگانی که به آن متصل کرده‌اید را نزد خود نگه می‌دارد. یک refresh token برای Google یا GitHub، کلیدی با عمر طولانی برای دسترسی به ایمیل‌ها و مخازن کد شماست و معمولاً با تغییر رمز عبور نیز باطل نمی‌شود. نفوذ به آن‌ها، به معنای نفوذ به حساب‌های شماست. خودمیزبانی (self-hosting)، این رکوردها را به یک فایل SQLite روی ماشینی منتقل می‌کند که شما آن را اجاره و مدیریت می‌کنید؛ فایلی که با کلیدی مهروموم شده است که هرگز از سرور شما خارج نمی‌شود.

پیش از شروع، هزینه‌های آن را به‌طور شفاف در نظر بگیرید. این VPS به ارزشمندترین سروری تبدیل می‌شود که مدیریت می‌کنید. این سرور اعتبارنامه‌های فعال ده‌ها سرویس را در یک فایل نگهداری می‌کند، بنابراین باید همان رفتاری را با آن داشته باشید که با میزبانِ مدیریت رمز عبور (password manager) دارید: فایروالی که فقط پورت 443 را باز می‌گذارد، عدم استفاده از لاگین‌های اشتراکی، بک‌آپی که حداقل یک‌بار آن را بازیابی کرده‌اید، و سیستمی برای هشدار در زمانی که سرور پاسخ نمی‌دهد. اگر حاضر نیستید vault رمز عبور خود را روی این سرور قرار دهید، connector را نیز روی آن نصب نکنید.

پیش از نصب هر چیزی، یک نسخه را ثابت (Pin) کنید

Open Connector پروژه نوپایی است. این مخزن برای نخستین بار در تاریخ 29 June 2026 ظاهر شد و تا تاریخ 1 August 2026، جدیدترین نسخه تگ‌شده v1.3.3 است که در تاریخ 30 July 2026 منتشر شده و دارای تگ latest نیز می‌باشد. رجیستری یک تگ tip هم منتشر می‌کند که از جدیدترین کامیت روی main ساخته شده است.

در پروژه‌ای به این تازگی، تگ‌های متغیر (moving tags) مدام تغییر می‌کنند. یک docker compose pull که از روی دو نسخه می‌پرد، می‌تواند endpoint مورد نیاز agent شما را تغییر دهد و شما مجبور خواهید شد تمام شب را صرف عیب‌یابی آن به عنوان یک مشکل در agent کنید. image را روی یک تگ نسخه ثابت کنید و پس از مطالعه یادداشت‌های انتشار (release notes)، هر زمان که خودتان تصمیم گرفتید، آن را ارتقا دهید.

استقرار Open Connector پشت TLS روی VPS شخصی

پیش از اجرای container، به موارد زیر نیاز دارید:

• Docker به همراه افزونه Compose روی Ubuntu 24.04 یا توزیع مشابه
• یک نام دامنه که رکورد A آن به این VPS اشاره می‌کند، برای مثال connect.example.com
• یک reverse proxy که در حال حاضر TLS (امنیت لایه انتقال) را برای آن دامنه مدیریت می‌کند
• دو عبارت امنیتی تصادفی که در ادامه تولید می‌شوند

راهنمای Traefik reverse proxy برای چندین برنامه Docker Compose بخش مربوط به proxy را پوشش می‌دهد. جزئیات کامل مربوط به گواهی‌ها برای یک برنامه واحد نیز در راهنمای n8n روی VPS با Docker و HTTPS موجود است.

ابتدا عبارت‌های امنیتی را تولید کنید. کلید رمزنگاری (encryption key) اعتبارنامه‌های ذخیره‌شده را مهر و موم می‌کند. توکن مدیریت (admin token) از کنسول وب و کل سطح دسترسی /api محافظت می‌کند. هیچ‌کدام مقدار پیش‌فرض ندارند و runtime بدون آن‌ها نیز اجرا می‌شود، اما این کار ناامن است.

mkdir -p ~/open-connector && cd ~/open-connector
umask 077
printf 'OOMOL_CONNECT_ENCRYPTION_KEY=%s\n' "$(openssl rand -base64 32)" > .env
printf 'OOMOL_CONNECT_ADMIN_TOKEN=%s\n' "$(openssl rand -base64 32)" >> .env
chmod 600 .env

هر دو مقدار را همین حالا، پیش از اولین اجرا، در مدیریت رمز عبور خود ذخیره کنید. کلید رمزنگاری هیچ راه بازیابی ندارد و دلیل آن در لیست خطاهای زیر ذکر شده است.

اکنون compose.yaml را ایجاد کنید. این فایل در دو مورد با نمونه اصلی تفاوت دارد و هر دو مورد اهمیت دارند.

services:
  connector:
    image: ghcr.io/oomol-lab/open-connector:v1.3.3
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - connector-data:/app/data
    environment:
      OOMOL_CONNECT_DATA_DIR: /app/data
      OOMOL_CONNECT_ORIGIN: "https://connect.example.com"
      OOMOL_CONNECT_ENCRYPTION_KEY: "${OOMOL_CONNECT_ENCRYPTION_KEY:?set this in .env}"
      OOMOL_CONNECT_ADMIN_TOKEN: "${OOMOL_CONNECT_ADMIN_TOKEN:?set this in .env}"

volumes:
  connector-data:

تغییر اول، استفاده از تگ ثابت (pinned tag) به‌جای latest است. تغییر دوم مربوط به پورت است. فایل اصلی از 3000:3000 استفاده می‌کند که روی تمام رابط‌های شبکه میزبان (host) متصل می‌شود. Docker پورت‌های منتشرشده را پیش از آنکه زنجیره فیلتر ufw بسته‌ها را ببیند، در جدول NAT (ترجمه آدرس شبکه) می‌نویسد؛ بنابراین ufw deny 3000 آن پورت را نمی‌بندد، که این همان تله‌ای است که در چرا پورت‌های Docker از ufw عبور می‌کنند توضیح داده شده است. نوشتن 127.0.0.1:3000:3000 باعث می‌شود پورت فقط روی رابط loopback منتشر شود و reverse proxy شما از همان میزبان به آن متصل شود.

عبارت :? هر متغیر را به‌عنوان الزامی علامت‌گذاری می‌کند، بنابراین اگر .env موجود نباشد، stack از اجرا امتناع می‌کند تا از اجرای برنامه با اعتبارنامه‌های رمزنگاری‌نشده جلوگیری شود. نگهداری مقادیر در .env به‌جای فایل compose، الگویی است که در فایل‌های env در Docker Compose و secrets معرفی شده است.

docker compose up -d
docker compose logs -n 30 connector
curl -s http://127.0.0.1:3000/health
sudo ss -tlnp | grep 3000

پس از بالا آمدن runtime، /health به { "ok": true } پاسخ می‌دهد. ss باید 127.0.0.1:3000 را چاپ کند. اگر خطی حاوی 0.0.0.0:3000 مشاهده کردید، به این معنی است که نگاشت پورت هنوز همان حالت اصلی است و gateway مستقیماً به کل اینترنت پاسخ می‌دهد. خطای Connection refused در بررسی سلامت (health check) به این معنی است که container هنوز در حال گوش دادن نیست؛ بنابراین پیش از تغییر در تنظیمات proxy، لاگ‌ها را مطالعه کنید.

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.connector.rule=Host(`connect.example.com`)"
      - "traefik.http.routers.connector.entrypoints=websecure"
      - "traefik.http.routers.connector.tls.certresolver=le"
      - "traefik.http.services.connector.loadbalancer.server.port=3000"

چرا OAuth شما را ملزم به داشتن یک hostname واقعی می‌کند

تنظیم OOMOL_CONNECT_ORIGIN موردی است که کاربران اغلب از آن صرف‌نظر می‌کنند، و نادیده گرفتن آن باعث می‌شود OAuth به شکلی از کار بیفتد که گویی ارائه‌دهنده دچار خطا شده است. محیط اجرا (runtime)، آدرس بازگشت (redirect URI) خود را بر اساس آن مبدأ و به فرمت <origin>/oauth/callback می‌سازد. اگر این مقدار تنظیم نشود، مبدأ به‌صورت پیش‌فرض http://localhost:3000 در نظر گرفته می‌شود؛ بنابراین محیط اجرا، آدرس بازگشت http://localhost:3000/oauth/callback را برای ارائه‌دهنده ارسال می‌کند، در حالی که برنامه OAuth شما با آدرس https://connect.example.com/oauth/callback ثبت شده است. از آنجا که این دو رشته با هم تفاوت دارند، GitHub این پاسخ را می‌دهد:

The redirect_uri MUST match the registered callback URL for this application.

یک ارائه‌دهنده OAuth، مرورگر را به آن آدرس بازگشت هدایت می‌کند؛ این یعنی آدرس باید برای دنیای خارج قابل دسترسی باشد و ارائه‌دهندگان، آدرس‌های ساده http:// را برای هر چیزی به‌جز localhost رد می‌کنند. به همین دلیل است که این استقرار به یک hostname و گواهی‌نامه نیاز دارد. مبدأ را پیش از اولین راه‌اندازی تنظیم کنید، زیرا این مقدار در زمان شروع برنامه خوانده می‌شود: پس از ویرایش .env یا compose.yaml، دستور docker compose up -d را دوباره اجرا کنید تا تغییرات اعمال شوند.

اتصال اولین ارائه‌دهنده از طریق OAuth

ابتدا برنامه OAuth را در پنل ارائه‌دهنده ایجاد کنید. در GitHub، مسیر Settings، سپس Developer settings، سپس OAuth Apps و در نهایت New OAuth App را دنبال کنید. آدرس بازگشت (callback URL) احراز هویت را روی https://connect.example.com/oauth/callback تنظیم کنید. شناسه کلاینت (client ID) و رمز کلاینت (client secret) را نزد خود نگه دارید.

هر فراخوانی /api شامل توکن مدیریت (admin token) است، بنابراین آن را یک‌بار برای نشست (session) فعلی shell صادر (export) کنید.

export ADMIN_TOKEN='paste-the-admin-token'
curl -s https://connect.example.com/api/oauth/configs \
  -H "authorization: Bearer $ADMIN_TOKEN"

این لیست، URI تغییر مسیر (redirect URI) مورد انتظار runtime برای هر ارائه‌دهنده را نشان می‌دهد؛ این سریع‌ترین راه برای بررسی اعمال شدن تنظیمات شماست. اگر همچنان مقدار localhost نمایش داده می‌شود، کانتینر با مقدار قدیمی در حال اجراست و فرآیند OAuth در مرحله آخر با خطا مواجه خواهد شد.

اعتبارنامه‌های کلاینت را ذخیره کرده و سپس یک احراز هویت را آغاز کنید.

curl -s -X PUT https://connect.example.com/api/oauth/configs/github \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"clientId":"...","clientSecret":"..."}'

curl -s -X POST https://connect.example.com/api/oauth/authorizations \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"service":"github"}'

فراخوانی دوم یک authorizationUrl برمی‌گرداند. آن را در مرورگر باز کنید، دامنه‌های دسترسی (scopes) را تأیید کنید تا ارائه‌دهنده مرورگر را به /oauth/callback بازگرداند؛ جایی که runtime کد را مبادله کرده و اعتبارنامه را ذخیره می‌کند. کنسول وب در مبدأ شما، همین مراحل را از طریق یک فرم و با استفاده از همان توکن مدیریت انجام می‌دهد. ارائه‌دهندگانی که از کلید API ساده استفاده می‌کنند، از تمام این مراحل عبور می‌کنند: PUT /api/connections/<service> به همراه {"authType":"api_key","values":{"apiKey":"..."}} کلید را مستقیماً ذخیره می‌کند.

به هر عامل یک توکن زمان اجرا اختصاص دهید، نه اعتبارنامه اصلی

عامل با استفاده از یک توکن زمان اجرا (runtime token) که توسط API مدیریت صادر شده است، به gateway احراز هویت می‌کند.

curl -s -X POST https://connect.example.com/api/runtime-tokens \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"research-agent"}'

پاسخ شامل توکنی است که با oct_ شروع می‌شود. برای هر عامل یک توکن صادر کنید و آن را با نام همان عامل نام‌گذاری کنید، زیرا ابطال توکنی که نمی‌توانید شناسایی کنید به معنای ابطال همه توکن‌هاست. سپس عامل، عملیات را از طریق HTTP معمولی فراخوانی می‌کند.

curl -s -X POST https://connect.example.com/v1/actions/github.get_current_user \
  -H "authorization: Bearer oct_..." \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

یک پاسخ سالم، پاکتی است که فیلد success آن برابر با true باشد و payload ارائه‌دهنده در زیر data قرار گرفته باشد. توکن GitHub در هیچ کجای این پاسخ وجود ندارد. برای یک کلاینت MCP، آن را با همان هدر bearer به https://connect.example.com/mcp اشاره دهید؛ در این حالت gateway به جای ارائه یک ابزار به ازای هر API، ابزارهای کشف مانند search_actions و execute_action را ارائه می‌دهد که باعث می‌شود لیست ابزارهای عامل کوچک باقی بماند. اجرای سرورهای MCP روی یک VPS نیمه کلاینتی این اتصال را پوشش می‌دهد.

پیش از آنکه این کار را تمام‌شده تلقی کنید، یک بررسی دیگر انجام دهید. فراخوانی عملیات را با حذف هدر authorization تکرار کنید. راهنمای شروع سریع خود پروژه، /v1 را بدون هیچ bearer فراخوانی می‌کند، بنابراین نصبی که در آن احراز هویت زمان اجرا پیکربندی نشده باشد، عملیات را برای هر کسی که به پورت دسترسی داشته باشد اجرا خواهد کرد. اگر فراخوانی بدون احراز هویت شما موفقیت‌آمیز بود، دو راه پیش رو دارید: توکن‌های زمان اجرا را پیکربندی کنید و تأیید کنید که فراخوانی ناشناس اکنون با شکست مواجه می‌شود، یا دسترسی به /api، /v1 و /mcp را در reverse proxy به آدرس‌هایی که عامل‌های شما از آنجا می‌آیند محدود کنید. فقط /oauth/callback باید برای عموم باز بماند، زیرا این تنها مسیری است که تغییر مسیر مرورگر ارائه‌دهنده به آن نیاز دارد.

فهرست عملیات را به آنچه عامل نیاز دارد محدود کنید

یک درگاه (gateway) با هزاران ارائه‌دهنده در پشت آن، سطح حمله گسترده‌ای را در اختیار یک مدل زبانی قرار می‌دهد. این سطح زمانی گسترده‌تر می‌شود که مدل شروع به خواندن متنی کند که خودش ننوشته است؛ زیرا صفحه‌ای که توسط نمونه SearXNG شخصی شما که به جستجوهای وب عامل پاسخ می‌دهد بازگردانده می‌شود، می‌تواند حاوی دستورالعمل‌هایی باشد که هر عملیاتی را که عامل در اختیار دارد، هدف قرار دهد. همان خویشتن‌داری که باعث می‌شود یک عامل کدنویسی کوچک‌ترین تغییرِ کارآمد را اعمال کند، باید در مجوزهای آن نیز رعایت شود: تنها تعداد انگشت‌شماری از عملیاتی را که برای انجام کار ضروری هستند به آن اعطا کنید و فراتر از آن چیزی ندهید. دو کنترل این دسترسی را محدود می‌کنند.

OOMOL_CONNECT_ALLOWED_ACTIONS یک لیست مجاز (allowlist) با جداکننده کاما می‌پذیرد و service.* و * را درک می‌کند. OOMOL_CONNECT_BLOCKED_ACTIONS لیست سیاه (denylist) است و اولویت با لیست سیاه است. تنظیم لیست مجاز روی github.get_current_user,github.list_issues به این معنی است که هر عملیات دیگری صرف‌نظر از درخواست عامل، رد می‌شود؛ این همان تفاوتی است که یک اشتباه را از یک حادثه امنیتی متمایز می‌کند. توکن‌های زمان اجرا (Runtime tokens) قوانین عملیاتی خاص خود را علاوه بر قوانین سراسری اعمال می‌کنند و لیست allowedProxies آن‌ها در ابتدا خالی است، بنابراین POST /v1/proxy/:service تا زمانی که آن را صراحتاً اعطا نکنید، رد می‌شود. آن نقطه پایانی پروکسی (proxy endpoint)، یک درخواست خام را به همراه اعتبارنامه شما به ارائه‌دهنده ارسال می‌کند، بنابراین آن را خالی بگذارید مگر اینکه یک عامل خاص به آن نیاز داشته باشد.

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK به‌صورت پیش‌فرض روی false تنظیم شده است که مانع از آن می‌شود که اتصال به یک ارائه‌دهنده میزبانی‌شده توسط خودتان (self-hosted)، به یک آدرس خصوصی مانند سرویس متادیتای ابری در 169.254.169.254 یا پایگاه داده شما در همان شبکه اشاره کند. آن را غیرفعال بگذارید. فقط برای ارائه‌دهنده‌ای که خودتان میزبانی می‌کنید، آن را فعال کنید.

پشتیبان‌گیری از سروری که تمام توکن‌ها را نگهداری می‌کند

دو مورد اهمیت دارند و هر کدام بدون دیگری بی‌فایده است. پایگاه داده در /app/data/connect.sqlite داخل volume مربوط به connector-data، اعتبارنامه‌های مهر و موم شده را نگه می‌دارد. کلید رمزنگاری در .env آن‌ها را از حالت مهر و موم خارج می‌کند. پشتیبان‌گیری از volume بدون کلید، چیزی را بازیابی نمی‌کند و کلید بدون volume نیز کارایی ندارد؛ بنابراین کلید باید در مدیریت رمز عبور شما ذخیره شود و volume باید در چرخه پشتیبان‌گیری معمول شما قرار گیرد.

هنگام کپی کردن فایل SQLite، کانتینر را متوقف کنید، زیرا کپی‌برداری در حین عملیات نوشتن ممکن است منجر به بازیابی یک پایگاه داده خراب شود.

docker volume ls | grep connector-data
docker compose stop connector
docker run --rm -v open-connector_connector-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/connector-data.tgz -C /data .
docker compose start connector

نام volume برابر است با دایرکتوری پروژه شما به اضافه _connector-data، به همین دلیل دستور اول در آنجا قرار دارد: نام واقعی را در دستور سوم جای‌گذاری کنید. آرشیو را با استفاده از پشتیبان‌گیری restic از یک VPS از روی VPS خارج کنید؛ این ابزار پیش از خروج داده‌ها، آن‌ها را رمزنگاری می‌کند، زیرا آن آرشیو در واقع مخزن اعتبارنامه‌ها است.

محیط اجرا (runtime)، آخرین عملیات‌های انجام شده را به عنوان سوابق حسابرسی (audit records) نگه می‌دارد که به‌طور پیش‌فرض 5,000 مورد است، بنابراین کنسول می‌تواند به شما بگوید کدام عامل (agent) چه کاری را در چه زمانی انجام داده است. آن لاگ اولین چیزی است که هنگام رفتار غیرعادی یک عامل باید مطالعه شود. همچنین یک صفحه وضعیت Uptime Kuma را به https://connect.example.com/health متصل کنید. هنگامی که gateway پاسخ‌دهی را متوقف می‌کند، عامل‌ها به شیوه‌های گیج‌کننده‌ای دچار خطا می‌شوند و اطلاع از اینکه gateway از دسترس خارج شده است، یک ساعت از زمان شما را برای خواندن خروجی عامل‌ها ذخیره می‌کند.

چه چیزی از کار می‌افتد و پیامی که مشاهده خواهید کرد

redirect_uri_mismatch در سمت ارائه‌دهنده. مبدأ (origin) و URL بازگشتی (callback URL) ثبت‌شده با هم تفاوت دارند. رشته دقیق را از /api/oauth/configs با تنظیمات برنامه در پنل ارائه‌دهنده مقایسه کنید؛ این بررسی شامل https در برابر http و هرگونه اسلش انتهایی (trailing slash) می‌شود.

هر فراخوانی /api با خطای 401 مواجه می‌شود. هدر توکن مدیریت (admin token) وجود ندارد یا اشتباه نوشته شده است. نام هدر Authorization: Bearer <token> است و کنسول وب نیز همان توکن را درخواست می‌کند.

کانتینر اجرا می‌شود و اعتبارنامه‌ها به صورت متن ساده (plain text) ذخیره شده‌اند. این اتفاق زمانی رخ می‌دهد که OOMOL_CONNECT_ENCRYPTION_KEY هرگز به کانتینر نمی‌رسد، زیرا runtime به جای امتناع از شروع کار، رکوردهای اعتبارنامه را بدون رمزنگاری ذخیره می‌کند. این موضوع را در نصب خود آزمایش کنید: یک ارائه‌دهنده را با یک API key که می‌شناسید متصل کنید، سپس پایگاه داده را برای یافتن آن جستجو کنید.

docker compose cp connector:/app/data/connect.sqlite /tmp/connect.sqlite
grep -c 'github_pat_' /tmp/connect.sqlite
shred -u /tmp/connect.sqlite

تعداد (count) بزرگ‌تر از 0 به این معنی است که کلید اعمال نشده است؛ بنابراین بررسی کنید که .env در همان دایرکتوری compose.yaml قرار داشته باشد و docker compose config مقدار آن را نشان دهد. با تنظیم صحیح کلید، همان جستجو باید مقدار 0 را برگرداند، زیرا رکورد با استاندارد AES-256-GCM (استاندارد رمزنگاری پیشرفته، کلید 256 بیتی، حالت Galois/counter) مهر و موم شده است.

پس از بازیابی (restore)، هیچ‌چیز رمزگشایی نمی‌شود. کلید رمزنگاری تغییر کرده یا گم شده است. طبق طراحی، این کلید هرگز در کنار داده‌ها ذخیره نمی‌شود، بنابراین هیچ مسیر بازیابی و هیچ تیکت پشتیبانی برای آن وجود ندارد. تمام ارائه‌دهنده‌ها را دوباره متصل کنید. چرخش کلید (rotation) از طریق یک متغیر کلید مجزا و یک دستور داده در runtime پشتیبانی می‌شود، بنابراین پیش از هرگونه چرخش، یادداشت‌های انتشار (release notes) فعلی را مطالعه کنید.

ایجنت (agent) خطایی دریافت می‌کند که به عملیاتی اشاره دارد که در کاتالوگ قابل مشاهده است. کشف (discovery) و اجرا (execution) دو فرایند مجزا هستند. یک عملیات ممکن است در search_actions ظاهر شود اما همچنان توسط OOMOL_CONNECT_ALLOWED_ACTIONS، لیست سیاه (denylist) یا قوانین مربوط به همان توکن runtime رد شود.

ارتقاها. از volume نسخه پشتیبان تهیه کنید، تگ image را به نسخه جدید تغییر دهید و سپس docker compose pull && docker compose up -d را اجرا کنید. docker compose logs -n 50 connector را برای مشاهده خط مربوط به migration زیر نظر بگیرید و پیش از اعتماد مجدد به سیستم، بررسی سلامت (health check) و یک عملیات واقعی را اجرا کنید. بازگشت به نسخه قبلی (rollback) به معنای بازگرداندن تگ قدیمی است که تنها در صورتی کار می‌کند که آن را از قبل ثابت (pin) کرده باشید.

FAQ

آیا برای میزبانی شخصی Open Connector به دامنه عمومی نیاز دارم؟

برای ارائه‌دهندگانی که از API key استفاده می‌کنند، خیر: یک gateway روی 127.0.0.1 کافی است. اما برای OAuth، در عمل بله. ارائه‌دهنده، مرورگر را به callback URL شما هدایت می‌کند، بنابراین آن URL باید از اینترنت عمومی قابل حل (resolve) باشد و ارائه‌دهندگان از پذیرش http:// ساده در خارج از localhost خودداری می‌کنند. پیش از اولین اجرا، OOMOL_CONNECT_ORIGIN را روی hostname خود در https:// تنظیم کنید و <origin>/oauth/callback را در اپلیکیشن OAuth ارائه‌دهنده ثبت نمایید.

اگر کلید رمزنگاری Open Connector را گم کنم چه می‌شود؟

اعتبارنامه‌های ذخیره‌شده قابل رمزگشایی نیستند و هیچ راه بازیابی وجود ندارد. این کلید عمداً هرگز در کنار داده‌ها ذخیره نمی‌شود تا هیچ‌کس، حتی شما، نتواند با در اختیار داشتن دیتابیس آن را بخواند. تنها گزینه شما این است که کلید جدیدی تنظیم کرده و دوباره به هر ارائه‌دهنده متصل شوید. کلید را در یک مدیریت‌کننده رمز عبور و دیتابیس را در چرخه پشتیبان‌گیری خود نگه دارید، زیرا بازیابی به هر دو نیاز دارد.

آیا ایجنت هوش مصنوعی من می‌تواند توکن دسترسی ارائه‌دهنده را ببیند؟

خیر، زمانی که از طریق gateway فراخوانی می‌کند، این‌طور نیست. ایجنت با یک توکن runtime که با oct_ شروع می‌شود احراز هویت می‌کند و gateway اعتبارنامه ارائه‌دهنده را به درخواست خروجی در سرور تزریق کرده و فقط پاسخ را برمی‌گرداند. دو مورد این ویژگی را نقض می‌کنند: اندپوینت /v1/proxy/:service که درخواست‌های خام را با اعتبارنامه متصل‌شده شما ارسال می‌کند (و به همین دلیل است که دسترسی‌های آن به‌صورت پیش‌فرض خالی هستند) و چسباندن دستی API key در ایجنت که باعث می‌شود gateway کاملاً نادیده گرفته شود.

آیا gateway باید از اینترنت عمومی در دسترس باشد؟

فقط /oauth/callback باید در دسترس باشد. پورت کانتینر را روی 127.0.0.1 منتشر کنید تا قوانین NAT در Docker نتوانند آن را فراتر از فایروال شما در معرض دید قرار دهند و یک reverse proxy در مقابل آن قرار دهید. سپس یک فراخوانی عملیاتی را بدون هدر authorization تست کنید. اگر موفقیت‌آمیز بود، /api، /v1 و /mcp را در پروکسی محدود به آدرس‌هایی کنید که ایجنت‌های شما استفاده می‌کنند، تا زمانی که فقط فراخوانی‌های احراز هویت‌شده کار کنند.

آیا Open Connector برای استفاده در محیط عملیاتی (production) آماده است؟

این نرم‌افزار تحت لایسنس Apache 2.0 است و به‌سرعت در حال پیشرفت است: مخزن آن در 29 June 2026 ایجاد شد و نسخه v1.3.3 در 30 July 2026 منتشر شد، بنابراین هر شماره نسخه در این راهنما را به‌عنوان یک snapshot از تاریخ 1 August 2026 در نظر بگیرید. آن را روی یک release tag ثابت اجرا کنید، هرگز از latest یا tip استفاده نکنید، پیش از هر ارتقا یادداشت‌های انتشار را بخوانید و یک نسخه پشتیبان از volume داشته باشید که قبلاً آن را بازیابی کرده‌اید. طراحی برای سروری که مالک آن هستید مناسب است و ریسک اصلی، تغییرات سریع نسخه‌هاست، نه معماری آن.