تخطَّ إلى المحتوى
OpenCode
app.header.homeapp.header.docs

الوكلاء

هيّئ الوكلاء المتخصصين واستخدمهم.

الوكلاء هم مساعدون متخصصون بالذكاء الاصطناعي يمكن تهيئتهم لمهام وسير عمل محدد. يتيحون لك إنشاء أدوات مركزة مع موجّهات مخصصة ونماذج وصلاحية وصول للأدوات.

يمكنك التبديل بين الوكلاء أثناء الجلسة أو استدعاؤهم عبر الإشارة بـ @.

الأنواع

يوجد نوعان من الوكلاء في OpenCode: وكلاء أساسيون ووكلاء فرعيون.

الوكلاء الأساسيون

الوكلاء الأساسيون هم المساعدون الرئيسيون الذين تتفاعل معهم مباشرة. يمكنك التنقل بينهم باستخدام مفتاح Tab أو اختصار switch_agent الذي قمت بتهيئته. يتولى هؤلاء الوكلاء محادثتك الرئيسية. يتم ضبط وصول الأدوات عبر الأذونات — على سبيل المثال، يمتلك Build جميع الأدوات مفعلة بينما يكون Plan مقيّدا.

يأتي OpenCode مع وكيلين أساسيين مدمجين: Build و Plan. سنلقي نظرة عليهما أدناه.

الوكلاء الفرعيون

الوكلاء الفرعيون هم مساعدين متخصصين يمكن للوكلاء الأساسيين استدعاؤهم لمهام محددة. يمكنك أيضا استدعاؤهم يدويا عبر الإشارة بـ @ في رسائلك.

يأتي OpenCode مع وكيلين فرعيين مدمجين: General و Explore. سنلقي نظرة على ذلك أدناه.

المدمجة

يأتي OpenCode مع وكيلين أساسيين مدمجين ووكيلين فرعيين مدمجين.

استخدام build

الوضع: primary

Build هو الوكيل الأساسي الافتراضي مع تفعيل جميع الأدوات. هذا هو الوكيل القياسي لأعمال التطوير عندما تحتاج إلى وصول كامل لعمليات الملفات وأوامر النظام.

استخدام plan

الوضع: primary

وكيل مقيّد صُمم للتخطيط والتحليل. نستخدم نظام أذونات لمنحك تحكما أكبر ومنع التغييرات غير المقصودة. افتراضيا، يتم ضبط كل ما يلي على ask:

  • file edits: جميع عمليات الكتابة والتصحيح (patches) والتحرير
  • bash: جميع أوامر bash

يفيد هذا الوكيل عندما تريد من LLM تحليل الشفرة أو اقتراح تغييرات أو إنشاء خطط بدون إجراء أي تعديلات فعلية على قاعدة الشفرة.

استخدام general

الوضع: subagent

وكيل عام الغرض للبحث في أسئلة معقدة وتنفيذ مهام متعددة الخطوات. لديه وصول كامل للأدوات (باستثناء todo)، لذا يمكنه إجراء تغييرات على الملفات عند الحاجة. استخدمه لتشغيل عدة وحدات عمل بالتوازي.

استخدام explore

الوضع: subagent

وكيل سريع للقراءة فقط لاستكشاف قواعد الشفرة. لا يستطيع تعديل الملفات. استخدمه عندما تحتاج إلى العثور بسرعة على ملفات عبر أنماط، أو البحث في الشفرة عن كلمات مفتاحية، أو الإجابة عن أسئلة حول قاعدة الشفرة.

استخدام compaction

الوضع: primary

وكيل نظام مخفي يضغط السياق الطويل إلى ملخص أصغر. يعمل تلقائيا عند الحاجة ولا يمكن اختياره من واجهة المستخدم.

استخدام title

الوضع: primary

وكيل نظام مخفي ينشئ عناوين قصيرة للجلسات. يعمل تلقائيا ولا يمكن اختياره من واجهة المستخدم.

استخدام summary

الوضع: primary

وكيل نظام مخفي ينشئ ملخصات للجلسات. يعمل تلقائيا ولا يمكن اختياره من واجهة المستخدم.

الاستخدام

  1. للوكلاء الأساسيين، استخدم مفتاح Tab للتنقل بينهم أثناء الجلسة. يمكنك أيضا استخدام اختصار switch_agent الذي قمت بتهيئته.

  2. يمكن استدعاء الوكلاء الفرعيين:

    • تلقائيا بواسطة الوكلاء الأساسيين لمهام متخصصة بناء على أوصافهم.

    • يدويا عبر الإشارة بـ @ إلى وكيل فرعي في رسالتك. على سبيل المثال:

      @general help me search for this function

  3. التنقل بين الجلسات: عندما ينشئ الوكلاء الفرعيون جلسات فرعية خاصة بهم، يمكنك التنقل بين الجلسة الأم وجميع الجلسات الفرعية باستخدام:

    • <Leader>+Right (أو اختصار session_child_cycle الذي قمت بتهيئته) للتنقل للأمام عبر parent → child1 → child2 → … → parent
    • <Leader>+Left (أو اختصار session_child_cycle_reverse الذي قمت بتهيئته) للتنقل للخلف عبر parent ← child1 ← child2 ← … ← parent

    يتيح لك ذلك التبديل بسلاسة بين المحادثة الرئيسية وعمل الوكلاء الفرعيين المتخصص.

التهيئة

يمكنك تخصيص الوكلاء المدمجين أو إنشاء وكلائك عبر التهيئة. يمكن تهيئة الوكلاء بطريقتين:

JSON

هيّئ الوكلاء في ملف إعدادات opencode.json:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

يمكنك أيضا تعريف الوكلاء باستخدام ملفات Markdown. ضعها في:

  • عام: ~/.config/opencode/agents/
  • لكل مشروع: .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---


You are in code review mode. Focus on:


- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations


Provide constructive feedback without making direct changes.

يصبح اسم ملف Markdown هو اسم الوكيل. على سبيل المثال، ينشئ review.md وكيلا باسم review.

الخيارات

لنلق نظرة على خيارات التهيئة هذه بمزيد من التفصيل.

الوصف

استخدم خيار description لتقديم وصف موجز لما يفعله الوكيل ومتى ينبغي استخدامه.

opencode.json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

هذا خيار تهيئة إلزامي.

درجة الحرارة

تحكم في العشوائية والإبداع في ردود LLM عبر إعداد temperature.

القيم الأقل تجعل الردود أكثر تركيزا وحتمية، بينما تزيد القيم الأعلى من الإبداع والتنوع.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

عادة تتراوح قيم temperature بين 0.0 و 1.0:

  • 0.0-0.2: ردود شديدة التركيز وحتمية، مثالية لتحليل الشفرة والتخطيط
  • 0.3-0.5: ردود متوازنة مع قدر من الإبداع، مناسبة لمهام التطوير العامة
  • 0.6-1.0: ردود أكثر إبداعا وتنوعا، مفيدة للعصف الذهني والاستكشاف
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

إذا لم يتم تحديد temperature، يستخدم OpenCode القيم الافتراضية الخاصة بالنموذج؛ عادة 0 لمعظم النماذج و 0.55 لنماذج Qwen.

الحد الأقصى للخطوات

تحكم في الحد الأقصى لعدد التكرارات الوكيلة التي يمكن لوكيل تنفيذها قبل أن يُجبر على الرد بنص فقط. يتيح ذلك للمستخدمين الذين يرغبون في التحكم بالتكاليف وضع حد للإجراءات الوكيلة.

إذا لم يتم ضبط هذا الخيار، سيستمر الوكيل بالتكرار حتى يقرر النموذج التوقف أو يقاطع المستخدم الجلسة.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

عند بلوغ الحد، يتلقى الوكيل موجّها نظاميا خاصا يطلب منه الرد بملخص لعمله والمهام المتبقية الموصى بها.

التعطيل

اضبطه على true لتعطيل الوكيل.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

الموجّه

حدد ملف موجّه نظامي مخصص لهذا الوكيل عبر إعداد prompt. يجب أن يحتوي ملف الموجّه على تعليمات خاصة بهدف الوكيل.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

هذا المسار نسبي لمكان وجود ملف الإعدادات. لذلك يعمل هذا لكل من إعدادات OpenCode العامة وإعدادات المشروع.

النموذج

استخدم إعداد model لتجاوز (override) النموذج لهذا الوكيل. يفيد ذلك لاستخدام نماذج مختلفة مُحسّنة لمهام مختلفة. على سبيل المثال، نموذج أسرع للتخطيط ونموذج أقدر للتنفيذ.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

يستخدم معرّف النموذج في إعدادات OpenCode الصيغة provider/model-id. على سبيل المثال، إذا كنت تستخدم OpenCode Zen، فستستخدم opencode/gpt-5.1-codex لـ GPT 5.1 Codex.

الأدوات

تحكم في الأدوات المتاحة لهذا الوكيل عبر إعداد tools. يمكنك تفعيل أو تعطيل أدوات محددة بضبطها على true أو false.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

يمكنك أيضا استخدام المحارف البديلة (wildcards) للتحكم في عدة أدوات دفعة واحدة. على سبيل المثال، لتعطيل جميع الأدوات القادمة من خادم MCP:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

اعرف المزيد عن الأدوات.

الأذونات

يمكنك تهيئة الأذونات لإدارة الإجراءات التي يستطيع الوكيل تنفيذها. حاليا، يمكن تهيئة أذونات أدوات edit و bash و webfetch إلى:

  • "ask" — طلب الموافقة قبل تشغيل الأداة
  • "allow" — السماح بكل العمليات بدون موافقة
  • "deny" — تعطيل الأداة
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

يمكنك تجاوز هذه الأذونات لكل وكيل.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

يمكنك أيضا ضبط الأذونات في وكلاء Markdown.

~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---


Only analyze code and suggest changes.

يمكنك ضبط الأذونات لأوامر bash محددة.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

يمكن لهذا أن يقبل نمط glob.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

ويمكنك أيضا استخدام المحرف البديل * لإدارة الأذونات لكل الأوامر. وبما أن آخر قاعدة مطابقة لها الأولوية، ضع قاعدة * أولا ثم القواعد الأكثر تخصيصا بعدها.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

اعرف المزيد عن الأذونات.

الوضع

تحكم في وضع الوكيل عبر إعداد mode. يُستخدم خيار mode لتحديد كيفية استخدام الوكيل.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

يمكن ضبط خيار mode على primary أو subagent أو all. إذا لم يتم تحديد mode، فالقيمة الافتراضية هي all.

مخفي

أخفِ وكيلا فرعيا من قائمة الإكمال التلقائي لـ @ عبر hidden: true. يفيد ذلك للوكلاء الفرعيين الداخليين الذين ينبغي استدعاؤهم برمجيا فقط بواسطة وكلاء آخرين عبر أداة Task.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

يؤثر هذا فقط على ظهور الوكيل للمستخدم في قائمة الإكمال التلقائي. لا يزال بإمكان النموذج استدعاء الوكلاء المخفيين عبر أداة Task إذا سمحت الأذونات.

أذونات Task

تحكم في أي الوكلاء الفرعيين يمكن لوكيل استدعاؤهم عبر أداة Task باستخدام permission.task. يستخدم أنماط glob لمطابقة مرنة.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

عند ضبطها على deny، تتم إزالة الوكيل الفرعي بالكامل من وصف أداة Task، لذا لن يحاول النموذج استدعاءه.

اللون

خصص المظهر البصري للوكيل في واجهة المستخدم عبر خيار color. يؤثر ذلك على كيفية ظهور الوكيل في الواجهة.

استخدم لونا سداسيا صالحا (مثل #FF5733) أو لون سمة: primary و secondary و accent و success و warning و error و info.

opencode.json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

تحكم في تنوع الردود عبر خيار top_p. بديل عن temperature للتحكم بالعشوائية.

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

تتراوح القيم من 0.0 إلى 1.0. القيم الأقل أكثر تركيزا، والقيم الأعلى أكثر تنوعا.

خيارات إضافية

أي خيارات أخرى تحددها في تهيئة الوكيل سيتم تمريرها مباشرة إلى مزود النموذج كخيارات للنموذج. يتيح لك ذلك استخدام ميزات ومعاملات خاصة بالمزود.

على سبيل المثال، مع نماذج الاستدلال من OpenAI يمكنك التحكم في مجهود الاستدلال:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

هذه الخيارات الإضافية تعتمد على النموذج والمزود. راجع توثيق مزودك لمعرفة المعاملات المتاحة.

إنشاء وكلاء

يمكنك إنشاء وكلاء جدد باستخدام الأمر التالي:

Terminal window
opencode agent create

سيقوم هذا الأمر التفاعلي بما يلي:

  1. سيسألك أين تريد حفظ الوكيل: عام (global) أو خاص بالمشروع.
  2. سيطلب وصفا لما ينبغي أن يفعله الوكيل.
  3. سيولّد موجّها نظاميا ومعرّفا مناسبا.
  4. سيتيح لك اختيار الأدوات التي يمكن للوكيل الوصول إليها.
  5. أخيرا، سينشئ ملف Markdown يحتوي تهيئة الوكيل.

حالات الاستخدام

فيما يلي بعض حالات الاستخدام الشائعة لوكلاء مختلفين.

  • Build agent: أعمال تطوير كاملة مع تفعيل جميع الأدوات
  • Plan agent: تحليل وتخطيط بدون إجراء تغييرات
  • Review agent: مراجعة الشفرة مع وصول للقراءة فقط بالإضافة إلى أدوات التوثيق
  • Debug agent: يركز على التحقيق مع تفعيل أدوات bash والقراءة
  • Docs agent: كتابة التوثيق مع عمليات الملفات بدون أوامر النظام

أمثلة

فيما يلي بعض أمثلة الوكلاء التي قد تجدها مفيدة.

وكيل التوثيق

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---


You are a technical writer. Create clear, comprehensive documentation.


Focus on:


- Clear explanations
- Proper structure
- Code examples
- User-friendly language

مدقق أمني

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---


You are a security expert. Focus on identifying potential security issues.


Look for:


- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues