لوكلاء الذكاء الاصطناعي

يطبع openemail agents دليلًا قصيرًا بصيغة Markdown لوكيل ذكاء اصطناعي مثل Claude Code أو Codex، أو لسكربت في CI: كيف يسجّل الدخول دون إنسان، ويقرأ المخرجات، ويجد الأوامر، ويغيّر الأشياء بأمان، ويتنقّل بين صفحات القوائم، وما يفعله حين ينقص رمز تحقق أو نطاق، وخمس وصفات جاهزة للنسخ. وopenemail agent هو الأمر نفسه.

openemail agentsopenemail agents --json | jq -r '.recipes[].commands[]'

مع --json يصبح الدليل مستندًا واحدًا فيه schemaVersion وtitle وintro وsections من { id, title, points } وexitCodes وrecipes من { id, title, commands }. وبدلًا من لصق هذه القواعد في كل موجّه، أخبر الوكيل مرة واحدة، في ملف التعليمات الذي يعطيه له مشروعك أصلًا، أن يشغّل openemail agents قبل أن يستخدم CLI.

• —استخدم مفتاح API. اضبط OPENEMAIL_API_KEY، أو مرّر --api-key إلى أمر واحد. أنشئه من الإعدادات → مفاتيح API (openemail open api-keys) بالنطاقات التي يحتاجها الوكيل فقط. المفتاح لا يفتح متصفحًا أبدًا ولا يحتاج إلى رمز تحقق أبدًا.
• —أو أعد استخدام تسجيل دخول عبر المتصفح أجراه إنسان مرة واحدة على هذا الجهاز بـ openemail login، واختره بـ --profile <name>. وتجدّد CLI رموزها بنفسها.
• —لا شيء يسأل دون طرفية. مع --json أو --no-input أو CI، أو دون طرفية متصلة، تتوقف القيمة التي كانت CLI ستسأل عنها برمز الخروج 2 مع ذكر الخيار الذي يجب تمريره.
• —يحتاج تسجيل الدخول عبر المتصفح إلى إنسان يوافق عليه، لذا يتوقف openemail login دون إشراف برمز الخروج 2 والرمز unattended قبل أن يسجّل أي شيء، ويشير إلى openemail login --with-token.
• —يعرض openemail whoami --json مساحة العمل ونوع تسجيل الدخول وscopes الخاصة به.

مرّر --json إلى كل أمر. عندها يحمل stdout مستند JSON واحدًا بالضبط، أو كائنًا واحدًا في كل سطر مع --ndjson، ويبقى التقدّم على stderr. ويطبع الفشل سطر {"error":{...}} واحدًا على stderr: تفرّع حسب رمز الخروج وحسب code الخاص به، واعرض next على إنسان، ولا تحلّل message أبدًا، فصياغته قد تتغير. وتسرد صفحة «السكربتات» كل حقل وكل رمز خروج.

يطبع --help --json المساعدة مستندَ JSON واحدًا، مبنيًا من سجل الأوامر نفسه الذي تحلّل به CLI، فيطابق دائمًا الإصدار المثبّت. ويعمل على الجذر أو على مجموعة أو على أمر، ويطبع openemail help <command> --json الشيء نفسه.

openemail send --help --jsonopenemail domains delete --help --json | jq '.commands[0] | {scopes, destructive}'openemail help domains --json | jq -r '.commands[0].subcommands[].command'openemail --help --json | jq -r '.commands[].command'

الشجرة كاملة نحو ميغابايت، وكلها تقريبًا الأوامر الـ 198 للموارد، لذا اطلب الأمر الذي تحتاجه أو صفِّ الشجرة بـ jq. ويحتفظ النص بعلامات الاقتباس المائلة ولا يحمل رموز ألوان، والأوامر المخفية مثل security مضمّنة مع ضبط hidden على true.

يعمل --dry-run على كل أمر عدا mcp serve. تجري القراءات كالمعتاد، ثم يُطبع أول طلب كان سيغيّر شيئًا بدلًا من إرساله، ويخرج الأمر بالرمز 0 دون أن يفعل أي شيء آخر. وتُتخطى التأكيدات إذ لا يُرسَل شيء، فيستطيع الوكيل أن يرى ما كان سيفعله أمر مدمّر دون تمرير --yes.

openemail domains delete <domain-id> --dry-runopenemail send --from [email protected] --to [email protected] --subject "Hi" --text "Hello" --dry-run --json

{  "dryRun": true,  "request": {    "method": "POST",    "url": "https://api.openemail.uk/emails",    "headers": {      "accept": "application/json",      "authorization": "Bearer [redacted]",      "content-type": "application/json",      "idempotency-key": "58e6fb61-ad2e-401e-b141-7a0546c7c749",      "user-agent": "openemail-cli/0.0.1 openemail-sdk/0.0.5"    },    "body": {      "from": "[email protected]",      "to": [        "[email protected]"      ],      "subject": "Hi",      "text": "Hello"    },    "raw": null  }}

• —التغيير هو أي طلب عدا GET وHEAD، واستدعاء أداة MCP، وطلبات تسجيل الدخول والخروج في login وlogout. أما تجديد الرموز وdocs ask فيعملان كالمعتاد.
• —تعرض الخطة الطريقة، والعنوان الكامل، والترويسات مع اختصار قيمة Authorization إلى Bearer [redacted]، ومتن JSON مع حجب الحقول السرية مثل مفتاح Resend. ويعرض الرفع حجمه ونوع محتواه فقط.
• —التغيير الذي يبقى على هذا الجهاز، مثل profile use أو login --with-token أو نسيان مفتاح API محفوظ، يطبع {"dryRun":true,"local":{"action","profile"}} ولا يحفظ شيئًا.
• —الأمر الذي يطبع ما قرأه قبل أول تغيير له يعرضه أولًا: يطبع read المحادثة، ثم الطلب الذي كان سيعلّمها مقروءة. مرّر --no-mark-read لإسقاط الثاني.
• —يرفض mcp serve الخيار --dry-run برمز الخروج 2، لأن عميله هو الذي يقرر ما يُرسَل. بدلًا من ذلك عاين استدعاء أداة واحدًا بـ openemail mcp call <tool> --dry-run.

يعرف كل أمر نطاقات API التي يحتاجها دائمًا، وتسردها مساعدته. وحين ينقص تسجيلَ دخول محفوظًا واحدٌ منها، يسأل الأمر API مرة واحدة عن القائمة الحالية، فيُحتسب فورًا الوصول الذي مُنح على الموقع بعد تسجيل الدخول. وإن بقي النطاق ناقصًا، يتوقف برمز الخروج 4 والرمز insufficient_scope قبل أن يسأل عن أي شيء أو يرسل طلبًا:

{"error":{"type":"cli_error","code":"insufficient_scope","message":"This sign-in does not have the emails:send permission, which openemail send needs.","hint":null,"next":"Give this app more access in Account settings, Connected apps (openemail open apps, then Edit access), or run openemail login --force and choose more access.","status":null,"requestId":null,"param":null,"docUrl":null,"exitCode":4}}

• —لتسجيل الدخول عبر المتصفح، يقول next أن تمنح التطبيق وصولًا أوسع في الحساب → سطر الأوامر (openemail open cli، ثم «تعديل الوصول»)، أو أن تشغّل openemail login --force وتختار وصولًا أوسع. ولا يُمنح تسجيل الدخول عبر المتصفح keys:write أو keys:manage أبدًا، لذا يشير لهما إلى مفتاح API.
• —لمفتاح API، يقول next أن تستخدم مفتاحًا فيه النطاق.
• —المفتاح القادم من --api-key أو OPENEMAIL_API_KEY لا يُفحص مسبقًا، وAPI هي التي تقرر. وحين ترفض API استدعاءً بسبب نطاق ناقص، يحمل الخطأ next نفسه.

مفتاح API لا يحتاج إلى رمز تحقق أبدًا. أما تسجيل الدخول عبر المتصفح فيحتاج إلى رمز قبل تغيير حساس، مثل إضافة webhook أو إنشاء قاعدة أو تغيير عضو أو إزالة نطاق، والوكيل لا يستطيع كتابته. لذا قبل أن يعمل الوكيل، يشغّل إنسان openemail verify في طرفية بالملف الشخصي نفسه، أو يختار لتسجيل الدخول ذاك «السماح بالتغييرات لمدة 60 دقيقة» في الحساب → سطر الأوامر. وأيٌّ منهما يغطي الدقائق الستين التالية.

openemail verifyopenemail verify --status --json

يخبر verify --status --json الوكيل هل الملف الشخصي متحقَّق منه، في elevated، وحتى متى، في elevatedUntil. ودون تحقق يتوقف التغيير برمز الخروج 4 والرمز step_up_required، ولا يتغير شيء:

{"error":{"type":"cli_error","code":"step_up_required","message":"This action needs a verification code, and there is no interactive terminal to ask for one.","hint":null,"next":"Run openemail verify in an interactive terminal first, then run this again within 60 minutes. An API key never needs a code.","status":403,"requestId":"req_9Qm4tV","param":null,"docUrl":"https://openemail.uk/docs/api/errors#step_up_required","exitCode":4}}

يستطيع الوكيل الذي يتحدث MCP أن يستخدم خادم MCP الخاص بـ OpenEmail بدلًا من ذلك. يطبع openemail mcp config --client claude-code، أو codex أو cursor أو غيرهما من العملاء الذين يسردهم، طريقة الإعداد، وopenemail mcp serve جسر محلي يعيد استخدام تسجيل الدخول عبر المتصفح لهذه CLI. ولا تصل مفاتيح API إلى خادم MCP. والتفاصيل في صفحة «الذكاء الاصطناعي وMCP».