{"id":11113,"date":"2026-03-13T03:29:58","date_gmt":"2026-03-13T07:29:58","guid":{"rendered":"https:\/\/chubes.net\/?documentation=wp-agent-setup"},"modified":"2026-03-13T03:29:58","modified_gmt":"2026-03-13T07:29:58","slug":"wp-agent-setup","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/wp-agent\/wp-agent-setup\/","title":{"rendered":"WP Agent \u2014 Setup"},"content":{"rendered":"<p>WP Agent is a WordPress-native AI agent runtime. It runs inside your site and can be used through multiple interfaces:<\/p><ul class=\"wp-block-list\"><li>WordPress admin + REST API<\/li><li>WP-CLI<\/li><li>Chat apps (Discord \/ Telegram)<\/li><li>Optional on-site Chat block<\/li><\/ul><h2 class=\"wp-block-heading\">Requirements<\/h2><ul class=\"wp-block-list\"><li>WordPress 6.9+<\/li><li>PHP 8.1+<\/li><\/ul><h2 class=\"wp-block-heading\">Install<\/h2><ol class=\"wp-block-list\"><li>Upload\/install the plugin zip or clone into:\n<code>wp-content\/plugins\/wp-agent\/<\/code><\/li><li>Activate <strong>WP Agent<\/strong> in WP Admin \u2192 Plugins.<\/li><\/ol><h2 class=\"wp-block-heading\">Configure AI Provider<\/h2><p>Go to <strong>Settings \u2192 WP Agent<\/strong>.<\/p><ul class=\"wp-block-list\"><li>Provider: choose the provider<\/li><li>Model: choose the model<\/li><li>API Key:<ul class=\"wp-block-list\"><li>Either set <code>wp_agent_api_key<\/code> in settings, <strong>or<\/strong><\/li><li>Provide a shared key via the <code>chubes_ai_provider_api_keys<\/code> filter (advanced)<\/li><\/ul><\/li><\/ul><h2 class=\"wp-block-heading\">Execution policy (security tiers)<\/h2><p>WP Agent can run with different execution tiers. Default is <strong>wp-native<\/strong>.<\/p><ul class=\"wp-block-list\"><li>Either set <code>wp_agent_api_key<\/code> in settings, <strong>or<\/strong><\/li><li>Provide a shared key via the <code>chubes_ai_provider_api_keys<\/code> filter (advanced)<\/li><\/ul><p>Configure this in <strong>Settings \u2192 WP Agent \u2192 Execution Policy<\/strong>.<\/p><h2 class=\"wp-block-heading\">Use WP Agent<\/h2><h3 class=\"wp-block-heading\">Option A \u2014 WordPress REST API (admin)<\/h3><p>Endpoint:<\/p><ul class=\"wp-block-list\"><li>Either set <code>wp_agent_api_key<\/code> in settings, <strong>or<\/strong><\/li><li>Provide a shared key via the <code>chubes_ai_provider_api_keys<\/code> filter (advanced)<\/li><\/ul><p>Requires:<\/p><ul class=\"wp-block-list\"><li><strong>wp-native<\/strong>: WordPress-native abilities only (no shell dependence)<\/li><li><strong>restricted-shell<\/strong>: allowlisted shell access for admin users<\/li><li><strong>extended-shell<\/strong> \/ <strong>trusted<\/strong>: advanced modes (only enable when you understand the risk)<\/li><\/ul><h3 class=\"wp-block-heading\">Option B \u2014 WP-CLI<\/h3><p>Examples:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">wp agent status\nwp agent chat &quot;List active plugins&quot;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Option C \u2014 Discord \/ Telegram<\/h3><p>Configure channel settings in <strong>Settings \u2192 WP Agent \u2192 Channels<\/strong>.<\/p><h3 class=\"wp-block-heading\">Option D \u2014 On-site Chat block (optional)<\/h3><p>Insert the block:<\/p><ul class=\"wp-block-list\"><li><code>POST \/wp-json\/wp-agent\/v1\/chat<\/code><\/li><\/ul><p>Notes:<\/p><ul class=\"wp-block-list\"><li>logged-in user with <code>manage_options<\/code><\/li><li>a valid WP REST nonce<\/li><\/ul><h2 class=\"wp-block-heading\">Making channels reactive<\/h2><p>WP Agent runs using Action Scheduler (preferred) with WP-Cron as a fallback.<\/p><p>On low-traffic sites, <strong>WP-Cron\/Action Scheduler may not run promptly<\/strong> unless something triggers them.<\/p><p>When an inbound message is received (webhook\/REST), WP Agent will enqueue it and <strong>trigger an async Action Scheduler run<\/strong> (when available) to process the queue ASAP.<\/p><h3 class=\"wp-block-heading\">Recommended: system cron runs Action Scheduler (most reliable)<\/h3><p>If you have server cron access, add a job (example: every minute):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">cron<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-cron\"><code class=\"language-cron\">* * * * * cd \/var\/www\/your-site &amp;&amp; wp action-scheduler run --due-now --quiet --allow-root<\/code><\/pre><\/div><p>(Use the correct site path and drop <code>--allow-root<\/code> if you\u2019re not root.)<\/p><h3 class=\"wp-block-heading\">Alternative: system cron hits wp-cron.php<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">cron<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-cron\"><code class=\"language-cron\">* * * * * curl -fsS https:\/\/example.com\/wp-cron.php?doing_wp_cron &gt;\/dev\/null 2&gt;&amp;1<\/code><\/pre><\/div><p>This is less direct, but works on hosts where WP-CLI cron isn\u2019t possible.<\/p><h3 class=\"wp-block-heading\">Notes<\/h3><ul class=\"wp-block-list\"><li>Block name: <strong>WP Agent Chat<\/strong> (<code>wp-agent\/chat<\/code>)<\/li><\/ul><h2 class=\"wp-block-heading\">Troubleshooting<\/h2><ul class=\"wp-block-list\"><li>This is <em>one<\/em> interface option.<\/li><li>The chat endpoint is authenticated (admin-only) by default.<\/li><li>Image support is available (upload requires Media permissions).<\/li><\/ul>","protected":false},"excerpt":{"rendered":"<p>WP Agent is a WordPress-native AI agent runtime. It runs inside your site and can be used through multiple interfaces: WordPress admin + REST API WP-CLI Chat apps (Discord \/&#8230;<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[753],"project_type":[],"class_list":["post-11113","documentation","type-documentation","status-publish","hentry","project-wp-agent"],"project_info":{"id":753,"name":"WP Agent","slug":"wp-agent"},"project_type_info":{"id":484,"name":"WordPress Plugins","slug":"wordpress-plugins"},"_links":{"self":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/11113","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation"}],"about":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/types\/documentation"}],"version-history":[{"count":0,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/11113\/revisions"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=11113"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=11113"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=11113"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=11113"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}