شروع کار#

راهنمای گام‌به‌گام از صفر تا اولین جلسه. اگر PostgreSQL از قبل روی میزبان نصب شده باشد، حدود ۱۵ دقیقه زمان بگذارید؛ در غیر این صورت حدود ۲۵ دقیقه طول می‌کشد.

این راهنما به صورت انتها-به-انتها نوشته شده — مواردی را پوشش می‌دهد که کنار opendray قرار دارند (نصب CLIهایی که opendray آن‌ها را اجرا می‌کند، آماده‌سازی Postgres) و مسیرهای استقرار را در README پی‌می‌گیرد. اگر قبلاً از opendray استفاده کرده‌اید و فقط می‌خواهید مجدداً اجرا کنید، مسیرهای خلاصه در بخش «Production deploy» در README مناسب‌تر هستند.

قبلاً می‌دانید opendray مناسب شما هست یا نه؟ اگر نمی‌دانید، ابتدا بخش «What is opendray?» در README را بخوانید — گلوله‌های آن ممکن است ۱۵ دقیقه از وقت شما را صرفه‌جویی کند اگر مورد استفادهٔ شما متناسب نباشد.

گام ۰ — چه چیزهایی نیاز دارید#

ابزار	چرا	توضیح
حداقل یکی از موارد: Claude Code / Codex CLI / Gemini CLI	opendray یک «بسته‌کننده» است، نه مدل — آن‌ها یک CLI را روی میزبان شما اجرا می‌کند	گام ۱ پایین‌تر
PostgreSQL 15 / 16 / 17 + `pgvector` extension	نگهداری وضعیت، جلسات، و بردارهای حافظه	گام ۲ پایین‌تر
`go` 1.25+ و `pnpm` 10+ — تنها در صورتی که از سورس بسازید	اگر باینری انتشار را دانلود می‌کنید، لازم نیست	صفحه انتشار ها
یک پورت شبکه قابل دسترس (پیش‌فرض `:8770`) برای مدیریت وب	رابط کاربری + API + WebSocketها	در صورت استفاده از پروکسی معکوس، به `127.0.0.1` محدود کنید

گام ۱ — نصب حداقل یک AI CLI#

ابزار opendray این CLIها را با استفاده از حساب‌های لوکال شما اجرا می‌کند. این ابزارها را همان‌طور که برای استفاده در ترمینال نصب می‌کنید، نصب کنید؛ opendray باینری‌ها را در متغیر محیطی PATH پیدا می‌کند.

Claude Code (نقطهٔ شروع پیشنهادی)#

[object Promise]

بعد از لاگین، اطلاعات اعتباری در ~/.claude/credentials.json قرار می‌گیرد. ابزار opendray این فایل را به‌صورت خودکار هنگام انتخاب ارائه‌دهندهٔ claude می‌خواند.

Codex CLI (OpenAI)#

[object Promise]

Gemini CLI (Google)#

[object Promise]

بررسی اینکه حداقل یکی قابل دسترس است#

[object Promise]

می‌توانید opendray را با تنها یک CLI نصب‌شده اجرا کنید و بعداً بقیه را اضافه کنید. فهرست ارائه‌دهنده‌ها پویا است — opendray در زمان اجرا باینری را پروب می‌کند و موارد گمشده در پنل Sessions به‌عنوان «executable file not found in $PATH» نمایش داده می‌شوند.

گام ۲ — نصب Postgres + pgvector#

ابزار opendray به PostgreSQL نسخهٔ ۱۵، ۱۶، یا ۱۷ به‌همراه افزونهٔ pgvector نیاز دارد. روش نصب را بر اساس توزیع یا سیستم‌عامل خود انتخاب کنید.

macOS (Homebrew)#

[object Promise]

اوبونتو / دبیان#

[object Promise]

سایر لینوکس‌ها#

بسته‌های PostgreSQL توزیع خود را نصب کنید، سپس یا pkg مربوط به pgvector را نصب کنید یا از منبع ساخت کنید.

آماده‌سازی پایگاه‌دادهٔ opendray (یک‌بار)#

در psql متصل به‌عنوان سوپربِوزر:

[object Promise]

دستور CREATE EXTENSION vector نیاز به دسترسی سوپربِوزر دارد. پس از اجرا، opendray_user فقط به امتیازات CRUD نیاز دارد — opendray در زمان اجرا هرگز به‌عنوان سوپربِوزر مجدداً وصل نمی‌شود.

برای آزمایش اعتبارنامه‌ها از میزانی که opendray قرار است اجرا شود، دستور زیر را اجرا کنید:

[object Promise]

باید خروجی check: ok را بدون خطا ببینید.

گام ۳ — انتخاب مسیر استقرار و نصب opendray#

پرسش تصمیم‌گیرنده: آیا برای قابلیت «spawn session» آماده می‌شوید (کنترل Claude / Codex / Gemini از طریق صفحهٔ Sessions وب)؟

اگر پاسخ بله است — مسیر «Full» لازم دارید#

میزبان شما	مسیر	بخش README
macOS به‌عنوان سرور ۲۴/۷	macOS LaunchDaemon	Option D
سرور/VM/LXC لینوکس	systemd	Option B
فقط آزمایشی در foreground	`go run` از سورس	Quickstart
ناظر روند دستی (s6 / runit / launchd Agent)	باینری مستقیم	Option C

از Docker بپرهیزید. ایمیج distroless است (نود، AI CLIها و pg_dump در آن نیست)؛ بنابراین تب Sessions در هر کلیک spawn خطا خواهد داد. دلیل معماری در بخش §A توضیح داده شده است.

اگر پاسخ خیر است — تنها به کانال‌ها / انتگراسیون‌ها / یادداشت‌ها / API نیاز دارید#

شما همچنان می‌توانید پیام‌ها را روی Telegram / Slack و دیگر کانال‌ها دریافت کنید، یادداشت بنویسید، از API استفاده کنید و مدیریت وب را ببینید؛ فقط نمی‌توانید از این استقرار برای spawn sessionهای لوکال استفاده کنید.

تمام مسیرها به هم می‌رسند روی:

[object Promise]

دو فیلد حداقلی در config.toml:

[object Promise]

سایر تنظیمات مقدارهای پیش‌فرض مناسبی دارند — برای مشاهدهٔ کامل سطح تنظیمات، نظرات داخلی در config.example.toml را ببینید.

گام ۴ — اولین ورود + تغییر گذرواژهٔ admin#

آدرس http://localhost:8770/admin/ (یا هر host:port که در config.toml تنظیم کرده‌اید) را باز کنید.

با نام کاربری admin و گذرواژه‌ای که در [admin].password گذاشته‌اید وارد شوید.
بلافاصله به Settings → Admin → Change password بروید.

چرا بلافاصله: بعد از اولین تغییر گذرواژه، opendray یک فایل keyfile حاوی هش bcrypt را در $HOME/.opendray/secrets/admin.key می‌نویسد و مقدار متنی [admin].password در config.toml بی‌اثر می‌شود (keyfile ارجح است). تا قبل از تغییر، تنها حفاظتی که دارید مجوزهای فایل سیستم روی config.toml است.

زنجیرهٔ ارجحیت اعتبارنامه‌ها در operator-guide §admin توضیح داده شده است.

گام ۵ — پیکربندی یک Provider#

Providers → روی ارائه‌دهنده‌ای که در گام ۱ نصب کرده‌اید کلیک کنید → موارد زیر را پر کنید:

Command path — مسیر مطلق به باینری CLI (با which claude پیدا می‌شود؛ روی Apple Silicon، نصب‌های Homebrew معمولاً در /opt/homebrew/bin/claude قرار می‌گیرند).
Accounts dir (فقط Claude، اختیاری) — دایرکتوری مجموعهٔ اعتبارنامه‌های نام‌گذاری‌شدهٔ Claude اگر می‌خواهید به‌ازای هر جلسه هویت متفاوت انتخاب کنید. خالی بگذارید تا از ~/.claude پیش‌فرض استفاده شود.

ذخیره کنید. opendray یک بار <cli> --version اجرا می‌کند تا پروب انجام شود؛ کارت ارائه‌دهنده وقتی باینری قابل دسترس باشد به رنگ سبز درمی‌آید.

گام ۶ — ایجاد اولین جلسه (spawn)#

Sessions → New session → ارائه‌دهنده را انتخاب کنید → یک دایرکتوری کاری انتخاب کنید (هر پروژه‌ای روی ماشین شما) → Spawn کنید.

یک ترمینال سمتِ مرورگر باز می‌شود. مثل ترمینال واقعی پرامپت‌ها را تایپ کنید. تب را ببندید؛ جلسه روی میزبان به‌کارش ادامه می‌دهد و هنگام بازگشت، scrollback حفظ شده است.

گام ۷ (اختیاری) — افزودن یک کانال Telegram#

این ویژگی تفاوت opendray را با tmux + ssh نشان می‌دهد. با اتصال یک کانال، opendray وقتی جلسه idle می‌شود (CLI منتظر ورودی است) نوتیفیکیشن می‌فرستد و پاسخ شما در Telegram به‌عنوان ورودی بعدی stdin نوشته می‌شود.

راه‌اندازی یک‌بارۀ Telegram#

در Telegram دنبال @BotFather بگردید و چت را شروع کنید.
/newbot → BotFather شما را برای نام و username راهنمایی می‌کند و توکنی شبیه 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 صادر می‌کند.
شناسهٔ چت خود را پیدا کنید:
- به‌صورت مستقیم به بات پیام بدهید (هر متن).
- https://api.telegram.org/bot<token>/getUpdates را در مرورگر باز کنید — chat.id عددی در پاسخ JSON دیده می‌شود.

در opendray#

Channels → New channel → نوع Telegram:

Bot token: از BotFather
Default chat ID: chat.id از getUpdates
Notify on: تیک session.idle را بزنید (یا هر سه موضوع را انتخاب کنید)

ذخیره کنید → روی کارت کانال «Test» را بزنید. ظرف چند ثانیه پیام آزمایشی را در Telegram دریافت خواهید کرد.

حالا یک جلسه را ۳۰ ثانیه (آستانۀ پیش‌فرض idle — قابل تنظیم در [session].idle_threshold) بدون فعالیت رها کنید؛ Telegram پیامی با آخرین خروجی CLI برایتان می‌فرستد. پاسخ دهید؛ متن به stdin جلسه نوشته می‌شود.

قدم بعدی؟#

کانال‌های بیشتر: Slack / Discord / Feishu (飞书) / DingTalk (钉钉) / WeCom (企业微信) — هرکدام تنظیمات مخصوص خود را در آموزش درون‌برنامه‌ای در /admin/tutorial/ دارند.
انتگراسیون‌های API: docs/integration-guide.md — کلیدهای API با محدوده، mount پروکسی معکوس، و WebSocket رویدادها.
زیرسیستم حافظه: برای بردارهای محلی ابتدا "[memory.backend] = \"local\"" را فعال کنید یا Ollama / LM Studio را متصل کنید — آموزش درون‌برنامه → بخش Memory را ببینید.
پشتیبان‌گیری رمزنگاری‌شده: [backup] را پیکربندی کنید تا dumpهای DB را به S3 / R2 / B2 / SFTP / rclone بفرستد — بخش operator-guide §backup را ملاحظه کنید.

رفع‌اشکال#

نشانه	دلیل	رفع
`relation "providers" does not exist` هنگام migrate	باینری قدیمی‌تر از v2.0.0 (issue #162)	آخرین باینری را بگیرید — اصلاح در v2.0.0 آمده است
`type "vector" does not exist` هنگام migrate	افزونهٔ pgvector در پایگاه‌دادهٔ opendray فعال نشده است	در دیتابیس `opendray` به‌عنوان سوپربِوزر `CREATE EXTENSION vector;` را اجرا کنید
`Spawn session failed: executable file not found in $PATH`	CLI بسته‌بندی‌شده روی میزبان opendray نصب نیست، یا Command Path در تنظیمات Provider اشتباه است	گام ۱ را ببینید؛ با `which claude` (یا هر CLI) بررسی کنید
بات Telegram به پاسخ‌ها جواب نمی‌دهد	حالت privacy بات به‌صورت پیش‌فرض روشن است (بات فقط دستورات را می‌بیند)	از BotFather با `/setprivacy` حالت privacy را غیرفعال کنید
`Bad gateway` از طریق پروکسی معکوس	پروکسی هدرهای ارتقاء WebSocket را فوروارد نمی‌کند	برای نمونه‌های nginx / Caddy به operator-guide §Topology مراجعه کنید
تب Sessions خالی است اما کانال‌ها کار می‌کنند	به‌احتمال زیاد باینری قابل اجرا هست اما Provider پیکربندی نشده است	گام ۵ را بررسی کنید

منابع#

README — جدول نصب، مسیرهای استقرار، وضعیت پروژه
README.zh.md — نسخهٔ چینی ساده‌شده
docs/quickstart.md — محیط توسعهٔ ۵ دقیقه‌ای (متمرکزتر از این راهنما)
docs/operator-guide.md — راهنمای اپراتور: توپولوژی، احراز هویت، پشتیبان، لاگینگ
docs/integration-guide.md — سطح API انتگراسیون‌های طرف‌سوم
VERSIONING.md — نسخه‌بندی major-as-generation
CHANGELOG.md — تاریخچهٔ انتشار