بناء وكلاء الذكاء الاصطناعي المخصصين باستخدام OpenClaw: دليل المطور

إن بناء وكيل ذكاء اصطناعي جاهز للإنتاج ليس مثل كتابة روبوت الدردشة. يجب على الوكلاء إدراك السياق، والتفكير في المعلومات غير المكتملة، وتنفيذ خطط متعددة الخطوات، والتعافي من حالات الفشل - كل ذلك دون إشراف بشري. OpenClaw عبارة عن منصة وكيل للذكاء الاصطناعي للمؤسسات تم تصميمها خصيصًا لهذا المستوى من الاستقلالية التشغيلية، مما يمنح المطورين وقت تشغيل منظم ونموذجًا لتكوين المهارات وإمكانية المراقبة من الدرجة الأولى من اليوم الأول.

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

الوجبات الرئيسية

• يتكون وكلاء OpenClaw من المهارات (القدرات الذرية)، وطبقات الذاكرة، والمنسق الذي يخطط لتسلسلات التنفيذ.
• يعلن ملف بيان الوكيل عن كافة التبعيات والأذونات وارتباطات الأدوات قبل وقت التشغيل.
• المهارات هي وظائف عديمة الحالة تقبل المدخلات المكتوبة وتصدر مخرجات مكتوبة، وقابلية الاختبار مضمنة.
• تخدم طبقات الذاكرة العاملة وذاكرة الحلقة والذاكرة طويلة المدى احتياجات مختلفة للاحتفاظ والاسترجاع.
• تتيح لك الخطافات (التشغيل المسبق، والتشغيل اللاحق، والخطأ) إدخال المراقبة وتحديد المعدل والمنطق الاحتياطي دون تعديل كود المهارة الأساسية.
• يتيح لك وضع Sandbox الخاص بـ OpenClaw إعادة تشغيل آثار الإنتاج محليًا لتصحيح الأخطاء دون استدعاءات API المباشرة.
• تستخدم عمليات التسليم متعددة الوكلاء ناقل رسائل مكتوبًا - ولا توجد سلسلة أولية تمر بين الوكلاء.
• يوفر ECOSIRE تطبيقات OpenClaw المُدارة ومكتبات المهارات المخصصة والتحسين المستمر لفرق المؤسسة.

---

فهم نموذج وكيل OpenClaw

يتكون كل وكيل OpenClaw من أربعة عناصر أولية: المهارات، والذاكرة، والأدوات، والمنسق.

المهارات هي الوحدات الذرية لقدرة الوكيل. المهارة هي دالة تقبل مخطط الإدخال المكتوب وترجع مخطط الإخراج المكتوب. يمكن أن تكون المهارات متزامنة أو غير متزامنة، وتعلن عن تبعياتها الخارجية بشكل صريح. أمثلة: ParseInvoice، SendSlackMessage، QueryCRMContact، GenerateReport.

الأدوات هي روابط نظام خارجية. يأتي OpenClaw مزودًا بأدوات مدمجة لواجهات REST API وقواعد البيانات وأنظمة الملفات والمتصفحات وقوائم انتظار الرسائل. يمكنك تسجيل الأدوات في بيان الوكيل وإدخالها في المهارات في وقت التشغيل عبر حقن التبعية.

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

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

يبدو المخطط الهندسي لوكيل واحد كما يلي:

User Request
     ↓
[ Orchestrator ]
     ↓ plan
[ Skill Selector ] → [ Skill Registry ]
     ↓ execute
[ Skill Instance ]
     ↓ tool calls
[ Tool Layer ] → [ External Systems ]
     ↓ result
[ Memory Writer ]
     ↓ store
[ Working / Episode / Long-Term Memory ]
     ↓ next step or done
[ Orchestrator ] → response

تستمر هذه الحلقة حتى يحدد المنسق أن الهدف قد تم استيفاؤه أو تم الوصول إلى حالة التوقف.

---

إعداد بيئة التطوير الخاصة بك

قبل كتابة مهارتك الأولى، تحتاج إلى OpenClaw SDK ووقت تشغيل الوكيل المحلي.

npm install @openclaw/sdk @openclaw/runtime @openclaw/cli
npx openclaw init my-agent --template=typescript

يقوم الأمر init بإنشاء مشروع بهذه البنية:

my-agent/
  agent.manifest.json   # Agent declaration
  skills/               # Skill implementations
  tools/                # Tool registrations
  memory/               # Memory adapter config
  tests/                # Skill and integration tests
  .openclaw/            # Local runtime state

agent.manifest.json هو الملف الأكثر أهمية. إنه يعلن عن كل ما يحتاجه OpenClaw لبدء تشغيل وكيلك:

{
  "name": "invoice-processor",
  "version": "1.0.0",
  "runtime": "node-20",
  "skills": [
    "skills/extract-line-items.ts",
    "skills/validate-vendor.ts",
    "skills/post-to-erp.ts"
  ],
  "tools": {
    "erp": { "type": "rest", "baseUrl": "${ERP_BASE_URL}", "auth": "bearer" },
    "storage": { "type": "s3", "bucket": "${DOCS_BUCKET}" }
  },
  "memory": {
    "working": { "ttl": 3600 },
    "episode": { "backend": "redis", "maxItems": 500 },
    "longTerm": { "backend": "postgres", "table": "agent_facts" }
  },
  "permissions": ["read:invoices", "write:erp", "read:vendors"]
}

يتم إدخال متغيرات البيئة في وقت التشغيل ولا يتم تخزينها مطلقًا في البيان.

---

كتابة مهارتك الأولى

المهارات تتبع عقدًا صارمًا. إنهم يقبلون كائن input المطابق للمخطط المعلن، ويتلقون tools وmemory المحقونين، ويعيدون كائن output أو يرمون SkillError مكتوبًا.

import { defineSkill, SkillError } from "@openclaw/sdk";
import { z } from "zod";

const ExtractLineItemsInput = z.object({
  documentUrl: z.string().url(),
  documentType: z.enum(["invoice", "receipt", "purchase-order"]),
});

const ExtractLineItemsOutput = z.object({
  lineItems: z.array(
    z.object({
      description: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
      total: z.number(),
    })
  ),
  confidence: z.number().min(0).max(1),
});

export const ExtractLineItems = defineSkill({
  name: "extract-line-items",
  description: "Extracts line items from a document using OCR and LLM parsing",
  input: ExtractLineItemsInput,
  output: ExtractLineItemsOutput,
  tools: ["storage"],
  async run({ input, tools, memory }) {
    const fileBuffer = await tools.storage.get(input.documentUrl);
    if (!fileBuffer) {
      throw new SkillError("DOCUMENT_NOT_FOUND", `No document at ${input.documentUrl}`);
    }

    // OCR + LLM extraction logic here
    const extracted = await runOcrPipeline(fileBuffer);

    await memory.working.set("lastExtraction", extracted);

    return {
      lineItems: extracted.items,
      confidence: extracted.confidence,
    };
  },
});

قواعد التصميم الرئيسية للمهارات:

• لا توجد آثار جانبية على الإدخال: يجب ألا تقوم المهارات بتعديل كائنات الإدخال الخاصة بها.
• الأخطاء المكتوبة: قم دائمًا بإلقاء SkillError برمز يمكن قراءته آليًا، وليس Error عامًا.
• إعلان تبعيات الأداة: يتم فقط إدخال الأدوات المعلنة في المصفوفة tools. تتسبب الأدوات غير المعلنة في حدوث خطأ في التحقق من صحة بدء التشغيل.
• الكتابة إلى الذاكرة بشكل صريح: لا تستمر المهارات في حالتها تلقائيًا. اتصل بـ memory.working.set() عمدًا.

---

إدارة الذاكرة في الممارسة العملية

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

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

// Skill A writes
await memory.working.set("vendorId", "VND-4521");

// Skill B reads
const vendorId = await memory.working.get("vendorId");

ذاكرة الحلقة عبارة عن متجر بحث دلالي. عند اكتمال المهمة، يكتب المنسق بشكل اختياري ملخصًا يتم تضمينه في ذاكرة الحلقة. يمكن للمهام المستقبلية استرجاع حلقات سابقة مماثلة لتوضيح أسبابها.

// Query past episodes
const relatedEpisodes = await memory.episode.search(
  "invoice from Acme Corp with disputed line items",
  { topK: 3, minScore: 0.75 }
);

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

// Store a learned fact
await memory.longTerm.upsert({
  key: `vendor:${vendorId}:paymentTerms`,
  value: "NET-30",
  source: "invoice-2024-0312",
  confidence: 0.9,
});

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

---

خطافات دورة الحياة لإمكانية المراقبة والتحكم

يعرض OpenClaw أربعة خطافات لدورة الحياة لكل تنفيذ للمهارة: preRun، postRun، onError، وonTimeout. قم بتسجيل الخطافات في بيان الوكيل أو برمجيًا في ملف التمهيد الخاص بك.

import { AgentRuntime } from "@openclaw/runtime";

const agent = new AgentRuntime({ manifest: "./agent.manifest.json" });

agent.useHook("preRun", async (ctx) => {
  ctx.metadata.startTime = Date.now();
  console.log(`[${ctx.skill}] starting with input keys: ${Object.keys(ctx.input)}`);
});

agent.useHook("postRun", async (ctx) => {
  const elapsed = Date.now() - ctx.metadata.startTime;
  metrics.record("skill.duration", elapsed, { skill: ctx.skill });
});

agent.useHook("onError", async (ctx) => {
  if (ctx.error.code === "RATE_LIMIT_EXCEEDED") {
    await sleep(ctx.error.retryAfterMs);
    return "retry";
  }
  alerting.send(`Skill ${ctx.skill} failed: ${ctx.error.message}`);
  return "escalate";
});

تتحكم قيمة إرجاع الخطاف onError في سلوك المُنسق: "retry" يقوم بتشغيل إعادة المحاولة (حتى الحد الأقصى الذي تم تكوينه)، ويوجه "escalate" المهمة إلى قائمة انتظار بشرية، وينهي "fail" المهمة على الفور.

---

اختبار المهارات في العزلة

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

import { testSkill } from "@openclaw/testing";
import { ExtractLineItems } from "../skills/extract-line-items";

describe("ExtractLineItems", () => {
  it("extracts items from a valid invoice", async () => {
    const result = await testSkill(ExtractLineItems, {
      input: {
        documentUrl: "s3://test-bucket/invoice-001.pdf",
        documentType: "invoice",
      },
      mocks: {
        storage: {
          get: jest.fn().mockResolvedValue(samplePdfBuffer),
        },
      },
    });

    expect(result.lineItems).toHaveLength(3);
    expect(result.confidence).toBeGreaterThan(0.8);
  });

  it("throws DOCUMENT_NOT_FOUND for missing file", async () => {
    await expect(
      testSkill(ExtractLineItems, {
        input: { documentUrl: "s3://test-bucket/missing.pdf", documentType: "invoice" },
        mocks: { storage: { get: jest.fn().mockResolvedValue(null) } },
      })
    ).rejects.toMatchObject({ code: "DOCUMENT_NOT_FOUND" });
  });
});

استخدم وضع Sandbox لاختبارات التكامل. يقوم Sandbox بإعادة تشغيل آثار الإنتاج المسجلة وفقًا لرمز مهاراتك الحالي، ويلتقط التراجعات قبل أن تصل إلى الأنظمة المباشرة.

npx openclaw sandbox replay --trace=traces/invoice-20240315.json

---

النشر إلى الإنتاج

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

FROM openclaw/runtime:node-20
WORKDIR /agent
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN npx openclaw build
CMD ["npx", "openclaw", "serve", "--workers=4"]

بالنسبة لسيناريوهات الإنتاجية العالية، قم بتكوين تجمع الوكلاء باستخدام قواعد القياس التلقائي. يعرض وقت تشغيل OpenClaw مقاييس Prometheus عند /metrics لعمق قائمة الانتظار، والنسب المئوية لزمن وصول المهارة، ومعدلات الخطأ، واستخدام الذاكرة - قم بتوصيلها بمكدس التنبيهات الخاص بك.

قائمة مراجعة الإنتاج قبل بدء التشغيل:

• جميع متغيرات البيئة موجودة في مدير الأسرار (AWS Secrets Manager، HashiCorp Vault)، وليس ملفات .env.
• تم تكوين تجمع الاتصالات في الواجهات الخلفية للذاكرة (Redis وPostgreSQL).
• يتوافق الإعداد maxConcurrentTasks مع سعة البنية الأساسية لديك.
• حدود الأسعار على مكالمات الأدوات الخارجية تتطابق مع حدود واجهة برمجة تطبيقات البائع.
• تم تكوين قائمة انتظار للأحرف الميتة للمهام التي تستنزف عمليات إعادة المحاولة.
• تم تمكين التتبع الموزع (OpenTelemetry) وتتدفق الآثار إلى منصة المراقبة الخاصة بك.

---

الأسئلة المتداولة

كيف يقرر منسق OpenClaw المهارة التي سيتم تشغيلها بعد ذلك؟

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

هل يمكن لمهارة ما أن تستدعي مهارة أخرى مباشرة؟

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

ماذا يحدث عندما تتعطل واجهة برمجة التطبيقات الخارجية أثناء تنفيذ المهارات؟

الخطاف onError يعترض الفشل. إذا أعاد الخطاف "retry"، فسينتظر المنسق الفاصل الزمني للتراجع الذي تم تكوينه ويعيد محاولة المهارة. بعد استنفاد عمليات إعادة المحاولة، تنتقل المهمة إلى قائمة انتظار الأحرف الميتة. إذا كانت لديك مهارة احتياطية مسجلة لنفس القدرة، فسيقوم المنسق بتجربتها قبل الاستسلام. يتم الاحتفاظ بحالة المهمة الجزئية في الذاكرة العاملة حتى يمكن استئناف المهمة من آخر مهارة ناجحة.

كيف تتعامل مع الأسرار التي تحتاجها المهارات في وقت التشغيل؟

تتم تهيئة الأدوات المعلنة في بيان الوكيل باستخدام بيانات الاعتماد عند بدء التشغيل، وليس لكل مهارة. يقوم مدير الأسرار الخاص بك بملء متغيرات البيئة المشار إليها في البيان (${ERP_BASE_URL}، ${DOCS_BUCKET}، وما إلى ذلك) عند بدء تشغيل الحاوية. لا ترى المهارات أبدًا بيانات اعتماد أولية، فهي تتفاعل مع مثيلات الأداة التي تم التحقق منها مسبقًا والتي يتم إدخالها خلال وقت التشغيل.

هل هناك حد لعدد المهارات التي يمكن أن يتمتع بها الوكيل؟

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

هل يمكن لوكلاء OpenClaw العمل داخل الشركة دون تبعيات سحابية؟

نعم. OpenClaw لا يعتمد على السحابة. يمكن تكوين وقت التشغيل والواجهات الخلفية للذاكرة وطبقة الأدوات لاستخدام البنية التحتية المحلية. يمكن تشغيل Redis محليًا، ويمكن أن تشير الواجهة الخلفية للذاكرة طويلة المدى إلى مثيل PostgreSQL محليًا، ويمكن أن تستهدف عمليات تكامل الأدوات واجهات برمجة التطبيقات الداخلية. المكالمة الخارجية الوحيدة هي لموفر LLM لاستدلال المنسق - يمكنك تكوين هذا لاستخدام LLM داخل الشركة إذا لزم الأمر.

كيف يمكنك إصدار مهارات الوكيل دون تعطيل المهام الجارية؟

يتم إصدار المهارات في بيان الوكيل باستخدام الإصدار الدلالي. يدعم وقت التشغيل تشغيل إصدارات متعددة من المهارات في وقت واحد أثناء النشر المستمر. تستمر المهام أثناء الرحلة في استخدام إصدار المهارة الذي بدأت به؛ مهام جديدة تلتقط الإصدار الأحدث. يتطلب كسر التغييرات في مخططات الإدخال/الإخراج للمهارة تحديثًا رئيسيًا للإصدار وخطة ترحيل لأي وكيل يستهلك مخرجات تلك المهارة.

---

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

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

توفر خدمة ECOSIRE خدمة OpenClaw Custom Skills تطويرًا شاملاً للوكيل: تحليل المتطلبات، وبنية المهارات، والتكامل مع أنظمتك الحالية، والاختبار، والنشر، والتحسين المستمر. قام فريقنا ببناء وكلاء OpenClaw لمعالجة المستندات وأتمتة تخطيط موارد المؤسسات (ERP) ودعم العملاء والتحليل المالي والمزيد.

تحدث إلى أحد متخصصي OpenClaw لمناقشة متطلبات التشغيل الآلي الخاصة بك والحصول على خريطة طريق مخصصة للتطوير.