الخادم

يشغّل الأمر opencode serve خادما HTTP دون واجهة ويعرض نقطة نهاية OpenAPI يمكن لعميل opencode استخدامها.

---

الاستخدام

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

الخيارات

الخيار	الوصف	الافتراضي
--port	المنفذ الذي يستمع عليه	4096
--hostname	اسم المضيف الذي يستمع عليه	127.0.0.1
--mdns	تفعيل اكتشاف mDNS	false
--mdns-domain	اسم نطاق مخصص لخدمة mDNS	opencode.local
--cors	أصول (Origins) متصفح إضافية مسموح بها	[]

يمكن تمرير --cors عدة مرات:

opencode serve --cors http://localhost:5173 --cors https://app.example.com

---

المصادقة

عيّن OPENCODE_SERVER_PASSWORD لحماية الخادم باستخدام مصادقة HTTP الأساسية. اسم المستخدم افتراضيا هو opencode، أو عيّن OPENCODE_SERVER_USERNAME لتغييره. ينطبق ذلك على كل من opencode serve و opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

---

كيف يعمل

عند تشغيل opencode يبدأ تشغيل واجهة terminal تفاعلية (TUI) وخادما. تكون الـ TUI هي العميل الذي يتحدث إلى الخادم. يوفّر الخادم نقطة نهاية لمواصفة OpenAPI 3.1. وتُستخدم هذه النقطة أيضا لتوليد SDK.

نصيحة

استخدم خادم opencode للتفاعل مع opencode برمجيا.

تتيح هذه البنية لـ opencode دعم عدة عملاء وتمكّنك من التفاعل مع opencode برمجيا.

يمكنك تشغيل opencode serve لبدء خادم مستقل. إذا كانت واجهة opencode في terminal (TUI) قيد التشغيل، فسيبدأ opencode serve خادما جديدا.

---

الاتصال بخادم موجود

عند بدء الـ TUI تقوم بتعيين منفذ واسم مضيف عشوائيا. يمكنك بدلا من ذلك تمرير الخيارات --hostname و --port، ثم استخدامهما للاتصال بخادمها.

يمكن استخدام نقطة النهاية /tui للتحكم في الـ TUI عبر الخادم. على سبيل المثال، يمكنك تعبئة الموجّه مسبقا أو تشغيله. يُستخدم هذا الإعداد بواسطة ملحقات OpenCode لـ IDE.

---

المواصفات

ينشر الخادم مواصفة OpenAPI 3.1 ويمكن عرضها على:

http://<hostname>:<port>/doc

على سبيل المثال: http://localhost:4096/doc. استخدم المواصفة لتوليد عملاء أو لفحص أنواع الطلبات والاستجابات. أو اعرضها في مستكشف Swagger.

---

واجهات API

يعرض خادم opencode واجهات API التالية.

---

عام

الطريقة	المسار	الوصف	الاستجابة
GET	/global/health	الحصول على صحة الخادم وإصداره	{ healthy: true, version: string }
GET	/global/event	الحصول على الأحداث العامة (تدفق SSE)	تدفق أحداث

---

المشروع

الطريقة	المسار	الوصف	الاستجابة
GET	/project	سرد جميع المشاريع	Project[]
GET	/project/current	الحصول على المشروع الحالي	Project

---

المسار و VCS

الطريقة	المسار	الوصف	الاستجابة
GET	/path	الحصول على المسار الحالي	Path
GET	/vcs	الحصول على معلومات VCS للمشروع الحالي	VcsInfo

---

المثيل

الطريقة	المسار	الوصف	الاستجابة
POST	/instance/dispose	التخلص من المثيل الحالي	boolean

---

الإعدادات

الطريقة	المسار	الوصف	الاستجابة
GET	/config	الحصول على معلومات الإعدادات	Config
PATCH	/config	تحديث الإعدادات	Config
GET	/config/providers	سرد المزوّدين والنماذج الافتراضية	{ providers: Provider[], default: { [key: string]: string } }

---

المزوّد

الطريقة	المسار	الوصف	الاستجابة
GET	/provider	سرد جميع المزوّدين	{ all: Provider[], default: {...}, connected: string[] }
GET	/provider/auth	الحصول على طرق مصادقة المزوّد	{ [providerID: string]: ProviderAuthMethod[] }
POST	/provider/{id}/oauth/authorize	تفويض مزوّد باستخدام OAuth	ProviderAuthAuthorization
POST	/provider/{id}/oauth/callback	معالجة رد نداء OAuth لمزوّد	boolean

---

الجلسات

الطريقة	المسار	الوصف	الملاحظات
GET	/session	سرد جميع الجلسات	يعيد Session[]
POST	/session	إنشاء جلسة جديدة	المتن: { parentID?, title? }، يعيد Session
GET	/session/status	الحصول على حالة الجلسات جميعها	يعيد { [sessionID: string]: SessionStatus }
GET	/session/:id	الحصول على تفاصيل الجلسة	يعيد Session
DELETE	/session/:id	حذف جلسة وجميع بياناتها	يعيد boolean
PATCH	/session/:id	تحديث خصائص الجلسة	المتن: { title? }، يعيد Session
GET	/session/:id/children	الحصول على الجلسات الفرعية لجلسة	يعيد Session[]
GET	/session/:id/todo	الحصول على قائمة المهام (todo) للجلسة	يعيد Todo[]
POST	/session/:id/init	تحليل التطبيق وإنشاء AGENTS.md	المتن: { messageID, providerID, modelID }، يعيد boolean
POST	/session/:id/fork	تفريع جلسة موجودة عند رسالة	المتن: { messageID? }، يعيد Session
POST	/session/:id/abort	إلغاء جلسة قيد التشغيل	يعيد boolean
POST	/session/:id/share	مشاركة جلسة	يعيد Session
DELETE	/session/:id/share	إلغاء مشاركة جلسة	يعيد Session
GET	/session/:id/diff	الحصول على diff لهذه الجلسة	الاستعلام: messageID?، يعيد FileDiff[]
POST	/session/:id/summarize	تلخيص الجلسة	المتن: { providerID, modelID }، يعيد boolean
POST	/session/:id/revert	التراجع عن رسالة	المتن: { messageID, partID? }، يعيد boolean
POST	/session/:id/unrevert	استعادة جميع الرسائل المتراجع عنها	يعيد boolean
POST	/session/:id/permissions/:permissionID	الرد على طلب إذن	المتن: { response, remember? }، يعيد boolean

---

الرسائل

الطريقة	المسار	الوصف	الملاحظات
GET	/session/:id/message	سرد رسائل جلسة	الاستعلام: limit?، يعيد { info: Message, parts: Part[]}[]
POST	/session/:id/message	إرسال رسالة والانتظار للحصول على رد	المتن: { messageID?, model?, agent?, noReply?, system?, tools?, parts }، يعيد { info: Message, parts: Part[]}
GET	/session/:id/message/:messageID	الحصول على تفاصيل الرسالة	يعيد { info: Message, parts: Part[]}
POST	/session/:id/prompt_async	إرسال رسالة بشكل غير متزامن (بدون انتظار)	المتن: مثل /session/:id/message، يعيد 204 No Content
POST	/session/:id/command	تنفيذ أمر شرطة مائلة (slash)	المتن: { messageID?, agent?, model?, command, arguments }، يعيد { info: Message, parts: Part[]}
POST	/session/:id/shell	تشغيل أمر في shell	المتن: { agent, model?, command }، يعيد { info: Message, parts: Part[]}

---

الأوامر

الطريقة	المسار	الوصف	الاستجابة
GET	/command	سرد جميع الأوامر	Command[]

---

الملفات

الطريقة	المسار	الوصف	الاستجابة
GET	/find?pattern=<pat>	البحث عن نص داخل الملفات	مصفوفة من كائنات المطابقة تحتوي على path وlines وline_number وabsolute_offset وsubmatches
GET	/find/file?query=<q>	العثور على الملفات والمجلدات بالاسم	string[] (مسارات)
GET	/find/symbol?query=<q>	العثور على رموز مساحة العمل	Symbol[]
GET	/file?path=<path>	سرد الملفات والمجلدات	FileNode[]
GET	/file/content?path=<p>	قراءة ملف	FileContent
GET	/file/status	الحصول على حالة الملفات المتعقّبة	File[]

معلمات الاستعلام لـ /find/file

• query (مطلوب) — سلسلة البحث (مطابقة ضبابية)
• type (اختياري) — حصر النتائج في "file" أو "directory"
• directory (اختياري) — تجاوز جذر المشروع لأجل البحث
• limit (اختياري) — الحد الأقصى للنتائج (1–200)
• dirs (اختياري) — خيار قديم (إرجاع "false" يعيد الملفات فقط)

---

الأدوات (تجريبية)

الطريقة	المسار	الوصف	الاستجابة
GET	/experimental/tool/ids	سرد جميع معرّفات الأدوات	ToolIDs
GET	/experimental/tool?provider=<p>&model=<m>	سرد الأدوات مع مخططات JSON لنموذج	ToolList

---

LSP والمنسّقات و MCP

الطريقة	المسار	الوصف	الاستجابة
GET	/lsp	الحصول على حالة خادم LSP	LSPStatus[]
GET	/formatter	الحصول على حالة المنسّقات	FormatterStatus[]
GET	/mcp	الحصول على حالة خادم MCP	{ [name: string]: MCPStatus }
POST	/mcp	إضافة خادم MCP ديناميكيا	المتن: { name, config }، يعيد كائن حالة MCP

---

الوكلاء

الطريقة	المسار	الوصف	الاستجابة
GET	/agent	سرد جميع الوكلاء المتاحين	Agent[]

---

التسجيل

الطريقة	المسار	الوصف	الاستجابة
POST	/log	كتابة إدخال سجل. المتن: { service, level, message, extra? }	boolean

---

TUI

الطريقة	المسار	الوصف	الاستجابة
POST	/tui/append-prompt	إلحاق نص بالموجّه	boolean
POST	/tui/open-help	فتح مربع حوار المساعدة	boolean
POST	/tui/open-sessions	فتح محدد الجلسات	boolean
POST	/tui/open-themes	فتح محدد السمات	boolean
POST	/tui/open-models	فتح محدد النماذج	boolean
POST	/tui/submit-prompt	إرسال الموجّه الحالي	boolean
POST	/tui/clear-prompt	مسح الموجّه	boolean
POST	/tui/execute-command	تنفيذ أمر ({ command })	boolean
POST	/tui/show-toast	عرض toast ({ title?, message, variant })	boolean
GET	/tui/control/next	الانتظار لطلب التحكم التالي	كائن طلب تحكم
POST	/tui/control/response	الاستجابة لطلب تحكم ({ body })	boolean

---

المصادقة

الطريقة	المسار	الوصف	الاستجابة
PUT	/auth/:id	تعيين بيانات اعتماد المصادقة. يجب أن يطابق المتن مخطط المزوّد	boolean

---

الأحداث

الطريقة	المسار	الوصف	الاستجابة
GET	/event	تدفق أحداث مرسلة من الخادم (SSE). أول حدث هو server.connected ثم أحداث الحافلة	تدفق أحداث مرسلة من الخادم

---

التوثيق

الطريقة	المسار	الوصف	الاستجابة
GET	/doc	مواصفة OpenAPI 3.1	صفحة HTML تتضمن مواصفة OpenAPI