Plugin خطافات الويب

تضيف إضافة Webhooks مسارات HTTP مصادقًا عليها بحيث يمكن لنظام خارجي موثوق (Zapier أو n8n أو مهمة CI أو خدمة داخلية) إنشاء TaskFlows مُدارة في OpenClaw والتحكم فيها عبر HTTP، من دون كتابة إضافة مخصصة.

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

ضبط المسارات

عيّن الإعدادات ضمن plugins.entries.webhooks.config:

{  plugins: {    entries: {      webhooks: {        enabled: true,        config: {          routes: {            zapier: {              path: "/plugins/webhooks/zapier",              sessionKey: "agent:main:main",              secret: {                source: "env",                provider: "default",                id: "OPENCLAW_WEBHOOK_SECRET",              },              controllerId: "webhooks/zapier",              description: "Zapier TaskFlow bridge",            },          },        },      },    },  },}

حقول المسار:

يقبل secret سلسلة نصية عادية أو SecretRef: ‏{ source: "env" | "file" | "exec", provider: "default", id: "..." }.

يُسجَّل كل مسار مضبوط عند بدء التشغيل بغض النظر عما إذا كان سرّه قابلًا للحل حاليًا. لا يؤدي تعذّر حل السر إلى تعطيل المسار أو تخطيه؛ إذ تفشل مصادقة الطلبات إليه (401) إلى أن يصبح حل السر ممكنًا. يُعاد حل قيم SecretRef مع كل طلب، لذا يسري تدوير السر الأساسي (متغير بيئة أو ملف أو مخرجات تنفيذ) من دون إعادة تشغيل Gateway.

نموذج الأمان

يعمل كل مسار بصلاحيات TaskFlow الخاصة بـ sessionKey المضبوط له: ويمكنه فحص أي TaskFlow تملكها تلك الجلسة وتعديلها. يمر الوصول إلى TaskFlow دائمًا عبر api.runtime.tasks.managedFlows.bindSession(...)، لذلك لا يمكن للمسار مطلقًا العمل خارج جلسته المرتبطة. للحد من نطاق الضرر:

• استخدم سرًا قويًا وفريدًا لكل مسار.
• فضّل SecretRef على سر نصي صريح مضمن.
• اربط المسارات بأضيق جلسة تلائم سير العمل.
• اكشف فقط مسار Webhook المحدد الذي تحتاج إليه.

ترتيب معالجة الطلبات لكل مسار: التحقق من طريقة HTTP (POST فقط) ومن Content-Type: application/json، ثم تحديد المعدل بنافذة ثابتة (120 طلبًا لكل نافذة مدتها 60 ثانية لكل مفتاح مؤلف من المسار وعنوان IP للعميل، مع تتبع ما يصل إلى 4,096 مفتاحًا)، ثم تحديد الطلبات قيد التنفيذ (8 طلبات متزامنة لكل مفتاح، مع تتبع ما يصل إلى 4,096 مفتاحًا)، ثم المصادقة بالسر المشترك، ثم قراءة نص JSON بحد أقصى 256 كيلوبايت وخلال 15 ثانية. الطلبات التي تفشل في تحقق مبكر لا تصل مطلقًا إلى عمليات التحقق اللاحقة.

تنسيق الطلب

أرسل طلبات POST مع Content-Type: application/json وأحد الترويسَتين Authorization: Bearer <secret> أو x-openclaw-webhook-secret: <secret>:

curl -X POST https://gateway.example.com/plugins/webhooks/zapier \  -H 'Content-Type: application/json' \  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \  -d '{"action":"create_flow","goal":"Review inbound queue"}'

الإجراءات المدعومة

تتطلب إجراءات التعديل (set_waiting وresume_flow وfinish_flow وfail_flow وrequest_cancel) الحقلين flowId وexpectedRevision للتحكم المتفائل في التزامن؛ وتعيد المراجعة القديمة 409 revision_conflict.

create_flow

{  "action": "create_flow",  "goal": "Review inbound queue",  "status": "queued",  "notifyPolicy": "done_only"}

run_task

قيم runtime المسموح بها: subagent وacp. لا تكون startedAt وlastEventAt وprogressSummary صالحة إلا عندما تكون status هي "running"؛ ويؤدي إرسالها مع أي حالة أخرى إلى إرجاع 400 invalid_request.

{  "action": "run_task",  "flowId": "flow_123",  "runtime": "acp",  "childSessionKey": "agent:main:acp:worker",  "task": "Inspect the next message batch"}

بنية الاستجابة

{  "ok": true,  "routeId": "zapier",  "result": {}}

{  "ok": false,  "routeId": "zapier",  "code": "not_found",  "error": "TaskFlow not found.",  "result": {}}

لا تتضمن عروض التدفقات والمهام مطلقًا بيانات وصفية عن المالك/الجلسة، ولذلك لا يمكن للاستجابات تسريب sessionKey المرتبط بالمسار. تتضمن قيم code: not_found وnot_managed وrevision_conflict وpersist_failed وcancel_requested وcancel_pending وterminal وinvalid_request وrequest_rejected، بالإضافة إلى رموز احتياطية خاصة بالإجراء (mutation_rejected وcreate_rejected وtask_not_created وcancel_rejected) عندما يُرفض تعديل لسبب لا تغطيه الرموز المسماة أعلاه.

ذو صلة

• الخطافات - الخطافات الداخلية المستندة إلى الأحداث مقارنةً بجسر TaskFlow هذا المستند إلى HTTP
• Webhooks الخاصة بـ Gateway (إعداد hooks.*) - ميزة منفصلة لنقطة نهاية HTTP عامة في Gateway؛ وليست مماثلة لمسارات هذه الإضافة
• حزمة SDK لوقت تشغيل الإضافة
• Webhooks في CLI