نصب Open Connector روی VPS برای عامل‌های هوش مصنوعی

Open Connector برای یک عامل هوش مصنوعی چه کاری انجام می‌دهد

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

مشکل از دومین یکپارچه‌سازی آغاز می‌شود. هر ارائه‌دهنده جریان OAuth (احراز هویت باز) مخصوص خود، طول عمر مخصوص توکن refresh و نام‌های scope مخصوص خود را دارد. اتصال دستی پنج ارائه‌دهنده به یک عامل، به پنج handler برای redirect، پنج مخزن اعتبارنامه و پنج حلقه refresh نیاز دارد که باید پیش از منقضی‌شدن توکن اجرا شوند. تقریباً هیچ‌کس این کد را نمی‌نویسد. در عوض، برای هر سرویس یک personal access token با عمر طولانی ایجاد می‌کنند و آن را در پیکربندی عامل، فایل محیطی یا خود prompt قرار می‌دهند. سپس هر ابزاری که عامل اجرا می‌کند می‌تواند آن توکن را بخواند و توکن در transcript نیز ثبت می‌شود؛ این همان مشکلی است که دور نگه‌داشتن اسرار از عامل‌های هوش مصنوعی توضیح می‌دهد.

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

کاتالوگ، بیش از 1,000 ارائه‌دهنده و 10,000 عملیات ازپیش‌ساخته را معرفی می‌کند. این رقم متعلق به خود پروژه است و نمی‌توان آن را از بیرون راستی‌آزمایی کرد. چیزی که می‌توان راستی‌آزمایی کرد، ساختار آن است: یک endpoint HTTP برای هر عملیات، یک connection ذخیره‌شده برای هر ارائه‌دهنده و یک توکن برای هر عامل.

چرا Open Connector را به‌صورت self-hosted اجرا کنیم، نه با استفاده از یک سرویس connector میزبانی‌شده

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

پیش از شروع، هزینه را دقیقاً در نظر بگیرید. این VPS به ارزشمندترین سروری تبدیل می‌شود که اجرا می‌کنید. این سرور credentialهای فعال ده‌ها سرویس را در یک فایل نگهداری می‌کند؛ بنابراین باید مانند میزبان password manager با آن رفتار کنید: firewall فقط پورت 443 را در معرض شبکه قرار دهد، ورودهای مشترک استفاده نشود، از داده‌ها نسخه پشتیبان داشته باشید و حداقل یک بار واقعاً بازیابی آن را آزمایش کرده باشید، و هنگامی که سرور دیگر پاسخ نمی‌دهد، هشدار دریافت کنید. اگر حاضر نیستید vault مربوط به passwordهای خود را روی این سرور قرار دهید، connector را نیز روی آن قرار ندهید.

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

Open Connector نرم‌افزاری نوپاست. این مخزن نخستین‌بار در 29 June 2026 ایجاد شد و در 1 August 2026، جدیدترین release دارای tag، یعنی v1.3.3، است که در 30 July 2026 منتشر شده و tag مربوط به latest را نیز دارد. registry همچنین tag مربوط به tip را منتشر می‌کند که از جدیدترین commit در main ساخته شده است.

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

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

پیش از راه‌اندازی کانتینر، به موارد زیر نیاز دارید:

• Docker به‌همراه Compose plugin، روی Ubuntu 24.04 یا نسخه‌ای نزدیک به آن
• یک hostname که رکورد A آن به این VPS اشاره کند؛ برای نمونه connect.example.com
• یک reverse proxy که از قبل TLS (امنیت لایه انتقال) را برای آن hostname خاتمه دهد
• دو secret تصادفی که در ادامه تولید می‌شوند

راهنمای reverse proxy مربوط به Traefik برای چند برنامه Docker Compose بخش proxy را پوشش می‌دهد. روند کامل تنظیم certificate برای یک برنامه منفرد، از ابتدا تا انتها، در راهنمای n8n روی VPS با Docker و HTTPS آمده است.

ابتدا secretها را تولید کنید. encryption key اعتبارنامه‌های ذخیره‌شده را رمزگذاری می‌کند. admin token از web console و کل سطح /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

هر دو مقدار را همین حالا، پیش از نخستین راه‌اندازی، در password manager خود کپی کنید. برای encryption key مسیر بازیابی وجود ندارد و دلیل آن در فهرست خطاهای پایین‌تر توضیح داده شده است.

اکنون compose.yaml. این فایل در دو بخش با نمونه upstream تفاوت دارد و هر دو تفاوت مهم هستند.

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:

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

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

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

/health پس از آماده‌شدن runtime به { "ok": true } پاسخ می‌دهد. ss باید 127.0.0.1:3000 را چاپ کند. خطی با محتوای 0.0.0.0:3000 نشان می‌دهد که mapping مربوط به port هنوز همان مقدار upstream است و gateway مستقیماً به کل اینترنت پاسخ می‌دهد. اگر health check با خطای connection refused مواجه شود، یعنی کانتینر هنوز در حال گوش‌دادن نیست؛ بنابراین پیش از تغییر proxy، logها را بررسی کنید.

    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 را به‌گونه‌ای مختل می‌کند که شبیه خطای provider به نظر می‌رسد. runtime URI بازگشت را از آن origin و با قالب <origin>/oauth/callback می‌سازد. اگر این مقدار تنظیم نشده باشد، origin به‌طور پیش‌فرض http://localhost:3000 می‌شود. در نتیجه، runtime URI بازگشت http://localhost:3000/oauth/callback را برای provider ارسال می‌کند، در حالی که در برنامه OAuth شما مقدار https://connect.example.com/oauth/callback ثبت شده است. این دو رشته با هم تفاوت دارند، بنابراین GitHub پاسخ زیر را ارسال می‌کند:

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

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

اتصال نخستین provider از طریق OAuth

ابتدا برنامه OAuth را در provider ایجاد کنید. در GitHub، مسیر به این صورت است: Settings، سپس Developer settings، سپس OAuth Apps و بعد New OAuth App. نشانی callback مجوزدهی را روی https://connect.example.com/oauth/callback تنظیم کنید. client ID و client secret را نگه دارید.

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

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

این فهرست، redirect URI مورد انتظار runtime را برای هر provider نشان می‌دهد و سریع‌ترین روش برای بررسی اعمال‌شدن origin شماست. اگر همچنان localhost را نشان می‌دهد، container با مقدار قبلی در حال اجراست و جریان OAuth در آخرین مرحله شکست خواهد خورد.

اعتبارنامه‌های client را ذخیره کنید، سپس فرایند مجوزدهی را آغاز کنید.

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 برمی‌گرداند. آن را در مرورگر باز کنید، scopeها را تأیید کنید و provider مرورگر را به /oauth/callback بازمی‌گرداند؛ در این مرحله runtime کد را مبادله می‌کند و اعتبارنامه را ذخیره می‌کند. کنسول وب در origin شما، همین مراحل را با یک فرم و با استفاده از همان admin token اجرا می‌کند. providerهایی که از API key ساده استفاده می‌کنند، همه این مراحل را رد می‌کنند: PUT /api/connections/<service> با {"authType":"api_key","values":{"apiKey":"..."}}، کلید را مستقیماً ذخیره می‌کند.

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

عامل با استفاده از یک توکن زمان اجرا به دروازه احراز هویت می‌شود؛ این توکن را API مدیریتی صادر می‌کند.

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 در هیچ بخشی از این پاسخ وجود ندارد. برای یک client مربوط به MCP، آن را به https://connect.example.com/mcp متصل کنید و همان header مربوط به bearer را استفاده کنید. در این حالت، دروازه ابزارهای کشف مانند search_actions و execute_action را ارائه می‌دهد، نه یک ابزار برای هر API؛ بنابراین فهرست ابزارهای عامل کوچک می‌ماند. اجرای سرورهای MCP روی یک VPS بخش مربوط به client این اتصال را پوشش می‌دهد.

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

فهرست اقدام‌ها را به موارد موردنیاز agent محدود کنید

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

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

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK به‌طور پیش‌فرض روی false تنظیم است. این تنظیم مانع می‌شود اتصال self-hosted provider به آدرس خصوصی مانند سرویس cloud metadata در 169.254.169.254 یا database شما در همان شبکه اشاره کند. آن را خاموش نگه دارید. فقط برای providerای که خودتان میزبانی می‌کنید، آن را روشن کنید.

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

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

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

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 اجراهای اخیر action را به‌صورت رکوردهای audit نگه می‌دارد؛ مقدار پیش‌فرض 5,000 رکورد است. بنابراین console می‌تواند نشان دهد کدام agent چه کاری را در چه زمانی اجرا کرده است. هنگام رفتار غیرعادی یک agent، ابتدا همین log را بررسی کنید. همچنین یک صفحه وضعیت Uptime Kuma را به https://connect.example.com/health متصل کنید. وقتی gateway دیگر پاسخ نمی‌دهد، agentها به شکل‌های گیج‌کننده‌ای با خطا مواجه می‌شوند و اطلاع از قطع بودن gateway، یک ساعت بررسی خروجی agent را ذخیره می‌کند.

چه چیزهایی از کار می‌افتند و چه پیامی می‌بینید

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

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

کانتینر اجرا می‌شود و اعتبارنامه‌ها به‌صورت متن ساده ذخیره می‌شوند. این وضعیت زمانی رخ می‌دهد که OOMOL_CONNECT_ENCRYPTION_KEY هرگز به کانتینر نمی‌رسد؛ زیرا محیط اجرا رکوردهای اعتبارنامه را بدون رمزنگاری ذخیره می‌کند و به‌جای امتناع از شروع، اجرا را ادامه می‌دهد. این موضوع را در نصب خود بررسی کنید: یک ارائه‌دهنده را با کلید API قابل‌شناسایی متصل کنید، سپس پایگاه داده را برای یافتن آن جست‌وجو کنید.

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

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

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

عامل با خطایی مواجه می‌شود که نام عملی را ذکر می‌کند که در فهرست می‌بیند. کشف و اجرا از هم جدا هستند. یک عمل ممکن است در search_actions نمایش داده شود، اما OOMOL_CONNECT_ALLOWED_ACTIONS، denylist یا قوانین اختصاصی همان توکن محیط اجرا همچنان آن را رد کند.

ارتقاها. از volume نسخه پشتیبان بگیرید، tag مربوط به image را به انتشار جدید تغییر دهید، سپس docker compose pull && docker compose up -d را اجرا کنید. docker compose logs -n 50 connector را برای یافتن خط مربوط به migration پایش کنید و پیش از اعتماد دوباره به سامانه، بررسی سلامت و یک عمل واقعی را مجدداً اجرا کنید. بازگشت به نسخه قبلی یعنی tag قدیمی را دوباره تنظیم کنید؛ این کار فقط به این دلیل ممکن است که tag را ثابت کرده‌اید.

FAQ

آیا برای میزبانی Open Connector به‌صورت مستقل به دامنه عمومی نیاز دارم؟

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

اگر کلید رمزنگاری Open Connector را گم کنم چه اتفاقی می‌افتد؟

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

آیا عامل هوش مصنوعی من می‌تواند access token ارائه‌دهنده را ببیند؟

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

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

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

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

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