OpenCode: الدليل الشامل لوكيل البرمجة الذكي مفتوح المصدر في الطرفية

انتشر OpenCode بشكل هائل ليتجاوز 120 ألف نجمة على GitHub و7.5 مليون مطوّر نشط شهرياً، ليصبح أكثر وكيل برمجة ذكي مفتوح المصدر اعتماداً في التاريخ. على عكس الأدوات المملوكة، يعمل بالكامل في طرفيتك، ويدعم أكثر من 75 مزود نماذج، ويعمل مع النماذج المحلية لحماية البيانات، ويمكن توسيعه بإضافات TypeScript.

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

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

• Node.js 18+ أو Bun مثبتاً
• مرتاح لاستخدام الطرفية
• مفتاح API لمزود نماذج (Google Gemini أو OpenAI أو Mistral) أو Ollama مثبت للنماذج المحلية
• إلمام أساسي بملفات إعداد JSON

ما ستتعلمه

بنهاية هذا الدليل ستكون قادراً على:

• تثبيت OpenCode وتهيئته لأي مشروع
• إعداد مزودي النماذج السحابية والمحلية
• تهيئة المشاريع مع إنشاء AGENTS.md الذكي
• دمج خوادم MCP للوصول إلى الأدوات الخارجية
• كتابة إضافات TypeScript مخصصة لتوسيع قدرات OpenCode

الخطوة الأولى: تثبيت OpenCode

يوفر OpenCode طرق تثبيت متعددة:

التثبيت السريع (موصى به)

curl -fsSL https://opencode.ai/install | bash

npm

npm install -g opencode@latest

Bun

bun add -g opencode

بعد التثبيت، تحقق من أن كل شيء يعمل:

opencode --version

يجب أن ترى الإصدار الحالي مطبوعاً في طرفيتك.

الخطوة الثانية: تهيئة مزود النماذج

يستخدم OpenCode ملف إعداد opencode.json. أنشئه في جذر مشروعك أو في ~/.config/opencode/opencode.json للإعدادات العامة.

حقل $schema يفعّل الإكمال التلقائي في معظم المحررات.

Google Gemini (تتوفر طبقة مجانية)

يتميز Gemini بطبقة مجانية سخية وهو نقطة بداية موصى بها:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "google": {
      "apiKey": "YOUR_GEMINI_API_KEY"
    }
  },
  "model": "google/gemini-2-5-pro"
}

احصل على مفتاح Gemini API من aistudio.google.com.

OpenAI

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "apiKey": "YOUR_OPENAI_API_KEY"
    }
  },
  "model": "openai/gpt-4.1"
}

Mistral (مستضاف في أوروبا، متوافق مع GDPR)

Mistral خيار ممتاز للفرق الأوروبية وفرق منطقة الشرق الأوسط وشمال أفريقيا التي تشترط إقامة البيانات:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "mistral": {
      "apiKey": "YOUR_MISTRAL_API_KEY"
    }
  },
  "model": "mistral/mistral-large-latest"
}

استخدام متغيرات البيئة

بدلاً من تضمين المفاتيح مباشرة، عيّنها كمتغيرات بيئة:

export GOOGLE_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"

يكتشف OpenCode تلقائياً GOOGLE_API_KEY وOPENAI_API_KEY وMISTRAL_API_KEY دون إعداد صريح.

الخطوة الثالثة: النماذج المحلية لخصوصية البيانات الكاملة

للقواعد البرمجية الحساسة أو الأنظمة المالية أو البيئات ذات متطلبات إقامة البيانات الصارمة، شغّل النماذج محلياً. لا تحتاج مفتاح API ولا اتصال بالإنترنت.

إعداد Ollama

ثبّت Ollama من ollama.ai، ثم احضر نموذجاً محسّناً للبرمجة:

ollama pull qwen2.5-coder:32b
# أو الإصدار الأصغر للاستجابة الأسرع:
ollama pull qwen2.5-coder:7b

هيّئ OpenCode لاستخدامه:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      },
      "models": {
        "qwen2.5-coder:32b": {
          "name": "Qwen 2.5 Coder 32B",
          "limit": {
            "context": 128000,
            "output": 32768
          }
        }
      }
    }
  },
  "model": "ollama/qwen2.5-coder:32b"
}

إعداد LM Studio

يوفر LM Studio واجهة رسومية لإدارة النماذج المحلية. بعد تشغيل نموذج في LM Studio:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}

نصيحة للأداء: لنموذج بـ 32 مليار معامل، تحتاج على الأقل 20 جيجابايت من الذاكرة الموحدة أو VRAM. الإصدارات المكثفة Q4 تعمل في أقل من 16 جيجابايت مع الحفاظ على أكثر من 90% من جودة الدقة الكاملة في مهام البرمجة.

الخطوة الرابعة: تهيئة مشروعك

انتقل إلى دليل مشروعك وشغّل OpenCode:

cd my-project
opencode

تفتح واجهة المستخدم في الطرفية (TUI). اكتب /init واضغط Enter. يحلل OpenCode قاعدة الكود ويولّد ملف AGENTS.md في جذر المشروع.

مثال على AGENTS.md لمشروع Next.js

# المشروع: my-nextjs-app
 
## مكدس التقنيات
- Next.js 15.3 مع App Router
- TypeScript في الوضع الصارم
- Tailwind CSS v4
- Drizzle ORM + PostgreSQL
- Vitest + React Testing Library
 
## هيكل المشروع
- `app/` — مسارات Next.js والتخطيطات
- `components/` — مكونات واجهة المستخدم القابلة لإعادة الاستخدام
- `lib/` — الأدوات المشتركة والدوال الخادمية
- `server/` — مخطط قاعدة البيانات والاستعلامات
 
## الاتفاقيات
- أسماء المكونات بـ PascalCase
- إجراءات الخادم في `app/actions/*.ts`
- مسارات API في `app/api/[route]/route.ts`
- استعلامات قاعدة البيانات في `server/queries/*.ts`

أضف AGENTS.md إلى git. هذا الملف يوفر سياقاً مشتركاً يساعد كل جلسة OpenCode على فهم المشروع دون إعادة تحليله في كل مرة.

خصّص الملف المُولَّد: أضف قرارات معمارية أو أنماطاً محظورة أو مفاهيم نطاق مهمة يستخدمها فريقك.

الخطوة الخامسة: الأوامر الأساسية والتنقل

بمجرد تشغيل OpenCode، هذه الأوامر متاحة:

اختصارات لوحة المفاتيح

أنماط الاستعلام الفعّالة

اطلب الخطط قبل التغييرات:

"قبل إجراء أي تغييرات، اشرح ما تخطط لفعله لإضافة ترقيم الصفحات إلى قائمة المنتجات."

حدّد نطاق التغييرات بوضوح:

"أعد هيكلة lib/auth.ts فقط لاستخدام تنسيق الجلسة الجديد. لا تلمس الملفات الأخرى."

الخطوة السادسة: دمج LSP — ذكاء اصطناعي يعي الأنواع

فعّل دعم بروتوكول خادم اللغة للحصول على مساعدة كود أغنى ومراعاة للأنواع:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "lsp": "allow"
  }
}

مع تفعيل LSP، يتصل OpenCode بخادم لغة مشروعك ويحصل على:

• معلومات الأنواع — يرى نفس الأنواع التي يراها محررك
• الانتقال إلى التعريف — يفهم مراجع الرموز عبر الملفات
• التشخيصات — يدرك أخطاء TypeScript قبل اقتراح التغييرات
• وثائق التمرير — يصل إلى تعليقات JSDoc وتوقيعات الأنواع

لمشاريع TypeScript، تأكد من توفر خادم اللغة:

npm install -g typescript typescript-language-server

الخطوة السابعة: الاتصال بخوادم MCP

يتيح بروتوكول نموذج السياق (MCP) ربط OpenCode بأدوات ومصادر بيانات خارجية:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects/allowed-dir"
      ]
    },
    "database": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    },
    "github": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

مع اتصال MCP، يمكنك توجيه OpenCode لـ:

• الاستعلام عن مخطط قاعدة بياناتك وكتابة استعلامات آمنة من الناحية النوعية
• قراءة مشكلات GitHub وإنشائها
• الوصول إلى الملفات خارج دليل المشروع الحالي

الخطوة الثامنة: كتابة إضافات TypeScript

الإضافات هي أقوى ميزة في OpenCode، تتيح إضافة أدوات مخصصة واعتراض hooks التنفيذ.

تثبيت SDK الإضافات

npm install @opencode-ai/plugin

أداة مخصصة: تشغيل اختبارات مكون محدد

// .opencode/plugins/test-runner.ts
import { type Plugin, tool } from "@opencode-ai/plugin"
 
export const TestRunnerPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      run_module_tests: tool({
        description: "تشغيل مجموعة الاختبارات لمكون محدد وإرجاع ملخص النجاح/الفشل",
        args: {
          module: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory } = context
          return `تنفيذ: vitest run ${args.module} في ${directory}`
        },
      }),
    },
  }
}

Hook دورة الحياة: تعقيم أوامر bash

// .opencode/plugins/safety-guard.ts
import { escape } from "shescape"
 
export const SafetyGuardPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

Hook حقن متغيرات البيئة

// .opencode/plugins/env-injector.ts
import type { Plugin } from "@opencode-ai/plugin"
 
export const EnvInjectorPlugin: Plugin = async ({ project }) => {
  return {
    "shell.env": async (input, output) => {
      output.env.PROJECT_ROOT = project.root
      output.env.NODE_ENV = "development"
    },
  }
}

تسجيل الإضافات في opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "./.opencode/plugins/test-runner.ts",
    "./.opencode/plugins/safety-guard.ts",
    "./.opencode/plugins/env-injector.ts"
  ]
}

للإضافات المنشورة على npm، أضفها باسم الحزمة:

{
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime",
    "@my-org/internal-standards"
  ]
}

الخطوة التاسعة: أفضل ممارسات إعداد الفريق

إعداد مشترك على مستوى المشروع

أضف opencode.json إلى git بدون مفاتيح API (استخدم متغيرات البيئة عوضاً):

{
  "$schema": "https://opencode.ai/config.json",
  "model": "google/gemini-2-5-pro",
  "permission": {
    "lsp": "allow",
    "bash": "ask"
  },
  "plugin": [
    "./.opencode/plugins/project-standards.ts"
  ],
  "mcp": {
    "database": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

إعداد التجاوز الشخصي

يحتفظ كل مطوّر بـ ~/.config/opencode/opencode.json لمفاتيح API وتفضيلاته الشخصية، والتي تندمج مع إعداد المشروع دون التأثير على الملف المشترك.

صيانة AGENTS.md

عامل AGENTS.md كوثائق إنتاج. حدّثه عندما:

• تتبنى مكتبة أو نمطاً جديداً
• تضيف مفاهيم نطاق مهمة
• تتخذ قرارات معمارية جديدة
• تكتشف أنماطاً يجب تجنبها

AGENTS.md المُحافَظ عليه جيداً يحسّن جودة اقتراحات الذكاء الاصطناعي بشكل كبير عبر فريقك بأكمله.

استكشاف الأخطاء وإصلاحها

المزود لا يستجيب: تحقق من تعيين مفتاح API في البيئة. شغّل echo $GOOGLE_API_KEY للتأكيد. يقرأ OpenCode GOOGLE_API_KEY وOPENAI_API_KEY وMISTRAL_API_KEY تلقائياً.

بطء استجابات النموذج المحلي: استخدم نموذجاً مكثفاً (Q4 أو Q8). لجهاز بـ 16 جيجابايت RAM، يعطي qwen2.5-coder:7b-q8 أفضل توازن بين السرعة والجودة في مهام البرمجة.

عدم تحميل AGENTS.md: يجب أن يكون في جذر المشروع — نفس الدليل الذي تشغّل فيه opencode. إذا كانت طرفيتك في دليل فرعي، قد لا يجده OpenCode.

أخطاء LSP عند البدء: تأكد من وجود ملف خادم اللغة في PATH. لـ TypeScript: تحقق من أن typescript-language-server --version يعمل في طرفيتك.

عدم تحميل الإضافة: إضافات TypeScript تتطلب tsconfig.json صالحاً في جذر المشروع. تأكد من تثبيت @opencode-ai/plugin محلياً في node_modules.

الخطوات التالية

الآن بعد إعداد OpenCode لسير عملك:

• استكشف سجل الإضافات في opencode.ai/plugins للتكاملات التي بناها المجتمع
• جرّب الوضع الفاعل للتغييرات متعددة الملفات: صف التغيير بمستوى عالٍ ودع OpenCode يخطط وينفذ
• ادمج مع CI للمراجعة الآلية للكود باستخدام opencode --no-tui في خطوط الأنابيب
• ادمج مع Git worktrees لتشغيل جلسات OpenCode المتوازية على ميزات مختلفة في آنٍ واحد

الخلاصة

يقدم OpenCode المرونة التي لا تستطيع وكلاء البرمجة المملوكة توفيرها: اختيار حر للمزودين، ودعم النماذج المحلية لقواعد الكود الحساسة، ونظام إضافات قابل للتوسيع يتكيف مع سير عمل فريقك بالضبط. بفضل دمج LSP ودعم بروتوكول MCP، يتصل بنفس البيئة التقنية التي تستخدمها أدواتك الحالية.

الـ 7.5 مليون مطوّر الذين يستخدمون OpenCode يومياً هم دليل على أن أدوات الذكاء الاصطناعي مفتوحة المصدر وصلت إلى جودة الإنتاج. هيّئه مرة واحدة، أضف AGENTS.md إلى git، ويرث فريقك بالكامل مساعداً برمجياً ذكياً متسقاً وقوياً من اليوم الأول.