dwindown/wp-agentic-writer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
44e06eed883d9581e1f6c4632365759df33eb341
wp-agentic-writer/docs/architecture/HYBRID-PROVIDER-WALKTHROUGH.md

12 KiB
Raw Blame History

Hybrid AI Provider System - User Walkthrough

Overview

The WP Agentic Writer plugin now supports multiple AI providers for different tasks:

Provider Use Case Cost Best For
Local Backend Text generation (chat, planning, writing) $0 Daily use, privacy, unlimited generation
Codex Alternative text provider Per-token When Local Backend unavailable
OpenRouter Image generation + fallback Per-token Images, fallback when local offline

The magic: Route text tasks to your free local Claude CLI, images to OpenRouter's best models.

Quick Start (5 Minutes)

Step 1: Check Prerequisites

You need:

  • ✅ Claude CLI installed (claude --version should work)
  • ✅ Node.js 18+ installed (node --version)
  • ✅ Z.ai subscription or Anthropic API key configured in Claude CLI

Don't have these? Get them first:

Step 2: Download & Start Local Backend

  1. In WordPress Admin, go to Settings → Agentic Writer → Local Backend
  2. Click "Download Local Backend v1.0.0"
  3. Extract the ZIP to a folder on your machine
  4. Open terminal in that folder
  5. Run: ./start-proxy.sh

You'll see output like:

🚀 Starting Claude Proxy Server...
📦 Installing dependencies...
✅ Dependencies installed

🌐 Local Backend is running!
   Base URL: http://192.168.1.105:8080
   Health Check: http://192.168.1.105:8080/ping

💡 To test: ./test-connection.sh
💡 To stop: ./stop-proxy.sh

Copy the Base URL (e.g., http://192.168.1.105:8080)

Step 3: Configure Plugin

  1. In WordPress, paste the Base URL into "Base URL" field
  2. Leave API Key as dummy (ignored by local proxy)
  3. Click "Test Connection"
  4. You should see: ✅ Connected! Proxy responding correctly.

Step 4: Set Provider Routing (Optional)

By default, all text tasks use your Local Backend (free). To customize:

  1. In the Local Backend tab, scroll to "Provider Routing"

  2. Choose provider per task:

    • Chat → Local Backend (free)
    • Clarity Check → Local Backend (free)
    • Outline Planning → Local Backend (free)
    • Article Writing → Local Backend (free)
    • Content Refinement → Local Backend or Codex
    • Image Generation → OpenRouter (only option)

  3. Click "Save Settings"

Step 5: Generate Content

  1. Open any post in Gutenberg editor
  2. Click the Agentic Writer sidebar (🤖 icon)
  3. Type a topic like: "Write about AI trends in 2025"
  4. Watch as content generates with $0.00 cost!

Provider Deep Dive

🏠 Local Backend (Recommended)

What it is: A Node.js proxy running on your machine that connects to your Claude CLI.

Why use it:

  • 💰 $0 cost for unlimited text generation
  • 🔒 Privacy - content never leaves your machine
  • ⚡ Speed - LAN latency vs cloud round-trip
  • 🎛️ Same quality - uses same Claude models as cloud

How it works:

WordPress → Your Computer (proxy) → Claude CLI → Z.ai/Anthropic

Limitations:

  • One request at a time (Claude CLI limitation)
  • Must keep terminal open with proxy running
  • Requires your computer to be on and on same network

Setup:

# Terminal 1: Start proxy
cd agentic-writer-local-backend
./start-proxy.sh

# Keep this terminal open while using the plugin

🔗 Codex (OpenAI)

What it is: Direct integration with OpenAI's API.

Why use it:

  • ☁️ Cloud reliability - works from anywhere
  • 🎯 High quality - excellent for technical content
  • 📱 Mobile friendly - doesn't require your computer

How to enable:

  1. Get OpenAI API key: https://platform.openai.com
  2. Go to Settings → Agentic Writer → General
  3. Add Codex API Key field (new field in settings)
  4. Set task provider to "Codex"

Cost: Per OpenAI pricing (~$0.002-0.03 per 1K tokens)

☁️ OpenRouter (Fallback)

What it is: The original cloud provider (still works great!).

Primary use:

  • 🖼️ Image generation (FLUX, Recraft, GPT-4o)
  • 🔄 Automatic fallback when Local Backend is offline

You already have this configured - it's the original system.

Configuration Examples

Example 1: All Local (Maximum Savings)

Goal: Pay $0 for all text generation

Settings:

Provider Routing:
  Chat       → Local Backend
  Clarity    → Local Backend
  Planning   → Local Backend
  Writing    → Local Backend
  Refinement → Local Backend
  Image      → OpenRouter

Expected cost: $0 for text, ~$0.05 per image

Example 2: Hybrid (Balanced)

Goal: Free for most tasks, cloud for refinement

Settings:

Provider Routing:
  Chat       → Local Backend
  Clarity    → Local Backend
  Planning   → Local Backend
  Writing    → Local Backend
  Refinement → Codex (cloud quality)
  Image      → OpenRouter

Expected cost: ~$0.10-0.30 per article (refinement only)

Example 3: Cloud Production (No Local)

Goal: Works from anywhere, no local setup

Settings:

Provider Routing:
  All tasks → OpenRouter

Expected cost: ~$0.50-2.00 per article

Troubleshooting

❌ "Connection failed" when testing

Symptoms: Red error message in settings

Solutions:

  1. Is proxy running?

    # Check if Node.js process is running
ps aux | grep claude-proxy

# If not, start it:
./start-proxy.sh

  2. Wrong IP address?

    # Find your correct local IP
./get-local-ip.sh

# Or manually:
# macOS: ifconfig | grep "inet "
# Linux: ip addr show
# Windows: ipconfig

  3. Firewall blocking?

    • macOS: System Preferences → Security → Firewall → Allow Node.js
    • Linux: sudo ufw allow 8080
    • Windows: Windows Defender → Allow app → Node.js

❌ "Claude CLI not responding"

Symptoms: Proxy starts but AI calls fail

Solutions:

  1. Test Claude CLI directly:

    echo "Say hello" | claude

    If this fails, Claude CLI isn't configured properly.

  2. Check Z.ai/Anthropic setup:

    claude config get apiKey

    Should show your API key. If empty:

    claude config set apiKey YOUR_API_KEY

  3. Re-authenticate:

    claude auth login

❌ "Proxy responded but with unexpected format"

Symptoms: Ping works but inference fails

Solutions:

  1. Check proxy logs:

    # In proxy folder
cat proxy.log

  2. Restart proxy:

    ./stop-proxy.sh
./start-proxy.sh

  3. Test manually:

    ./test-connection.sh

❌ Content generates but cost shows in dashboard

Symptoms: Expecting $0 but seeing charges

Check:

  1. Go to Settings → Local Backend → Provider Routing
  2. Verify tasks are set to "Local Backend" not "OpenRouter"
  3. Check that Local Backend URL is saved (not empty)
  4. Test connection - should show ✅

Fallback behavior: If Local Backend is unreachable, plugin auto-switches to OpenRouter (and charges apply).

Advanced Tips

Tip 1: Running Proxy on a Different Machine

You can run the proxy on a dedicated machine (e.g., home server) and connect WordPress from anywhere:

On server (192.168.1.50):

./start-proxy.sh
# Shows: http://192.168.1.50:8080

In WordPress:

Base URL: http://192.168.1.50:8080

Requirements:

  • Both on same network (or VPN)
  • Server has Claude CLI + Z.ai configured
  • Port 8080 open on server firewall

Tip 2: Using with Cloud-Hosted WordPress

The challenge: Your WordPress is on a server, but proxy needs to be on your machine.

Solutions:

Option A: VPN/Network Bridge

  • Install Tailscale or similar on both machines
  • WordPress connects via Tailscale IP

Option B: SSH Tunnel

# From your local machine
ssh -R 8080:localhost:8080 user@wordpress-server

Option C: Use Codex/OpenRouter

  • Skip Local Backend for cloud WordPress
  • Use Codex or OpenRouter (cloud providers)

Tip 3: Auto-Start Proxy

macOS (LaunchAgent):

<!-- ~/Library/LaunchAgents/com.agenticwriter.proxy.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agenticwriter.proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/agentic-writer-local-backend/start-proxy.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Linux (systemd):

# ~/.config/systemd/user/claude-proxy.service
[Unit]
Description=Claude Proxy for WP Agentic Writer

[Service]
Type=simple
WorkingDirectory=/path/to/agentic-writer-local-backend
ExecStart=/path/to/agentic-writer-local-backend/start-proxy.sh
Restart=always

[Install]
WantedBy=default.target

Tip 4: Monitoring Proxy

Check if proxy is running:

# Quick check
curl http://192.168.1.105:8080/ping
# Should return: pong

Watch logs:

# In proxy folder
tail -f proxy.log

Auto-restart if crashed:

# Add to crontab
*/5 * * * * /path/to/agentic-writer-local-backend/start-proxy.sh >/dev/null 2>&1

Cost Comparison

Scenario Monthly Usage Old Cost (OpenRouter) New Cost (Hybrid) Savings
Light blogger 10 articles $5-10 $0-2 80%
Content agency 100 articles $50-100 $5-10 90%
Heavy user 500 articles $250-500 $20-40 92%
Image-heavy 50 images $2.50 $2.50 0%

Assumptions:

  • Text tasks use Local Backend (free)
  • Images use OpenRouter ($0.05 each)
  • Occasional Codex refinement ($0.20 per article)

FAQ

Q: Is Local Backend really free?

A: Yes! It uses your existing Claude CLI + Z.ai/Anthropic subscription. The proxy just connects WordPress to your local Claude. Your Z.ai subscription covers the usage.

Q: What if my computer is off?

A: The plugin automatically falls back to OpenRouter. You'll see a notice: "Local Backend unavailable, using OpenRouter."

Q: Can multiple WordPress sites use one proxy?

A: Yes! Just point all sites to the same http://your-ip:8080. Only one request processes at a time (Claude CLI limitation).

Q: Is my content private?

A: With Local Backend, yes! Content goes:

  • WordPress → Your Computer → Claude CLI → Z.ai

Never passes through our servers or third-party APIs (except Z.ai/Anthropic which you already use).

Q: Can I use Ollama instead of Claude CLI?

A: Not currently. The proxy is designed for Claude CLI. Future versions may support Ollama.

Q: Why is streaming not working?

A: Local Backend currently uses non-streaming (full response). This is a Claude CLI limitation. Codex and OpenRouter support streaming.

Q: How do I update the proxy?

A: Download the latest ZIP from plugin settings and replace your proxy folder. Your configuration (Base URL in WordPress) stays the same.

Migration from Old System

If you were using OpenRouter only:

  1. ✅ Nothing breaks - plugin defaults to OpenRouter
  2. ✅ All settings preserved - API key, models, etc.
  3. ➕ New option - add Local Backend anytime

To add Local Backend:

  1. Follow Quick Start above
  2. No need to change existing content or settings
  3. Gradually switch tasks to Local Backend

Getting Help

Documentation

  • This walkthrough (you're reading it!)
  • TROUBLESHOOTING.md (in proxy package)
  • README.md (in proxy package)

Community

  • GitHub Issues: [plugin-repo]/issues
  • Discord: [community-link]

Debug Info

When reporting issues, include:

1. Proxy version: cat package.json | grep version
2. Claude version: claude --version
3. Node version: node --version
4. Connection test result: ./test-connection.sh
5. WordPress version
6. Plugin version

Next Steps

  1. ✅ Download Local Backend
  2. ✅ Configure Plugin
  3. ✅ Test Generation
  4. 📖 Read Troubleshooting if needed
  5. 🚀 Enjoy unlimited free AI generation!

Last updated: 2026-02-27 Plugin version: 0.3.0 Proxy version: 1.0.0

Reference in New Issue View Git Blame Copy Permalink