---
read_when:
    - تريد تمكين وضع الكود في OpenClaw لتشغيل وكيل
    - يجب شرح سبب اختلاف وضع الكود عن وضع الكود في Codex
    - أنت تراجع عقد `exec/wait`، أو صندوق عزل QuickJS-WASI، أو تحويل TypeScript، أو جسر فهرس الأدوات المخفي
    - أنت تضيف أو تراجع تكاملاً لسجل مساحة أسماء داخلي لوضع الكود
sidebarTitle: Code mode
summary: 'وضع الكود في OpenClaw: واجهة أدوات exec/wait اختيارية التفعيل مدعومة بـ QuickJS-WASI وفهرس أدوات مخفي مقيّد بنطاق التشغيل'
title: وضع الكود
x-i18n:
    generated_at: "2026-06-27T18:30:46Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 859d56eb09e21c9277961ac5178c1458ce669de114e8cc3f2c8d4b104f428a74
    source_path: reference/code-mode.md
    workflow: 16
---

وضع الكود هو ميزة تجريبية في وقت تشغيل وكيل OpenClaw. وهو متوقف
افتراضيا. عند تفعيله، يغير OpenClaw ما يراه النموذج لتشغيلة واحدة:
بدلا من كشف كل مخطط أداة مفعل مباشرة، لا يرى النموذج سوى
`exec` و`wait`.

توثق هذه الصفحة وضع الكود في OpenClaw. وهو ليس وضع Codex Code mode. تشترك
الميزتان في الاسم، لكنهما تنفذان عبر أوقات تشغيل مختلفة وتكشفان
عقود `exec` مختلفة:

- Codex Code Mode مفعل لخيوط خادم تطبيق Codex ما لم تعطل سياسة الأدوات
  المقيدة وضع الكود الأصلي. يعمل ضمن حاضنة البرمجة في Codex،
  حيث يكتب النموذج أوامر الصدفة من خلال عقد `exec.command`.
- وضع الكود في OpenClaw معطل ما لم يتم ضبط `tools.codeMode.enabled: true`.
  يعمل ضمن وقت تشغيل الوكيل العام في OpenClaw، حيث يكتب النموذج
  برامج JavaScript أو TypeScript من خلال عقد `exec.code`.

Codex Code Mode والبحث الديناميكي عن الأدوات الأصلي في Codex هما سطحان
مستقران في حاضنة Codex. وضع الكود في OpenClaw هو محول تجريبي مملوك لـ OpenClaw
لسطح الأدوات لتشغيلات OpenClaw العامة. يستخدم `quickjs-wasi`، وكتالوج أدوات
OpenClaw مخفي، ومنفذ أدوات OpenClaw العادي.

## ما هذا؟

يتيح وضع الكود في OpenClaw للنموذج كتابة برنامج JavaScript أو TypeScript صغير
بدلا من الاختيار مباشرة من قائمة طويلة من الأدوات.

عندما يكون وضع الكود نشطا:

- قائمة الأدوات المرئية للنموذج هي بالضبط `exec` و`wait`.
- يقيم `exec` JavaScript أو TypeScript مولدا من النموذج في عامل
  QuickJS-WASI مقيد.
- تكون أدوات OpenClaw العادية مخفية عن مطالبة النموذج ومكشوفة داخل
  برنامج الضيف عبر `ALL_TOOLS` و`tools`.
- يمكن لكود الضيف البحث في الكتالوج المخفي، ووصف أداة، واستدعاء أداة
  من خلال مسار تنفيذ OpenClaw نفسه المستخدم في دورات الوكيل العادية.
- تجمع أدوات MCP تحت مساحة الاسم `MCP`. في وضع الكود، مساحة الاسم هذه
  هي الطريقة الوحيدة المدعومة لاستدعاء أدوات MCP.
- يستأنف `wait` تشغيلة وضع كود معلقة عندما تظل استدعاءات الأدوات المتداخلة
  قيد الانتظار.

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

## لماذا هذا جيد؟

يجعل وضع الكود كتالوجات الأدوات الكبيرة أسهل استخداما للنماذج.

- سطح مطالبة أصغر: يتلقى المزودون أداتي تحكم بدلا من عشرات أو مئات
  مخططات الأدوات الكاملة.
- تنسيق أفضل: يمكن للنموذج استخدام الحلقات، والدمج، والتحويلات الصغيرة،
  والمنطق الشرطي، واستدعاءات الأدوات المتداخلة المتوازية داخل خلية كود واحدة.
- محايد للمزودين: يعمل مع أدوات OpenClaw وPlugin وMCP والعميل دون
  الاعتماد على تنفيذ كود أصلي لدى المزود.
- تظل السياسة الحالية نافذة: ما زالت استدعاءات الأدوات المتداخلة تمر عبر
  سياسة OpenClaw، والموافقات، والخطافات، وسياق الجلسة، ومسارات التدقيق.
- نمط فشل واضح: عندما يكون وضع الكود مفعلا صراحة ويكون وقت التشغيل غير
  متاح، يفشل OpenClaw بإغلاق آمن بدلا من الرجوع إلى كشف واسع ومباشر للأدوات.

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

## كيفية تفعيله

أضف `tools.codeMode.enabled: true` إلى إعداد الوكيل أو وقت التشغيل:

```json5
{
  tools: {
    codeMode: {
      enabled: true,
    },
  },
}
```

يقبل الاختصار أيضا:

```json5
{
  tools: {
    codeMode: true,
  },
}
```

يبقى وضع الكود متوقفا عندما يكون `tools.codeMode` محذوفا، أو `false`، أو كائنا
بلا `enabled: true`.

عند استخدام وكلاء معزولين مع خوادم MCP مضبوطة، تأكد أيضا من أن سياسة أدوات
العزل تسمح بـ Plugin MCP المضمن، مثلا عبر
`tools.sandbox.tools.alsoAllow: ["bundle-mcp"]`. راجع
[الإعداد - الأدوات والمزودون المخصصون](/ar/gateway/config-tools#mcp-and-plugin-tools-inside-sandbox-tool-policy).

استخدم حدودا صريحة عندما تريد قيودا أشد:

```json5
{
  tools: {
    codeMode: {
      enabled: true,
      timeoutMs: 10000,
      memoryLimitBytes: 67108864,
      maxOutputBytes: 65536,
      maxSnapshotBytes: 10485760,
      maxPendingToolCalls: 16,
      snapshotTtlSeconds: 900,
      searchDefaultLimit: 8,
      maxSearchLimit: 50,
    },
  },
}
```

لتأكيد شكل حمولة النموذج أثناء التصحيح، شغل Gateway مع تسجيل موجه:

```bash
OPENCLAW_DEBUG_CODE_MODE=1 \
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 \
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools \
openclaw gateway
```

مع نشاط وضع الكود، يجب أن تكون أسماء الأدوات المواجهة للنموذج المسجلة هي
`exec` و`wait`. إذا كنت تحتاج إلى حمولة المزود المنقحة، فأضف
`OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted` لجلسة تصحيح قصيرة.

## جولة تقنية

يصف باقي هذه الصفحة عقد وقت التشغيل وتفاصيل التنفيذ.
وهو مخصص للمشرفين، ومؤلفي Plugin الذين يصححون كشف الأدوات، والمشغلين
الذين يتحققون من عمليات نشر عالية المخاطر.

## حالة وقت التشغيل

- وقت التشغيل: [`quickjs-wasi`](https://github.com/vercel-labs/quickjs-wasi).
- الحالة الافتراضية: معطل.
- الاستقرار: سطح OpenClaw تجريبي؛ وضع Codex Code mode سطح منفصل مستقر
  في حاضنة Codex.
- السطح الهدف: تشغيلات وكيل OpenClaw العامة.
- الموقف الأمني: كود النموذج عدائي.
- الوعد الموجه للمستخدم: لا يؤدي تفعيل وضع الكود أبدا إلى رجوع صامت إلى كشف
  واسع ومباشر للأدوات.

## النطاق

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

ضمن النطاق:

- تعريفات أداتي `exec` و`wait` المرئيتين للنموذج
- بناء كتالوج الأدوات المخفي
- تنفيذ ضيف JavaScript وTypeScript
- وقت تشغيل عامل QuickJS-WASI
- استدعاءات المضيف للبحث في الكتالوج، ووصف المخطط، واستدعاء الأداة
- حالة قابلة للاستئناف لبرامج الضيف المعلقة
- حدود الإخراج، والمهلة، والذاكرة، والاستدعاءات المعلقة، واللقطات
- القياس عن بعد وإسقاط المسار لاستدعاءات الأدوات المتداخلة

خارج النطاق:

- تنفيذ الكود البعيد الأصلي لدى المزود
- دلالات تنفيذ الصدفة
- تغيير تفويض الأدوات الحالي
- سكربتات مستمرة يؤلفها المستخدم
- الوصول إلى مدير الحزم، أو الملفات، أو الشبكة، أو الوحدات في كود الضيف
- إعادة الاستخدام المباشر لداخليات وضع Codex Code mode

تظل الأدوات المملوكة للمزود مثل علب عزل Python البعيدة أدوات منفصلة. راجع
[تنفيذ الكود](/ar/tools/code-execution).

## المصطلحات

**وضع الكود** هو وضع وقت تشغيل OpenClaw الذي يخفي أدوات النموذج العادية
ولا يكشف سوى `exec` و`wait`.

**وقت تشغيل الضيف** هو آلة JavaScript الافتراضية QuickJS-WASI التي تقيم كود النموذج.

**جسر المضيف** هو سطح الاستدعاء الضيق المتوافق مع JSON من كود الضيف
راجعا إلى OpenClaw.

**الكتالوج** هو قائمة الأدوات الفعالة ضمن نطاق التشغيلة بعد سياسة الأدوات
العادية، وحل Plugin وMCP وأدوات العميل.

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

**اللقطة** هي حالة آلة QuickJS-WASI الافتراضية المسلسلة المحفوظة لكي يستطيع
`wait` متابعة تشغيلة وضع كود معلقة.

## الإعداد

`tools.codeMode.enabled` هو بوابة التفعيل. لا يؤدي تعيين حقول وضع الكود الأخرى
إلى تفعيل الميزة.

الحقول المدعومة:

- `enabled`: قيمة منطقية. الافتراضي `false`. يفعل وضع الكود فقط عندما تكون `true`.
- `runtime`: `"quickjs-wasi"`. وقت التشغيل الوحيد المدعوم.
- `mode`: `"only"`. يكشف `exec` و`wait`، ويخفي أدوات النموذج العادية.
- `languages`: مصفوفة من `"javascript"` و`"typescript"`. يتضمن الافتراضي
  كليهما.
- `timeoutMs`: حد زمني فعلي لعملية `exec` أو `wait` واحدة. الافتراضي `10000`.
  حد وقت التشغيل: من `100` إلى `60000`.
- `memoryLimitBytes`: حد كومة QuickJS. الافتراضي `67108864`. حد وقت التشغيل:
  من `1048576` إلى `1073741824`.
- `maxOutputBytes`: حد للنص المعاد، وJSON، والسجلات. الافتراضي `65536`.
  حد وقت التشغيل: من `1024` إلى `10485760`.
- `maxSnapshotBytes`: حد للقطات الآلة الافتراضية المسلسلة. الافتراضي `10485760`.
  حد وقت التشغيل: من `1024` إلى `268435456`.
- `maxPendingToolCalls`: حد لاستدعاءات الأدوات المتداخلة المتزامنة. الافتراضي `16`.
  حد وقت التشغيل: من `1` إلى `128`.
- `snapshotTtlSeconds`: مدة إمكانية استئناف آلة افتراضية معلقة. الافتراضي `900`.
  حد وقت التشغيل: من `1` إلى `86400`.
- `searchDefaultLimit`: عدد نتائج البحث الافتراضي في الكتالوج المخفي. الافتراضي `8`.
  يقيد وقت التشغيل هذا إلى `maxSearchLimit`.
- `maxSearchLimit`: الحد الأقصى لعدد نتائج البحث في الكتالوج المخفي. الافتراضي `50`.
  حد وقت التشغيل: من `1` إلى `50`.

إذا كان وضع الكود مفعلا لكن QuickJS-WASI لا يمكن تحميله، يفشل OpenClaw بإغلاق
آمن لتلك التشغيلة. ولا يكشف الأدوات العادية بصمت كرجوع احتياطي.

## التفعيل

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

ترتيب التفعيل:

1. حل الوكيل، والنموذج، والمزود، والعزل، والقناة، والمرسل، وسياسة التشغيلة.
2. بناء قائمة أدوات OpenClaw الفعالة.
3. إضافة أدوات Plugin وMCP والعميل المؤهلة.
4. تطبيق سياسة السماح والمنع.
5. إذا كانت `tools.codeMode.enabled` خطأ، فتابع مع كشف الأدوات العادي.
6. إذا كانت مفعلة وكانت الأدوات نشطة للتشغيلة، فسجل الأدوات الفعالة في
   كتالوج وضع الكود.
7. أزل كل الأدوات العادية من قائمة الأدوات المرئية للنموذج.
8. أضف `exec` و`wait` الخاصتين بوضع الكود.

التشغيلات التي لا تحتوي عمدا على أدوات، مثل استدعاءات النموذج الخام،
أو `disableTools`، أو قائمة سماح فارغة، لا تفعل سطح وضع الكود حتى لو كان
الإعداد يحتوي على `tools.codeMode.enabled: true`.

كتالوج وضع الكود ضمن نطاق التشغيلة. يجب ألا يسرب أدوات من وكيل، أو جلسة،
أو مرسل، أو تشغيلة أخرى.

## الأدوات المرئية للنموذج

عندما يكون وضع الكود نشطا، يرى النموذج بالضبط هاتين الأداتين على المستوى الأعلى:

- `exec`
- `wait`

كل الأدوات المفعلة الأخرى تكون مخفية من قائمة الأدوات المواجهة للنموذج ومسجلة
في كتالوج وضع الكود.

ينبغي أن يستخدم النموذج `exec` لتنسيق الأدوات، ودمج البيانات، والحلقات،
والاستدعاءات المتداخلة المتوازية، والتحويلات المنظمة. وينبغي أن يستخدم النموذج
`wait` فقط عندما يعيد `exec` نتيجة `waiting` قابلة للاستئناف.

## `exec`

يبدأ `exec` خلية وضع كود ويعيد نتيجة واحدة. كود الإدخال مولد من النموذج
ويجب التعامل معه كعدائي.

الإدخال:

```typescript
type CodeModeExecInput = {
  code?: string;
  command?: string;
  language?: "javascript" | "typescript";
};
```

قواعد الإدخال:

- يجب أن يكون أحد `code` أو `command` غير فارغ.
- `code` هو الحقل الموثق والموجه للنموذج.
- يقبل `command` كاسم بديل متوافق مع exec لسياسات الخطافات وإعادة الكتابة
  الموثوقة؛ عند وجودهما معا، يجب أن تتطابق القيمتان.
- تتضمن أحداث خطاف `exec` الخارجية لوضع الكود `toolKind: "code_mode_exec"`
  وتتضمن `toolInputKind: "javascript" | "typescript"` عندما تكون لغة الإدخال
  معروفة، بحيث تستطيع السياسات تمييز خلايا وضع الكود عن استدعاءات `exec`
  بأسلوب الصدفة التي تشترك في اسم الأداة نفسه.
- القيمة الافتراضية لـ `language` هي `"javascript"`.
- إذا كانت `language` هي `"typescript"`، يقوم OpenClaw بالتحويل قبل التقييم.
- يرفض `exec` أنماط `import`، و`require`، والاستيراد الديناميكي، ومحمل الوحدات
  في v1.
- لا يكشف `exec` تنفيذ `exec` العادي للصدفة بشكل تكراري.

النتيجة:

```typescript
type CodeModeResult = CodeModeCompletedResult | CodeModeWaitingResult | CodeModeFailedResult;

type CodeModeCompletedResult = {
  status: "completed";
  value: unknown;
  output?: CodeModeOutput[];
  telemetry: CodeModeTelemetry;
};

type CodeModeWaitingResult = {
  status: "waiting";
  runId: string;
  reason: "pending_tools" | "yield";
  pendingToolCalls?: CodeModePendingToolCall[];
  output?: CodeModeOutput[];
  telemetry: CodeModeTelemetry;
};

type CodeModeFailedResult = {
  status: "failed";
  error: string;
  code?: CodeModeErrorCode;
  output?: CodeModeOutput[];
  telemetry: CodeModeTelemetry;
};
```

يعيد `exec` الحالة `waiting` عندما تعلق آلة QuickJS الافتراضية مع حالة قابلة
للاستئناف ما زالت تحتاج إلى متابعة مرئية للنموذج. تتضمن النتيجة `runId` من أجل
`wait`. تستنزف استدعاءات جسر مساحة الاسم، بما في ذلك استدعاءات مساحة اسم MCP،
تلقائيا داخل استدعاء `exec`/`wait` نفسه عندما تكون جاهزة، لذلك يمكن لكتلة كود
موجزة فحص `$api()` واستدعاء أداة MCP دون فرض استدعاء أداة نموذج واحد لكل
انتظار مساحة اسم.

`exec` تُرجع `completed` فقط عندما لا تكون لدى آلة الضيف الافتراضية أي أعمال معلقة وتكون
القيمة النهائية متوافقة مع JSON بعد تشغيل محوّل مخرجات OpenClaw.

## `wait`

تواصل `wait` آلة افتراضية معلّقة في وضع الشيفرة.

الإدخال:

```typescript
type CodeModeWaitInput = {
  runId: string;
};
```

المخرج هو اتحاد `CodeModeResult` نفسه الذي تُرجعه `exec`.

توجد `wait` لأن أدوات OpenClaw المتداخلة قد تكون بطيئة أو تفاعلية أو خاضعة
للموافقة أو تبث تحديثات جزئية. يجب ألا يحتاج النموذج إلى إبقاء استدعاء `exec`
طويل واحد مفتوحًا بينما ينتظر المضيف عملًا خارجيًا.

لقطة QuickJS-WASI والاستعادة هما آلية الاستئناف في v1:

1. تقيّم `exec` الشيفرة حتى الاكتمال أو الفشل أو التعليق.
2. عند التعليق، يأخذ OpenClaw لقطة لآلة QuickJS الافتراضية ويسجل عمل المضيف
   المعلق.
3. عندما يستقر العمل المعلق، تستعيد `wait` لقطة الآلة الافتراضية.
4. يعيد OpenClaw تسجيل استدعاءات المضيف الراجعة بأسماء مستقرة.
5. يسلّم OpenClaw نتائج الأدوات المتداخلة إلى الآلة الافتراضية المستعادة.
6. يفرّغ OpenClaw مهام QuickJS المعلقة.
7. تُرجع `wait` النتيجة `completed` أو `failed` أو نتيجة `waiting` أخرى.

اللقطات هي حالة تشغيل، وليست عناصر أثرية للمستخدم. وهي محدودة الحجم، ومنتهية
الصلاحية، ومقيّدة بنطاق التشغيل والجلسة اللذين أنشآها.

تفشل `wait` عندما:

- يكون `runId` غير معروف.
- تكون اللقطة منتهية الصلاحية.
- يكون التشغيل الأصل أو الجلسة قد أُجهض.
- لا يكون المستدعي ضمن نطاق التشغيل/الجلسة نفسه.
- تفشل استعادة QuickJS-WASI.
- تتجاوز الاستعادة الحدود المضبوطة.

## واجهة API لبيئة تشغيل الضيف

تعرض بيئة تشغيل الضيف واجهة API عامة صغيرة:

```typescript
declare const ALL_TOOLS: ToolCatalogEntry[];
declare const tools: ToolCatalog;
declare const MCP: Record<string, unknown>;
declare const namespaces: Record<string, unknown>;

declare function text(value: unknown): void;
declare function json(value: unknown): void;
declare function yield_control(reason?: string): Promise<void>;
```

`ALL_TOOLS` هي بيانات وصفية مضغوطة للفهرس المقيّد بنطاق التشغيل. لا تحتوي
المخططات الكاملة افتراضيًا.

```typescript
type ToolCatalogEntry = {
  id: string;
  name: string;
  label?: string;
  description: string;
  source: "openclaw" | "plugin" | "mcp" | "client";
  sourceName?: string;
};
```

لا يُحمّل المخطط الكامل إلا عند الطلب:

```typescript
type ToolCatalogEntryWithSchema = ToolCatalogEntry & {
  parameters: unknown;
};
```

مساعدات الفهرس:

```typescript
type ToolCatalog = {
  search(query: string, options?: { limit?: number }): Promise<ToolCatalogEntry[]>;
  describe(id: string): Promise<ToolCatalogEntryWithSchema>;
  call(id: string, input?: unknown): Promise<unknown>;
  [safeToolName: string]: unknown;
};
```

لا تُثبّت دوال الأدوات المختصرة إلا للأسماء الآمنة غير الملتبسة:

```typescript
const files = await tools.search("read local file");
const fileRead = await tools.describe(files[0].id);
const content = await tools.call(fileRead.id, { path: "README.md" });

// If the hidden catalog has an unambiguous `web_search` entry:
const hits = await tools.web_search({ query: "OpenClaw code mode" });
```

إدخالات فهرس MCP غير قابلة للاستدعاء عبر `tools.call(...)` أو الدوال المختصرة
في وضع الشيفرة. تُعرَض فقط من خلال مساحة الأسماء `MCP` المولّدة. تتوفر ملفات
تصريح بأسلوب TypeScript من خلال سطح الملفات الافتراضي `API` للقراءة فقط، لكي
تتمكن الوكلاء من فحص تواقيع MCP دون إضافة مخططات MCP إلى الموجه:

```typescript
const files = await API.list("mcp");
const githubApi = await API.read("mcp/github.d.ts");

const issue = await MCP.github.createIssue({
  owner: "openclaw",
  repo: "openclaw",
  title: "Investigate gateway logs",
});

const snapshot = await MCP.chromeDevtools.takeSnapshot({ output: "markdown" });
const resource = await MCP.docs.resources.read({ uri: "memo://one" });
const prompt = await MCP.docs.prompts.get({
  name: "brief",
  arguments: { topic: "release" },
});
```

تُرجع `API.read("mcp/<server>.d.ts")` تصريحات مضغوطة مستنتجة من بيانات وصفية
لأداة MCP:

```typescript
type McpToolResult = {
  content?: unknown[];
  structuredContent?: unknown;
  isError?: boolean;
  [key: string]: unknown;
};

declare namespace MCP.github {
  /** Return this TypeScript-style API header. */
  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;

  /**
   * Create a GitHub issue.
   * @param owner Repository owner
   * @param repo Repository name
   * @param title Issue title
   */
  function createIssue(input: {
    owner: string;
    repo: string;
    title: string;
    body?: string;
  }): Promise<McpToolResult>;
}
```

ملفات التصريح افتراضية، وليست ملفات مكتوبة ضمن مساحة العمل أو دليل الحالة.
لكل استدعاء `exec` في وضع الشيفرة، يبني OpenClaw فهرس الأدوات المقيّد بنطاق
التشغيل، ويبقي إدخالات MCP المرئية، ويصيّر `mcp/index.d.ts` إضافة إلى تصريح
`mcp/<server>.d.ts` واحد لكل خادم مرئي، ويحقن ذلك الجدول الصغير للقراءة فقط في
عامل QuickJS. لا ترى شيفرة الضيف إلا الكائن `API`: تُرجع `API.list(prefix?)`
بيانات وصفية للملف وتُرجع `API.read(path)` محتوى التصريح المحدد. تُرفض المسارات
غير المعروفة ومقاطع `.` / `..`.

يبقي هذا مخططات MCP الكبيرة خارج موجه النموذج. يتعلم الوكيل وجود واجهة API
الافتراضية من وصف أداة `exec`، ويقرأ فقط ملف التصريح المطلوب، ثم يستدعي
`MCP.<server>.<tool>()` بوسيط كائن واحد. تبقى `MCP.<server>.$api()` متاحة
كخيار احتياطي مضمن عندما يحتاج الوكيل إلى استجابة مخطط لأداة واحدة داخل البرنامج.

يجب ألا تعرض بيئة تشغيل الضيف كائنات المضيف مباشرة. تعبر المدخلات والمخرجات
الجسر كقيم متوافقة مع JSON وبحدود حجم صريحة.

## مساحات الأسماء الداخلية

تمنح مساحات الأسماء الداخلية وضع الشيفرة واجهة API موجزة للمجال دون إضافة
المزيد من الأدوات المرئية للنموذج. يمكن لتكامل مملوك للمحمّل تسجيل مساحة أسماء
مثل `Issues` أو `Fictions` أو `Calendar`؛ ثم تستدعي شيفرة الضيف مساحة الأسماء
تلك داخل برنامج QuickJS بينما لا يزال OpenClaw يعرض للنموذج سوى `exec` و`wait`.

مساحات الأسماء داخلية في الوقت الحالي. لا توجد واجهة API عامة لمساحات أسماء
Plugin SDK: تحتاج مساحات أسماء Plugins الخارجية إلى عقد مملوك للمحمّل بحيث لا
تنحرف هوية Plugin والبيانات الظاهرة المثبتة وحالة المصادقة وواصفات الفهرس
المخزنة مؤقتًا عن أدوات Plugin التي تدعم مساحة الأسماء. لا يملك وضع الشيفرة
في النواة إلا صندوق العزل، والتسلسل، وبوابة الفهرس، وإرسال الجسر.

يمكن لشيفرة الضيف بعد ذلك استخدام العام المباشر أو خريطة `namespaces`:

```javascript
const open = await Issues.list({ state: "open" });
const alsoOpen = await namespaces.Issues.list({ state: "open" });
return { count: open.length, alsoCount: alsoOpen.length };
```

### دورة حياة السجل

سجل مساحة الأسماء محلي للعملية ومفهرس بمعرّف مساحة الأسماء. يتبع التشغيل
النموذجي هذا المسار:

1. يستدعي محمّل موثوق `registerCodeModeNamespaceForPlugin(pluginId, registration)`.
2. ينشئ وضع الشيفرة `ToolSearchRuntime` المخفي للتشغيل ويقرأ فهرسه المقيّد
   بنطاق التشغيل.
3. تُبقي `createCodeModeNamespaceRuntime(ctx, catalog)` فقط التسجيلات التي تكون
   كل `requiredToolNames` فيها مرئية ومملوكة لنفس `pluginId`.
4. تستدعي كل مساحة أسماء مرئية `createScope(ctx)` للتشغيل الحالي. يتلقى النطاق
   سياق التشغيل مثل `agentId` و`sessionKey` و`sessionId` و`runId` والإعدادات
   وحالة الإجهاض.
5. تُسلسَل بيانات النطاق إلى واصف عادي وتُحقن في QuickJS كعموميات مباشرة و
   `namespaces.<globalName>`.
6. تُعلّق استدعاءات الضيف عبر جسر العامل، وتحل مسار مساحة الأسماء على المضيف،
   وتربط الاستدعاء بأداة فهرس مصرّح بها ومملوكة لـ Plugin، وتنفذ تلك الأداة عبر
   `ToolSearchRuntime.call`.
7. يفرّغ OpenClaw تلقائيًا استدعاءات جسر مساحة الأسماء الجاهزة داخل استدعاء
   أداة `exec`/`wait` النشط. إذا ظل عمل مساحة الأسماء معلقًا عند المهلة أو
   أعطى الضيف التحكم صراحة، تستأنف `wait` بيئة تشغيل مساحة الأسماء نفسها لاحقًا.
8. يستدعي تراجع Plugin أو إلغاء تثبيته `clearCodeModeNamespacesForPlugin(pluginId)`
   حتى لا تبقى العموميات القديمة بعد فشل تحميل Plugin.

الثابت المهم: استدعاءات مساحة الأسماء هي استدعاءات أدوات فهرس. تستخدم خطافات
السياسة نفسها، والموافقات، ومعالجة الإجهاض، والقياس عن بُعد، وإسقاط النص،
وسلوك التعليق/الاستئناف مثل `tools.call(...)`.

### شكل التسجيل

سجّل مساحات الأسماء من التكامل الذي يملك الأدوات الداعمة. أبقِ النطاق صغيرًا
واعرض فقط أفعال المجال التي ترتبط بأدوات فهرس مصرّح بها.

```typescript
import {
  createCodeModeNamespaceTool,
  registerCodeModeNamespaceForPlugin,
} from "../agents/code-mode-namespaces.js";

const pluginId = "github";

registerCodeModeNamespaceForPlugin(pluginId, {
  id: "github-issues",
  globalName: "Issues",
  description: "GitHub issue helpers for the current repository.",
  requiredToolNames: ["github_list_issues", "github_update_issue"],
  prompt: "Use Issues.list(params) and Issues.update(number, patch).",
  createScope: (ctx) => ({
    repository: ctx.config,
    list: createCodeModeNamespaceTool("github_list_issues", ([params]) => params ?? {}),
    update: createCodeModeNamespaceTool("github_update_issue", ([number, patch]) => ({
      number,
      patch,
    })),
  }),
});
```

تضع `createCodeModeNamespaceTool(toolName, inputMapper)` علامة على عضو النطاق
كدالة مساحة أسماء قابلة للاستدعاء. يتلقى `inputMapper` الاختياري وسائط الضيف
ويُرجع كائن الإدخال لأداة الفهرس الداعمة. دون مخطط إدخال، يُستخدم وسيط الضيف
الأول، أو `{}` عند حذفه.

تُرفض دوال المضيف الخام قبل تشغيل شيفرة الضيف:

```typescript
createScope: () => ({
  // Wrong: this bypasses the catalog tool lifecycle and will be rejected.
  list: async () => githubClient.listIssues(),
});
```

### الملكية والرؤية

ملكية مساحة الأسماء مرتبطة بـ `pluginId` الخاص بمستدعي التسجيل.
`requiredToolNames` هي بوابة رؤية وفحص ملكية في الوقت نفسه:

- يجب أن تكون كل أداة مطلوبة موجودة في فهرس التشغيل
- يجب أن تكون لكل أداة مطلوبة `sourceName === pluginId`
- تُخفى مساحة الأسماء عند غياب أي أداة مطلوبة أو امتلاكها من Plugin آخر
- لا يجوز لكل مسار قابل للاستدعاء استهداف إلا أداة مسماة في `requiredToolNames`

يمنع هذا Plugin آخر من عرض مساحة أسماء عبر تسجيل أداة بالاسم نفسه. كما يبقي
مساحات الأسماء متوائمة مع سياسة الوكيل العادية: إذا لم يتمكن التشغيل من رؤية
الأدوات الداعمة، فلن يتمكن من رؤية مساحة الأسماء.

على سبيل المثال، يجب أن تعيش مساحة أسماء GitHub خلف إضافة مملوكة لـ GitHub
تملك مصادقة GitHub، وعملاء REST أو GraphQL، وحدود المعدل، وموافقات الكتابة،
والاختبارات. يجب ألا يضمّن وضع الشيفرة في النواة واجهات API خاصة بـ GitHub أو
معالجة الرموز أو سياسة المزوّد.

### قواعد تسلسل النطاق

قد تُرجع `createScope(ctx)` كائنًا عاديًا يحتوي قيمًا متوافقة مع JSON ومصفوفات
وكائنات متداخلة وعلامات استدعاء `createCodeModeNamespaceTool(...)`. لا تدخل
كائنات المضيف إلى QuickJS مباشرة أبدًا.

يرفض المسلسل:

- الدوال الخام
- رسومًا بيانية كائنية دائرية
- مقاطع المسار غير الآمنة: `__proto__` أو `constructor` أو `prototype` أو
  المفاتيح الفارغة أو المفاتيح التي تحتوي فاصل المسار الداخلي
- قيم `globalName` التي ليست معرّفات JavaScript
- تصادمات `globalName` مع عموميات وضع الشيفرة المدمجة مثل `tools` أو
  `namespaces` أو `text` أو `json` أو `yield_control` أو `__openclaw*`

تُحوّل القيم التي لا يمكن تسلسلها إلى JSON إلى قيم احتياطية آمنة لـ JSON قبل
عبور الجسر. يجب أن تبقى البيانات الثنائية والمقابض والمقابس والعملاء ومثيلات
الفئات خلف أدوات الفهرس العادية.

### الموجهات

تُلحَق `description` الخاصة بمساحة الأسماء و`prompt` الاختيارية بمخطط `exec`
المرئي للنموذج فقط عندما تكون مساحة الأسماء مرئية لذلك التشغيل. استخدمها
لتعليم أصغر سطح مفيد:

```typescript
{
  description: "Fiction production service helpers.",
  prompt:
    "Use Fictions.riskAudit(), Fictions.promoteIfReady(id, status), and Fictions.unpaidOver(amount).",
}
```

أبقِ الموجهات متعلقة بعقد مساحة الأسماء، لا بإعداد المصادقة أو تاريخ التنفيذ
أو سلوك Plugin غير ذي صلة.

### التنظيف

مساحات الأسماء هي تسجيلات محلية للعملية. أزلها عندما يكون Plugin المالك
معطلا أو ملغى تثبيته أو جرى التراجع عنه:

```typescript
clearCodeModeNamespacesForPlugin(pluginId);
```

تنظيف وضع التعليمات البرمجية مملوك للـ Plugin؛ امسح تسجيلات مساحة الأسماء الخاصة بالـ Plugin
عند انتهاء دورة حياته بدلا من الاحتفاظ بمقابض إنهاء لكل مساحة اسم. يمكن للاختبارات
استدعاء `clearCodeModeNamespacesForTest()` لتجنب تسريب التسجيلات
عبر الحالات.

### قائمة تحقق الاختبار

يجب أن تغطي تغييرات مساحة الأسماء حد الأمان وسلوك الضيف:

- يظهر نص مطالبة مساحة الأسماء فقط عندما تكون الأدوات الداعمة مرئية
- الأدوات ذات الاسم نفسه من `sourceName` آخر لا تكشف مساحة الأسماء
- تُرفض دوال النطاق الخام
- تُرفض معرفات مساحة الأسماء المزورة والمسارات المزورة
- لا يمكن للمسارات القابلة للاستدعاء استهداف أدوات غير مصرّح بها
- تُسلسل الكائنات المتداخلة والمراجع المشتركة بشكل صحيح
- تُنفذ استدعاءات مساحة الأسماء عبر أدوات الكتالوج وتعيد تفاصيل آمنة لـ JSON
- يمكن لرمز الضيف التقاط حالات الفشل
- تُستأنف استدعاءات مساحة الأسماء المعلقة عبر `wait`
- يؤدي التراجع عن Plugin إلى مسح تسجيلات مساحة الأسماء المالكة

تكمّل مساحات الأسماء كتالوج `tools.search` / `tools.call` العام. استخدم
الكتالوج لأدوات OpenClaw وPlugin والعميل الممكنة عموما؛ واستخدم `MCP` لأدوات
MCP؛ واستخدم مساحات أسماء أخرى لواجهات API موثقة ومملوكة للـ Plugin ضمن نطاقات
مجالية، حيث تكون التعليمات البرمجية الموجزة أكثر موثوقية من عمليات البحث المتكررة في المخطط.

## واجهة API للإخراج

يضيف `text(value)` مخرجا قابلا للقراءة البشرية إلى مصفوفة `output`.

يضيف `json(value)` عنصر إخراج منظما بعد تسلسل متوافق مع JSON.

تصبح القيمة النهائية التي يرجعها رمز الضيف هي `value` في نتيجة `completed`.

عنصر الإخراج:

```typescript
type CodeModeOutput = { type: "text"; text: string } | { type: "json"; value: unknown };
```

قواعد الإخراج:

- ترتيب الإخراج يطابق استدعاءات الضيف
- الإخراج محدود بواسطة `maxOutputBytes`
- تُحوّل القيم غير القابلة للتسلسل إلى سلاسل نصية عادية أو أخطاء
- القيم الثنائية غير مدعومة في v1
- تنتقل الصور والملفات عبر أدوات OpenClaw العادية، لا عبر
  جسر وضع التعليمات البرمجية

## كتالوج الأدوات

يتضمن الكتالوج المخفي الأدوات بعد تطبيق ترشيح السياسة الفعلي:

1. أدوات OpenClaw الأساسية.
2. أدوات Plugin المضمنة.
3. أدوات Plugin الخارجية.
4. أدوات MCP.
5. الأدوات المقدمة من العميل للتشغيل الحالي.

تكون معرفات الكتالوج مستقرة ضمن تشغيل واحد وحتمية عبر مجموعات الأدوات المتكافئة
عندما يكون ذلك ممكنا.

شكل المعرّف الموصى به:

```text
<source>:<owner>:<tool-name>
```

أمثلة:

```text
openclaw:core:message
plugin:browser:browser_request
mcp:github:create_issue
client:app:select_file
```

يحذف الكتالوج أدوات التحكم في وضع التعليمات البرمجية:

- `exec`
- `wait`
- `tool_search_code`
- `tool_search`
- `tool_describe`
- `tool_call`

يمنع هذا الاستدعاء الذاتي ويحافظ على تضييق العقدة المرئية للنموذج.

تبقى إدخالات MCP في الكتالوج محدود النطاق بالتشغيل كي تبقى السياسة والموافقات والخطافات
والقياسات وإسقاط النص ومعرفات الأدوات الدقيقة مشتركة مع تنفيذ الأدوات العادي.
تحذف عروض `ALL_TOOLS` و`tools.search(...)` و`tools.describe(...)` و`tools.call(...)`
الموجهة للضيف إدخالات MCP. تحل مساحة الأسماء
`MCP.<server>.<tool>({ ...input })` المولدة إلى معرف الكتالوج الدقيق ثم تُرسل عبر
مسار المنفذ نفسه.

## تفاعل بحث الأدوات

يحل وضع التعليمات البرمجية محل سطح نموذج بحث أدوات OpenClaw للتشغيلات التي يكون فيها
نشطا.

عندما تكون `tools.codeMode.enabled` صحيحة وينشط وضع التعليمات البرمجية:

- لا يكشف OpenClaw `tool_search_code` أو `tool_search` أو `tool_describe`
  أو `tool_call` كأدوات مرئية للنموذج.
- تنتقل فكرة الفهرسة نفسها إلى داخل وقت تشغيل الضيف.
- يتلقى وقت تشغيل الضيف بيانات تعريف `ALL_TOOLS` مضغوطة ومساعدات بحث ووصف
  واستدعاء للأدوات غير التابعة لـ MCP.
- تستخدم استدعاءات MCP مساحة الأسماء `MCP` المولدة وترويسات `$api()` الخاصة بها
  بدلا من `tools.call(...)`.
- تُرسل الاستدعاءات المتداخلة عبر مسار منفذ OpenClaw نفسه الذي يستخدمه بحث الأدوات.

تصف صفحة [بحث الأدوات](/ar/tools/tool-search) الحالية جسر الكتالوج المضغوط في OpenClaw.
وضع التعليمات البرمجية هو بديل OpenClaw العام للتشغيلات التي يمكنها استخدام
`exec` و`wait`.

## أسماء الأدوات والتعارضات

أداة `exec` المرئية للنموذج هي أداة وضع التعليمات البرمجية. إذا كانت أداة OpenClaw
العادية للصدفة `exec` ممكنة، فستُخفى عن النموذج وتُفهرس مثل أي أداة أخرى.

داخل وقت تشغيل الضيف:

- يمكن لـ `tools.call("openclaw:core:exec", input)` استدعاء أداة تنفيذ الصدفة إذا
  سمحت السياسة بذلك.
- لا تُثبت `tools.exec(...)` إلا إذا كان لإدخال كتالوج تنفيذ الصدفة اسم آمن
  غير ملتبس.
- لا تكون أداة وضع التعليمات البرمجية `exec` متاحة أبدا بصورة متكررة عبر `tools`.

إذا طُبّعت أداتان إلى اسم ملاءمة آمن واحد، يحذف OpenClaw دالة الملاءمة
ويتطلب `tools.call(id, input)`.

## تنفيذ الأدوات المتداخلة

يعبر كل استدعاء أداة متداخل جسر المضيف ويعيد الدخول إلى OpenClaw.

يحافظ التنفيذ المتداخل على:

- معرف العامل النشط
- معرف الجلسة ومفتاح الجلسة
- سياق المرسل والقناة
- سياسة صندوق العزل
- سياسة الموافقة
- خطافات Plugin `before_tool_call`
- إشارة الإجهاض
- تحديثات البث حيثما توفرت
- أحداث المسار والتدقيق

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

تُسمح الاستدعاءات المتداخلة المتوازية حتى `maxPendingToolCalls`.

## حالة وقت التشغيل

لكل تشغيل في وضع التعليمات البرمجية آلة حالات:

- `running`: ينفذ VM أو توجد استدعاءات متداخلة قيد التنفيذ.
- `waiting`: توجد لقطة VM ويمكن استئنافها باستخدام `wait`.
- `completed`: أُعيدت القيمة النهائية؛ حُذفت اللقطة.
- `failed`: أُعيد خطأ؛ حُذفت اللقطة.
- `expired`: تجاوزت اللقطة أو الحالة المعلقة مدة الاحتفاظ؛ لا يمكن الاستئناف.
- `aborted`: أُلغيت الجلسة/التشغيل الأب؛ حُذفت اللقطة.

تكون الحالة محددة النطاق بتشغيل العامل والجلسة ومعرف استدعاء الأداة. يفشل استدعاء
`wait` من تشغيل أو جلسة مختلفة.

تخزين اللقطات محدود:

- الحد الأقصى لبايتات اللقطة لكل تشغيل
- الحد الأقصى للقطات الحية لكل عملية
- مدة بقاء اللقطة
- التنظيف عند نهاية التشغيل
- التنظيف عند إيقاف Gateway حيث لا يكون الاستمرار مدعوما

## وقت تشغيل QuickJS-WASI

يحمّل OpenClaw `quickjs-wasi` كتبعية مباشرة في الحزمة المالكة. لا يعتمد وقت التشغيل
على نسخة انتقالية مثبتة للوكيل أو PAC أو أي تبعيات أخرى غير ذات صلة.

مسؤوليات وقت التشغيل:

- ترجمة أو تحميل وحدة WebAssembly الخاصة بـ QuickJS-WASI
- إنشاء VM معزول واحد لكل تشغيل أو استئناف في وضع التعليمات البرمجية
- تسجيل استدعاءات المضيف بأسماء مستقرة
- تعيين حدود الذاكرة والمقاطعة
- تقييم JavaScript
- تفريغ المهام المعلقة
- أخذ لقطة لحالة VM المعلقة
- استعادة اللقطات من أجل `wait`
- التخلص من مقابض VM واللقطات بعد الحالات النهائية

ينفذ وقت التشغيل خارج حلقة الأحداث الرئيسية في OpenClaw داخل عامل. يجب ألا تحظر
حلقة لا نهائية في الضيف عملية Gateway إلى أجل غير مسمى.

## TypeScript

دعم TypeScript هو تحويل مصدري فقط:

- الإدخال المقبول: سلسلة تعليمات TypeScript واحدة
- الإخراج: سلسلة JavaScript يقيّمها QuickJS-WASI
- لا يوجد فحص أنواع
- لا يوجد حل للوحدات
- لا يوجد `import` أو `require` في v1
- تُعاد التشخيصات كنتائج `failed`

يُحمّل مترجم TypeScript بكسل فقط لخلايا TypeScript. لا تُحمّل خلايا JavaScript
العادية ولا وضع التعليمات البرمجية المعطل المترجم.

ينبغي أن يحافظ التحويل على أرقام أسطر مفيدة حيثما أمكن.

## حد الأمان

رمز النموذج عدائي. يستخدم وقت التشغيل دفاعا متعدد الطبقات:

- تشغيل QuickJS-WASI خارج حلقة الأحداث الرئيسية
- تحميل `quickjs-wasi` كتبعية مباشرة، لا عبر Codex أو حزمة انتقالية
- لا نظام ملفات ولا شبكة ولا عملية فرعية ولا استيراد وحدات ولا متغيرات بيئة ولا
  كائنات مضيف عامة في الضيف
- استخدام حدود ذاكرة ومقاطعة QuickJS
- فرض مهلة زمنية حائطية للعملية الأب
- فرض حدود للإخراج واللقطات والسجلات والاستدعاءات المعلقة
- تسلسل قيم جسر المضيف عبر محول JSON ضيق
- تحويل أخطاء المضيف إلى أخطاء ضيف عادية، وليس إلى كائنات من نطاق المضيف أبدا
- إسقاط اللقطات عند المهلة أو الإجهاض أو نهاية الجلسة أو انتهاء الصلاحية
- رفض الوصول المتكرر إلى `exec` و`wait` وأدوات التحكم في بحث الأدوات
- منع تعارضات أسماء الملاءمة من حجب مساعدات الكتالوج

صندوق العزل طبقة أمان واحدة. قد يظل المشغلون بحاجة إلى تقوية على مستوى نظام التشغيل
لعمليات النشر عالية المخاطر.

## رموز الخطأ

```typescript
type CodeModeErrorCode =
  | "runtime_unavailable"
  | "invalid_config"
  | "invalid_input"
  | "unsupported_language"
  | "typescript_transform_failed"
  | "module_access_denied"
  | "timeout"
  | "memory_limit_exceeded"
  | "output_limit_exceeded"
  | "snapshot_limit_exceeded"
  | "snapshot_expired"
  | "snapshot_restore_failed"
  | "too_many_pending_tool_calls"
  | "nested_tool_failed"
  | "aborted"
  | "internal_error";
```

الأخطاء المعادة إلى الضيف هي بيانات عادية. لا تعبر مثيلات `Error` الخاصة بالمضيف
ولا كائنات المكدس ولا النماذج الأولية ولا دوال المضيف إلى QuickJS.

## القياسات

يبلغ وضع التعليمات البرمجية عن:

- أسماء الأدوات المرئية المرسلة إلى النموذج
- حجم الكتالوج المخفي وتفصيل المصادر
- أعداد `exec` و`wait`
- أعداد البحث والوصف والاستدعاء المتداخلة
- معرفات الأدوات المتداخلة المستدعاة
- حالات فشل حدود المهلة والذاكرة واللقطات والإخراج
- أحداث دورة حياة اللقطات

يجب ألا تتضمن القياسات أسرارا أو قيما خاما للبيئة أو مدخلات أدوات غير منقحة
بما يتجاوز سياسة مسار OpenClaw الحالية.

## التصحيح

استخدم تسجيل نقل النموذج الموجه عندما يتصرف وضع التعليمات البرمجية بشكل مختلف عن
تشغيل أداة عادي:

```bash
OPENCLAW_DEBUG_CODE_MODE=1 \
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 \
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools \
OPENCLAW_DEBUG_SSE=events \
openclaw gateway
```

لتصحيح شكل الحمولة، استخدم `OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted`.
يسجل هذا لقطة JSON محدودة ومنقحة لطلب النموذج؛ وينبغي استخدامه أثناء التصحيح فقط
لأن المطالبات ونص الرسائل قد تظل ظاهرة.

لتصحيح البث، استخدم `OPENCLAW_DEBUG_SSE=peek` لتسجيل أول خمسة أحداث SSE
منقحة. يفشل وضع التعليمات البرمجية أيضا بشكل مغلق إذا لم تحتو حمولة المزود النهائية
على `exec` و`wait` بالضبط بعد تفعيل سطح وضع التعليمات البرمجية.

## تخطيط التنفيذ

وحدات التنفيذ:

- عقد التكوين: `tools.codeMode`
- منشئ الكتالوج: الأدوات الفعلية إلى إدخالات مضغوطة وخريطة معرفات
- محول سطح النموذج: استبدال الأدوات المرئية بـ `exec` و`wait`
- محول وقت تشغيل QuickJS-WASI: التحميل، التقييم، اللقطة، الاستعادة، التخلص
- مشرف العامل: المهلة، الإجهاض، عزل الانهيار
- محول الجسر: استدعاءات مضيف آمنة لـ JSON وتسليم النتائج
- محول TypeScript
- مخزن اللقطات: مدة البقاء، حدود الحجم، تحديد نطاق التشغيل/الجلسة
- إسقاط المسار لاستدعاءات الأدوات المتداخلة
- عدادات القياسات والتشخيصات

يعيد التنفيذ استخدام مفاهيم الكتالوج والمنفذ من بحث الأدوات، لكنه لا يستخدم
الابن `node:vm` كصندوق عزل.

## قائمة تحقق التحقق

يجب أن تثبت تغطية وضع التعليمات البرمجية:

- يترك الإعداد المعطّل عرض الأدوات الحالي دون تغيير
- إعداد الكائن بدون `enabled: true` يترك وضع الكود معطّلاً
- يعرض الإعداد المفعّل فقط `exec` و`wait` للنموذج عندما تكون الأدوات
  نشطة للتشغيل
- لا تؤدي التشغيلات الأولية بلا أدوات، و`disableTools`، وقوائم السماح الفارغة إلى فرض
  حمولة وضع الكود
- تظهر جميع الأدوات الفعالة غير MCP في `ALL_TOOLS`
- لا تظهر الأدوات المرفوضة في `ALL_TOOLS`
- تعمل `tools.search` و`tools.describe` و`tools.call` مع أدوات OpenClaw
- يتيح `API.list("mcp")` و`API.read("mcp/<server>.d.ts")` إعلانات MCP بنمط TypeScript
  دون جسر/استدعاء أداة
- تبقى مساحة أسماء MCP `$api()` متاحة كبديل احتياطي مضمن للمخططات
- تعمل استدعاءات مساحة أسماء MCP للأدوات المرئية من MCP مع إدخال كائن واحد، بينما
  لا تكون إدخالات كتالوج MCP المباشرة موجودة في `tools.*`
- تكون أدوات التحكم في Tool Search مخفية عن كل من سطح النموذج والكتالوج المخفي
- تحافظ الاستدعاءات المتداخلة على سلوك الموافقة والخطاف
- يكون shell `exec` مخفيًا عن النموذج لكن يمكن استدعاؤه عبر معرّف الكتالوج عند السماح بذلك
- لا يمكن استدعاء `exec` و`wait` المتكررين في وضع الكود من كود الضيف
- يتم تحويل إدخال TypeScript وتقييمه دون تحميل TypeScript في
  المسارات المعطّلة أو الخاصة بـ JavaScript فقط
- يفشل الوصول إلى `import` و`require` ونظام الملفات والشبكة والبيئة
- تنتهي الحلقات اللانهائية بمهلة ولا يمكنها حظر Gateway
- تنهي حالات فشل حد الذاكرة VM الضيف
- يتم فرض حدود الإخراج واللقطات للاستدعاءات المكتملة والمعلّقة
- يستأنف `wait` لقطة معلّقة ويعيد القيمة النهائية
- تفشل قيم `runId` المنتهية الصلاحية، والمُجهضة، وذات الجلسة الخاطئة، والمجهولة
- تحافظ إعادة تشغيل النص والمثابرة على استدعاءات التحكم في وضع الكود
- يعرض النص والقياسات استدعاءات الأدوات المتداخلة بوضوح

## خطة اختبار E2E

شغّل هذه كاختبارات تكامل أو اختبارات شاملة عند تغيير وقت التشغيل:

1. ابدأ Gateway مع `tools.codeMode.enabled: false`.
2. أرسل دورة وكيل مع مجموعة أدوات مباشرة صغيرة.
3. تحقق من أن الأدوات المرئية للنموذج لم تتغير.
4. أعد التشغيل مع `tools.codeMode.enabled: true`.
5. أرسل دورة وكيل مع أدوات اختبار OpenClaw وPlugin وMCP والعميل.
6. تحقق من أن قائمة الأدوات المرئية للنموذج هي بالضبط `exec` و`wait`.
7. في `exec`، اقرأ `ALL_TOOLS` وتحقق من وجود أدوات الاختبار الفعالة.
8. في `exec`، استدع أدوات OpenClaw/Plugin/العميل عبر `tools.search`،
   و`tools.describe`، و`tools.call`.
9. في `exec`، استدع `API.list("mcp")` و`API.read("mcp/<server>.d.ts")` وتحقق من
   أن ملفات الإعلان تصف أدوات MCP المرئية.
10. في `exec`، استدع أدوات MCP عبر `MCP.<server>.<tool>({ ...input })` وتحقق من
    أن إدخالات كتالوج MCP المباشرة غير موجودة في `ALL_TOOLS` و`tools.*`.
11. تحقق من أن الأدوات المرفوضة غير موجودة ولا يمكن استدعاؤها بمعرّف مُخمّن.
12. ابدأ استدعاء أداة متداخلاً يكتمل بعد أن يعيد `exec` القيمة `waiting`.
13. استدع `wait` وتحقق من أن VM المستعاد يتلقى نتيجة الأداة.
14. تحقق من أن الإجابة النهائية تحتوي على إخراج تم إنتاجه بعد الاستعادة.
15. تحقق من أن المهلة والإجهاض وانتهاء صلاحية اللقطة تنظف حالة وقت التشغيل.
16. صدّر المسار وتحقق من أن الاستدعاءات المتداخلة مرئية تحت استدعاء
    وضع الكود الأصل.

يجب أن تستمر التغييرات الخاصة بالتوثيق فقط في هذه الصفحة بتشغيل `pnpm check:docs`.

## ذات صلة

- [Tool Search](/ar/tools/tool-search)
- [أوقات تشغيل الوكلاء](/ar/concepts/agent-runtimes)
- [أداة Exec](/ar/tools/exec)
- [تنفيذ الكود](/ar/tools/code-execution)
