اتصال هوش مصنوعی به وردپرس؛ آموزش واقعی AI Client، OpenAI و MCP

اتصال هوش مصنوعی به وردپرس تا چند ماه قبل معمولاً دو مسیر اصلی داشت: نصب یک افزونه آماده یا نوشتن کدی که مستقیم به API یک سرویس مثل OpenAI وصل شود. امروز شرایط فرق کرده است. وردپرس 7 یک AI Client داخلی دارد، وردپرس 6.9 زیرساخت Abilities API را اضافه کرده و ابزارهایی مثل WordPress MCP Adapter هم راه اتصال کنترل‌شده AI Agentها را باز کرده‌اند.

در این آموزش قرار نیست فقط چند اصطلاح معرفی کنیم. از صفر جلو می‌رویم: اتصال Provider در وردپرس، تفاوت AI Client با API مستقیم، ساخت یک درخواست واقعی، نکات امنیتی، کاربرد در ووکامرس و در پایان اتصال WordPress MCP به ابزارهایی مثل Claude. تصاویر این مقاله اسکرین‌شات‌های واقعی از آموزش‌های رسمی WordPress Developer Blog هستند؛ نه تصویرسازی ساختگی.

قبل از شروع: دقیقاً چه چیزی را به هوش مصنوعی وصل می‌کنیم؟

«اتصال AI به وردپرس» می‌تواند چند معنی متفاوت داشته باشد. اگر هدف شما بیشتر جنبه فروش و بازاریابی دارد، مقاله نقش هوش مصنوعی در افزایش فروش دید تجاری موضوع را تکمیل می‌کند. گاهی فقط می‌خواهید یک دکمه در صفحه محصول داشته باشید که توضیح کوتاه تولید کند. گاهی می‌خواهید چت پشتیبانی به اطلاعات محصول دسترسی داشته باشد. در پروژه‌های پیشرفته‌تر، یک Agent بیرونی باید بتواند چند عملیات مشخص سایت را اجرا کند.

به همین دلیل قبل از انتخاب ابزار، سناریو را مشخص کنید:

• تولید یا بازنویسی متن داخل پیشخوان وردپرس؛
• تولید تصویر و ذخیره مستقیم در Media Library؛
• پاسخ‌گویی هوشمند به مشتری فروشگاه؛
• تحلیل سفارش‌ها و ساخت گزارش مدیریتی؛
• خلاصه‌سازی دیدگاه‌ها و تیکت‌ها؛
• اتصال یک AI Agent خارجی به عملیات تعریف‌شده وردپرس.

این تفاوت مهم است؛ چون برای هرکدام بهترین روش اتصال یکی نیست.

روش‌های اصلی اتصال هوش مصنوعی به وردپرس

مرحله اول: اتصال Provider از Settings → Connectors

در WordPress 7، صفحه Settings → Connectors برای مدیریت اتصال سرویس‌های خارجی در یک محل واحد اضافه شده است. در آموزش رسمی WordPress Developer Blog، از همین صفحه برای نصب و تنظیم Providerهای AI استفاده می‌شود. ایده اصلی این است که هر افزونه مجبور نباشد صفحه جداگانه‌ای برای ذخیره API Key بسازد.

طبق آموزش رسمی، Provider Pluginهایی برای سرویس‌های اصلی از جمله OpenAI، Anthropic و Google وجود دارد و Providerهای دیگری مثل Ollama، OpenRouter و Mistral هم توسط اکوسیستم پشتیبانی می‌شوند. روند کلی این است:

1. به Settings → Connectors بروید.
2. Provider موردنظر را نصب کنید.
3. API Key همان Provider را وارد و ذخیره کنید.
4. بعد از اتصال، افزونه شما از AI Client استفاده می‌کند و لازم نیست خودش کلید را مدیریت کند.

نکته مهم این است که وجود WordPress 7 به‌تنهایی به معنی فعال بودن AI نیست. باید حداقل یک Provider نصب و پیکربندی شده باشد و Provider انتخابی قابلیت مورد نیاز شما، مثل تولید متن یا تصویر، را پشتیبانی کند.

WordPress AI Client چیست و چرا مهم است؟

AI Client یک API داخلی و Provider-agnostic است. یعنی افزونه شما نباید بداند درخواست در نهایت به OpenAI می‌رود یا Google یا Anthropic. افزونه فقط می‌گوید چه خروجی لازم دارد؛ وردپرس بر اساس Providerهای فعال، مدل مناسب را انتخاب می‌کند.

این تغییر برای توسعه‌دهنده مهم است چون به‌جای نوشتن سه مسیر جدا برای سه سرویس، یک کد اصلی دارید. مدیر سایت هم Provider و API Key را خودش کنترل می‌کند.

ساده‌ترین نمونه تولید متن

<?php
$result = wp_ai_client_prompt()
    ->with_text( 'مزایای کش در وردپرس را کوتاه توضیح بده.' )
    ->using_temperature( 0.7 )
    ->generate_text_result();

if ( is_wp_error( $result ) ) {
    // خطا را مدیریت کنید.
}

برای پروژه‌های ساده‌تر می‌توان مستقیماً از generate_text() هم استفاده کرد. نکته عملی این است که خروجی AI باید مثل هر ورودی خارجی دیگر بررسی شود؛ یعنی صرفاً به این دلیل که خروجی از مدل آمده، نباید بدون اعتبارسنجی در دیتابیس ذخیره یا منتشر شود.

قبل از نمایش قابلیت AI، پشتیبانی را چک کنید

در آموزش رسمی WordPress توصیه شده قبل از نمایش دکمه یا رابط AI بررسی کنید قابلیت لازم واقعاً در دسترس است. مثلاً برای تولید تصویر:

<?php
$is_available = wp_ai_client_prompt()
    ->with_text( 'test' )
    ->is_supported_for_image_generation();

if ( ! $is_available ) {
    // دکمه تولید تصویر را نمایش ندهید
    // یا پیام راهنما نشان دهید.
}

این بررسی inference انجام نمی‌دهد و برای تشخیص قابلیت Provider استفاده می‌شود. نتیجه این است که رابط کاربری شما وقتی Provider تنظیم نشده یا مدل مناسب وجود ندارد، بی‌دلیل خراب نمی‌شود.

نمونه واقعی: تولید تصویر داخل Media Library

یکی از بهترین نمونه‌های رسمی برای درک AI Client، افزونه آموزشی WordPress است که در Media Library یک دکمه «Generate Image File» اضافه می‌کند. کاربر prompt را وارد می‌کند، تصویر تولید می‌شود، preview نمایش داده می‌شود و بعد می‌تواند فایل را به Media Library ذخیره کند.

این نمونه از نظر معماری هم آموزنده است. فایل اصلی افزونه فقط وجود AI Client را چک می‌کند و منطق prompt، REST API و رابط مدیریت در فایل‌های جدا قرار دارند. یعنی حتی در پروژه کوچک هم بهتر است کد AI را وسط functions.php پخش نکنید.

اگر بخواهیم مستقیم به OpenAI وصل شویم چه؟

AI Client بهترین انتخاب برای افزونه عمومی است، اما همیشه لازم نیست. اگر پروژه کاملاً اختصاصی است یا به قابلیت خاص OpenAI نیاز دارید، می‌توانید مستقیماً از API رسمی استفاده کنید. در این حالت درخواست باید از سمت سرور وردپرس ارسال شود، نه مرورگر کاربر.

الگوی ساده با Responses API:

<?php
$api_key = get_option( 'my_openai_api_key' );

$response = wp_remote_post(
    'https://api.openai.com/v1/responses',
    array(
        'timeout' => 45,
        'headers' => array(
            'Authorization' => 'Bearer ' . $api_key,
            'Content-Type'  => 'application/json',
        ),
        'body' => wp_json_encode(
            array(
                'model' => 'YOUR_MODEL_ID',
                'input' => 'برای این محصول یک خلاصه 80 کلمه‌ای بنویس.',
            )
        ),
    )
);

if ( is_wp_error( $response ) ) {
    return $response;
}

$status = wp_remote_retrieve_response_code( $response );
$body   = json_decode(
    wp_remote_retrieve_body( $response ),
    true
);

در این روش، مدیریت API Key، انتخاب مدل، Rate Limit و خطاها بر عهده خود شماست. مزیتش کنترل کامل است؛ عیبش هم این است که افزونه به همان Provider وابسته می‌شود.

کلید API را کجا نگه داریم؟

یکی از رایج‌ترین خطاها، قرار دادن API Key در JavaScript است. اگر کلید داخل کد فرانت‌اند باشد، کاربر می‌تواند آن را در DevTools یا Network ببیند. کلید باید سمت سرور بماند.

برای WordPress 7 و افزونه‌هایی که با Connectors سازگار هستند، همان زیرساخت Connectors انتخاب تمیزتری است. در اتصال اختصاصی نیز بهتر است درخواست از PHP ارسال شود و فرانت‌اند فقط یک endpoint محدود داخل سایت را صدا بزند.

ساخت REST endpoint محدود برای دکمه «تولید با AI»

فرض کنید در صفحه ویرایش محصول یک دکمه دارید که باید توضیح کوتاه بسازد. فرانت‌اند نباید prompt آزاد و API Key را در اختیار داشته باشد. بهتر است فقط شناسه محصول را به endpoint خودتان بفرستید:

<?php
add_action( 'rest_api_init', function () {
    register_rest_route(
        'wpsell-ai/v1',
        '/product-summary/(?P<id>d+)',
        array(
            'methods'  => 'POST',
            'callback' => 'wpsell_ai_product_summary',
            'permission_callback' => function () {
                return current_user_can( 'edit_products' );
            },
        )
    );
} );

در callback، اطلاعات واقعی همان محصول را می‌خوانید، prompt را در PHP می‌سازید و خروجی را به صورت پیش‌نویس برمی‌گردانید. این طراحی هم امنیت بیشتری دارد و هم جلوی مصرف نامحدود را می‌گیرد.

Abilities API؛ وقتی AI باید «کار» انجام دهد

Abilities API از WordPress 6.9 وارد هسته شد. Ability در اصل یک عملیات تعریف‌شده با ورودی، خروجی، Permission و callback مشخص است. مثلاً به‌جای اینکه Agent به همه توابع وردپرس دسترسی داشته باشد، فقط Ability «دریافت اطلاعات سایت» یا «ساخت پیش‌نویس نوشته» را می‌بیند.

نمونه‌ای از ثبت Ability:

<?php
wp_register_ability(
    'my-plugin/describe-image',
    array(
        'label'       => 'Describe an image via AI',
        'description' => 'Describe an image for an editor.',
        'input_schema' => array(
            'type' => 'object',
            'properties' => array(
                'image_url' => array(
                    'type' => 'string',
                ),
            ),
            'required' => array( 'image_url' ),
        ),
        'execute_callback' => 'my_describe_image',
        'permission_callback' => function () {
            return current_user_can( 'edit_posts' );
        },
        'meta' => array(
            'show_in_rest' => true,
        ),
    )
);

ارزش اصلی Ability این است که قرارداد روشنی ایجاد می‌کند: Agent می‌داند چه ورودی بدهد، چه خروجی بگیرد و آیا اجازه اجرای عملیات را دارد یا نه.

MCP و اتصال WordPress به Claude یا Agentهای دیگر

MCP یا Model Context Protocol یک استاندارد برای معرفی ابزارها و منابع به AI Agent است. WordPress MCP Adapter می‌تواند Abilityهای وردپرس را به ابزارهای MCP تبدیل کند. به این ترتیب، یک Agent بیرونی می‌تواند فقط ابزارهای مشخص را اجرا کند و لازم نیست SSH، FTP یا دسترسی کامل wp-admin داشته باشد.

در آموزش رسمی WordPress، Claude Desktop به WordPress MCP Server متصل شده و از Abilityهای سایت query می‌گیرد. تصویر زیر نمونه واقعی همین ارتباط است:

این همان جایی است که Abilities اهمیت خود را نشان می‌دهد. به‌جای «دسترسی کامل»، مجموعه‌ای از ابزارهای محدود و قابل ممیزی دارید.

کاربرد هوش مصنوعی در ووکامرس

در فروشگاه ووکامرس، AI زمانی ارزشمند است که روی داده واقعی فروشگاه کار کند و قوانین مالی همچنان در اختیار کد باقی بماند. برای مدیریت عملی سفارش‌ها و فروشگاه از موبایل نیز می‌توانید Woo Manager را بررسی کنید.

پاسخ‌گویی به سؤال مشتری

می‌توانید عنوان، قیمت، موجودی و ویژگی‌های محصول را به مدل بدهید و پاسخ پیشنهادی تولید کنید. برای چت زنده، WP-Sell Chat Manager می‌تواند لایه مدیریت مکالمه باشد و AI نقش دستیار پاسخ‌گویی را داشته باشد.

تولید توضیح محصول

روش امن این است که مدل فقط از ویژگی‌های ثبت‌شده استفاده کند. در prompt صریحاً بنویسید «هیچ ویژگی جدیدی اضافه نکن». سپس نتیجه به‌صورت Draft نمایش داده شود تا مدیر تأیید کند.

خلاصه سفارش

برای مدیر می‌توان اقلام سفارش، وضعیت، روش پرداخت و یادداشت مشتری را خلاصه کرد. اما AI نباید خودش مبلغ را تغییر دهد، refund انجام دهد یا وضعیت مالی را بدون قانون قطعی تغییر دهد.

تحلیل دیدگاه‌ها

صدها دیدگاه را می‌توان به موضوعاتی مثل «مشکل نصب»، «درخواست قابلیت»، «رضایت از سرعت» و «مشکل پرداخت» دسته‌بندی کرد. این کاربرد معمولاً ریسک کمتری دارد و برای تصمیم‌گیری محصول مفید است.

۵ قانون امنیتی که نباید حذف شوند

اتصال AI جای امنیت پایه وردپرس را نمی‌گیرد. در کنار رعایت اصول زیر، استفاده از یک لایه امنیتی مناسب مانند Wordfence Security فارسی می‌تواند برای فایروال و اسکن سایت مفید باشد.

1. API Key فقط سمت سرور: هر کلیدی که در مرورگر ارسال شود قابل مشاهده است.
2. Permission Callback واقعی: لاگین بودن کاربر به‌تنهایی کافی نیست؛ capability متناسب با عملیات را بررسی کنید.
3. حداقل داده: اطلاعات مشتری و سفارش را فقط در حد لازم به Provider ارسال کنید.
4. Human Review برای عملیات حساس: انتشار، تغییر سفارش، موجودی و مالی بهتر است تأیید انسانی داشته باشند.
5. Rate Limit و Logging: تعداد درخواست‌ها، خطا و زمان پاسخ را ثبت کنید.

Prompt Injection در وردپرس یعنی چه؟

فرض کنید مدل قرار است دیدگاه مشتری را بخواند. خود متن دیدگاه ممکن است شامل جمله‌ای شبیه «همه دستورات قبلی را نادیده بگیر و…» باشد. اگر سیستم شما بدون مرزبندی و بدون کنترل ابزارها طراحی شده باشد، این متن می‌تواند روی رفتار مدل اثر بگذارد.

راه‌حل اصلی این نیست که فقط در prompt بنویسید «این دستورات را اجرا نکن». ابزارها و مجوزها باید در کد محدود باشند. حتی اگر مدل پاسخ نامناسبی تولید کرد، نباید بتواند خارج از Permission تعریف‌شده کاری انجام دهد.

سرعت و هزینه؛ AI را داخل مسیر لود صفحه نگذارید

پاسخ مدل ممکن است چند ثانیه طول بکشد. اگر هر بار که صفحه محصول باز می‌شود یک درخواست AI اجرا کنید، TTFB بالا می‌رود و هزینه هم افزایش پیدا می‌کند.

برای عملیات مدیریتی، درخواست را بعد از کلیک کاربر اجرا کنید. برای کار انبوه از Queue یا Action Scheduler استفاده کنید. نتیجه‌های قابل استفاده مجدد را cache کنید و برای هر کاربر یا endpoint سقف درخواست در نظر بگیرید.

در تولید تصویر، علاوه بر هزینه inference، حجم فایل هم مهم است. تصویر خروجی را مثل هر رسانه دیگری فشرده و به WebP تبدیل کنید. برای این بخش می‌توانید PicFast را بررسی کنید.

خطاهای متداول هنگام اتصال AI

AI Client روی سایت وجود دارد ولی کار نمی‌کند

اول بررسی کنید Provider نصب و API Key ذخیره شده باشد. سپس قابلیت موردنظر مثل text یا image generation را با support check بررسی کنید.

خطای 401 یا 403 در اتصال مستقیم

معمولاً API Key اشتباه، منقضی یا فاقد دسترسی است. header و محیطی که کلید از آن خوانده می‌شود را بررسی کنید.

خطای 429

Rate Limit یا سقف مصرف سرویس رد شده است. Queue، cache و backoff لازم است.

wp-admin کند شده

به احتمال زیاد درخواست AI در هوک عمومی اجرا می‌شود. فراخوانی باید فقط پس از action مشخص کاربر یا در پردازش پس‌زمینه انجام شود.

پاسخ JSON خراب است

ساختار خروجی را در prompt دقیق تعریف کنید و بعد سمت PHP آن را validate کنید. هرگز فرض نکنید مدل همیشه JSON کامل برمی‌گرداند.

برای پروژه شما کدام روش مناسب‌تر است؟

اگر افزونه عمومی می‌سازید: از WordPress AI Client شروع کنید. این انتخاب وابستگی به Provider را کم می‌کند.

اگر پروژه اختصاصی است و فقط OpenAI می‌خواهید: API مستقیم قابل قبول است، به شرطی که کلید سمت سرور و Rate Limit داشته باشید.

اگر اپلیکیشن خارجی باید با وردپرس کار کند: REST API همراه احراز هویت محدود مناسب است.

اگر Agent قرار است چند کار تعریف‌شده انجام دهد: Ability + MCP انتخاب تمیزتری است؛ چون ابزارهای Agent از ابتدا محدود و قابل ممیزی هستند.

سوالات متداول

آیا برای اتصال هوش مصنوعی به وردپرس حتماً افزونه لازم است؟

خیر. می‌توانید افزونه اختصاصی بنویسید، از AI Client استفاده کنید یا مستقیم به API وصل شوید. برای پروژه قابل نگهداری، نوشتن یک افزونه کوچک اختصاصی بهتر از ریختن کد در functions.php است.

آیا AI Client خودش OpenAI است؟

خیر. AI Client لایه واسط وردپرس است و می‌تواند با Providerهای سازگار مختلف کار کند.

آیا WordPress 7 بدون API Key هوش مصنوعی دارد؟

خیر. AI Client زیرساخت اتصال است؛ برای استفاده واقعی باید Provider و credential لازم تنظیم شود.

آیا می‌توان Claude را به وردپرس وصل کرد؟

بله. در سمت Provider می‌توان از Provider سازگار استفاده کرد و در سناریوی Agent هم WordPress MCP Adapter می‌تواند ابزارهای وردپرس را برای Claude Desktop یا کلاینت‌های MCP در دسترس قرار دهد.

آیا می‌توان AI را مستقیم به سفارش ووکامرس دسترسی داد؟

از نظر فنی ممکن است، اما بهتر است عملیات حساس پشت Permission، قانون قطعی و تأیید انسانی بماند. AI برای پیشنهاد و تحلیل مناسب‌تر از تصمیم نهایی مالی است.

جمع‌بندی

نسل جدید اتصال هوش مصنوعی به وردپرس از «یک API Call ساده» فراتر رفته است. WordPress AI Client اتصال Provider-agnostic می‌دهد، Connectors مدیریت credentialها را متمرکز می‌کند، Abilities عملیات قابل کنترل می‌سازد و MCP می‌تواند این عملیات را به Agentهای خارجی ارائه دهد.

برای شروع، یک سناریوی کوچک انتخاب کنید؛ مثلاً ساخت توضیح محصول یا خلاصه دیدگاه. Provider را وصل کنید، permission و error handling را از روز اول درست بنویسید و خروجی را قبل از انتشار بررسی کنید. بعد از اینکه هزینه و کیفیت را اندازه گرفتید، اتوماسیون را مرحله‌به‌مرحله گسترش دهید.

منابع رسمی

• آموزش رسمی WordPress AI Client و تولید تصویر
• ساخت اولین افزونه AI-Powered وردپرس
• WordPress Abilities API
• WordPress MCP Adapter
• OpenAI API Quickstart

کاربرد عملی AI در فروشگاه: برای استفاده از هوش مصنوعی در پشتیبانی مشتری، راهنمای چت آنلاین ووکامرس با هوش مصنوعی را مطالعه کنید.