الخادم
يشغّل الأمر 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 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.
يعرض خادم opencode واجهات API التالية.
| الطريقة | المسار | الوصف | الاستجابة |
|---|---|---|---|
GET | /global/health | الحصول على صحة الخادم وإصداره | { healthy: true, version: string } |
GET | /global/event | الحصول على الأحداث العامة (تدفق SSE) | تدفق أحداث |
| الطريقة | المسار | الوصف | الاستجابة |
|---|---|---|---|
GET | /project | سرد جميع المشاريع | Project[] |
GET | /project/current | الحصول على المشروع الحالي | Project |
| الطريقة | المسار | الوصف | الاستجابة |
|---|---|---|---|
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[] |
POST | /session/:id/init | تحليل التطبيق وإنشاء AGENTS.md | المتن: { messageID, providerID, modelID }، يعيد boolean |
POST | /session/:id/fork | تفريع جلسة موجودة عند رسالة | المتن: { messageID? }، يعيد Session |
POST | /session/:id/abort | إلغاء جلسة قيد التشغيل | يعيد boolean |
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 |
| الطريقة | المسار | الوصف | الاستجابة |
|---|---|---|---|
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 |
| الطريقة | المسار | الوصف | الاستجابة |
|---|---|---|---|
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 |