🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί AI Orchestrator
πŸ¦€ ClawHub

AI Orchestrator

by @ciklopentan

DeepSeek AI access via Puppeteer browser automation with CDP interceptor. Persistent daemon (~35ms startup), health checks, graceful shutdown, PM2 management...

Versionv2.0.11
Downloads843
Stars⭐ 1
#legal#health#automation#productivity
TERMINAL
clawhub install ai-orchestrator

πŸ“– About This Skill

name: ai-orchestrator description: > DeepSeek AI access via Puppeteer browser automation with CDP interceptor. Persistent daemon (~35ms startup), health checks, graceful shutdown, PM2 management. Configurable via .deepseek.json. Use when: (1) need DeepSeek responses without API key, (2) code analysis, review, or generation, (3) text analysis, summarization, translation, (4) "consult DeepSeek" or ask-deepseek.sh.

AI Orchestrator v2.0.11

What this is: Browser automation that talks to DeepSeek via Puppeteer. What this is NOT: A general AI router or multi-model orchestrator. It's one browser β†’ one LLM.

Execution

Working directory rule: Unless a command here uses an absolute path, run ai-orchestrator commands from the skill root: ~/.openclaw/workspace/skills/ai-orchestrator. If you are not already there, run:

cd ~/.openclaw/workspace/skills/ai-orchestrator

Relative paths such as .daemon-ws-endpoint, .profile/, .deepseek.json, and scripts/setup-daemon.sh assume this directory.

Quick Start

# Simple question
ask-deepseek.sh "What is HTTP?"
Session (keeps context between questions)

ask-deepseek.sh "Explain OAuth2" --session work
ask-deepseek.sh "What about OpenID Connect?" --session work
ask-deepseek.sh --session work --end-session
With daemon (fast startup ~35ms vs ~15s cold)

ask-deepseek.sh "Question" --daemon
Pipe code or long prompts

cat code.py | ask-deepseek.sh "Find bugs"
ask-deepseek.sh --stdin < code.py
ask-deepseek.sh <<'EOF'
Long multi-line prompt here
EOF

When to use ai-orchestrator

| Task | ai-orchestrator | Direct API | Manual browser | |------|----------------|------------|----------------| | Code analysis / review | βœ… Fast, no API key | Needs API | ❌ Slow | | Text analysis / summary | βœ… (with --daemon) | Needs API | ❌ Tedious | | Brainstorming | ❌ (use Dual Thinking skill) | Needs API | ❌ | | Web scraping | ❌ Wrong tool | ❌ | βœ… | | API testing | ❌ Overkill | βœ… | ❌ | | CAPTCHA solving | ❌ Will fail | ❌ | βœ… (manual) |

Rule: Need LLM reasoning without API key β†’ ai-orchestrator. Need browser tasks (scrape, click, fill forms) β†’ use agent-browser skill instead.

Default site mode: ai-orchestrator must keep DeepSeek in Expert mode whenever the site exposes the Instant / Expert switch. Treat Expert as the canonical default. Do not fall back to Instant unless a future implementation explicitly adds an override and the user asks for it.

Session continuity: in daemon mode, follow-up requests using --session NAME must restore the exact saved DeepSeek chatUrl for that session unless --new-chat was explicitly requested. Reusing an arbitrary open DeepSeek tab is incorrect because it breaks multi-round review continuity.

All Flags

| Flag | Purpose | |------|---------| | --session NAME | Persistent context across requests (keeps chat history) | | --daemon | Use running Chrome daemon (~35ms startup) | | --search | Enable DeepSeek web search capability | | --think | Enable DeepThink site mode (deeper reasoning) | | --new-chat | Start new chat within existing session | | --end-session | Close and clean up session | | --visible | Open visible browser (for auth/CAPTCHA fixes) | | --wait | Wait for manual auth completion (with --visible) | | --close | Force close browser after request | | --dry-run | Test auth + composer without sending prompt | | --stdin | Explicitly read prompt body from stdin | | --debug | Verbose debug output | | --verbose | More detailed logs | | -h, --help | Show help |

Health check

# 1. Daemon running?
pm2 status | grep -q "deepseek.*online" || echo "Daemon down"
2. Dry-run path works?

ask-deepseek.sh --dry-run --daemon || echo "DeepSeek dry-run failed"  # Checks auth + composer through the daemon path
3. Real response path works?

ask-deepseek.sh "OK" --daemon | grep -q "OK" || echo "DeepSeek not responding"

If any step fails, do not improvise. Use the troubleshooting ladder below.

Failure Recovery (mandatory routing)

First failure rule β€” do not skip

When any command fails: 1. STOP β€” do not try a random second fix yet 2. CAPTURE β€” read the exact error you saw 3. MATCH β€” find the closest symptom row below 4. RUN β€” execute that row's exact command 5. VERIFY β€” retry with the specified verification command

Symptom β†’ exact command

| If you see this symptom | Run this exact command | Then verify with | |---|---|---| | Connection refused, ECONNREFUSED, daemon not online | pm2 restart deepseek-daemon && sleep 8 && ask-deepseek.sh --dry-run --daemon | ask-deepseek.sh "Say OK" --daemon | | auth expired, CAPTCHA, login page, 401, 403 | cd ~/.openclaw/workspace/skills/ai-orchestrator && pm2 stop deepseek-daemon && rm -f .daemon-ws-endpoint && bash ask-deepseek.sh --visible --wait --dry-run && pm2 start deepseek-daemon | bash ask-deepseek.sh --dry-run --daemon | | response cuts off / incomplete long answer | ask-deepseek.sh "Part 1" --session temp && ask-deepseek.sh "Continue with next part" --session temp | ask-deepseek.sh --session temp --end-session | | lock, Singleton, profile already in use | cd ~/.openclaw/workspace/skills/ai-orchestrator && rm -f .profile/Singleton* && pm2 restart deepseek-daemon | bash ask-deepseek.sh --dry-run | | timeout, selector missing, composer not found | ask-deepseek.sh --dry-run --visible | only after manual inspection consider selector edits |

If 3 fixes failed already

Do not keep guessing. Reset to a known-good baseline:

cd ~/.openclaw/workspace/skills/ai-orchestrator
pm2 stop deepseek-daemon
pkill -f puppeteer || true
rm -f .daemon-ws-endpoint .profile/Singleton*
bash scripts/setup-daemon.sh
bash ask-deepseek.sh "Say OK" --daemon

If that still fails, escalate to manual auth/inspection with --visible --wait.

Manual Auth with --wait

--wait blocks until you complete auth in the visible browser or interrupt the command yourself. There is no automatic timeout documented here. Use Ctrl+C if you need to abort.

Daemon Setup

One-liner: 
cd ~/.openclaw/workspace/skills/ai-orchestrator && bash scripts/setup-daemon.sh

Or manual: 

bash scripts/setup-daemon.sh  # Or run step-by-step below
npm install   # First time only
pm2 start deepseek-daemon.js --name deepseek-daemon --no-autorestart
pm2 save
pm2 startup   # Auto-start on boot

Exit Codes

| Code | Meaning | Action | |------|---------|--------| | 0 | Success β€” response received | Continue | | 1 | Config/arg error | Check flags, run --help | | 2 | DeepSeek unreachable or daemon unavailable | Check network, daemon endpoint, pm2 status | | 3 | Blocked or rate limited | Wait 5s, retry, or use --visible |

Note: Partial success (truncated response) still returns 0. Use "Continue" button handling.

Known Limitations (v2.0.11)

  • Exact-string prompts: DeepSeek may prepend explanation text before the requested suffix. For machine-sensitive checks, prefer structured JSON prompts when possible, or validate that the returned payload still contains the expected terminal token instead of assuming exact literal obedience.
  • Oversized prompts: if a giant single-shot prompt does not actually leave the page, ai-orchestrator now validates submit outcome, retries with adaptive shortening, and fails explicitly with DEEPSEEK_SUBMIT_BLOCKED_OVERSIZE_PROMPT if delivery never succeeds.
  • Publish hygiene: local runtime state must not be published. Before ClawHub publish, verify that .clawhubignore excludes local profile, diagnostics, logs, sessions, and daemon state files.

    • DeepSeek Free Tier Limits

  • Per response: ~13,000 characters (verified 2026-04-03)
  • Button "Continue" auto-clicked up to 30 times
  • Rate limit: 5 seconds between requests
  • Session limit: Use --session for long conversations instead of single huge prompts

    • Workaround for Long Answers (>13k chars)

    ask-deepseek.sh "Write a Python backend guide" --session guide
ask-deepseek.sh "Now cover async and databases" --session guide  # Continue
ask-deepseek.sh --session guide --end-session  # Done

    Logging

    After important orchestrator runs, append to memory/episodic/YYYY-MM-DD.md: 
    ## ai-orchestrator

  • Task: code review app.js (tool: deepseek, duration: 12s, status: success)
    • 

  • Failure: CAPTCHA on deepseek (fallback: manual via --visible)
    •
    Not every request needs logging. Log decisions and failures, not routine questions.

    What NOT to do

  • ❌ Use for web scraping or browser automation (wrong tool β€” use agent-browser skill)
  • ❌ Bypass Dual Thinking for complex decisions (orchestrator executes, doesn't think)
  • ❌ Ignore failure logs (they tell you what's broken)
  • ❌ Run without --daemon unless debugging (cold start = 15s vs 35ms)
  • ❌ Guess random fixes when a known failure case already matches
  • ❌ Open a visible browser first if the problem is only a dead daemon β€” restart daemon first
  • ❌ Keep reusing one broken long prompt after free-tier cutoff β€” switch to --session chunks instead

    • Configuration (.deepseek.json)

    {
  "idleTimeout": 15000,
  "heartbeatInterval": 15000,
  "domErrorIdleMs": 25000,
  "maxContinueRounds": 30,
  "logToFile": true,
  "logPath": ".logs/deepseek.log"
}

    Minimal Contract for Weak Runtimes

  • Exit codes: 0 = success, 1 = config/runtime error, 2 = DeepSeek unreachable or daemon unavailable, 3 = blocked or rate-limited. Never treat 2 or 3 as success.
  • Mode enforcement: when DeepSeek shows Instant / Expert, ai-orchestrator must use Expert unless the user explicitly requests otherwise via a future supported override.
  • Session restore: --session NAME must restore the exact saved chatUrl unless --new-chat was explicitly requested.
  • Publish hygiene: before publishing to ClawHub, ensure .clawhubignore exists and excludes local runtime state.

    • Minimal Decision Rules for Weak Models

    When choosing what to do next, use these defaults:

  • Need fastest normal run β†’ use --daemon
  • Need context across multiple prompts on one topic β†’ use --session
  • Need a brand new DeepSeek chat for that topic β†’ add --new-chat
  • Need to close the topic chat β†’ use --end-session
  • Need auth/login repair β†’ stop daemon first, then --visible --wait --dry-run
  • Need a health check without sending a real prompt β†’ use --dry-run
  • Need a long answer β†’ use --session and split it into chunks
  • Need browser automation on websites β†’ stop and use agent-browser, not ai-orchestrator
  • Need failure recovery β†’ do not guess; use the symptom table above
  • Before every real prompt send, keep the DeepSeek site in Expert mode when that switch exists
  • If --think is used, enable the site DeepThink` toggle before sending the prompt

    • Troubleshooting β†’ REFERENCE.md

    See REFERENCE.md for:
  • Architecture overview (Puppeteer + CDP interceptor)
  • Complete troubleshooting guide
  • Diagnostic system (trace + metrics + summary JSON + file log)
  • Performance benchmarks
  • Common issues: CAPTCHA, rate limits, selector changes, visible-browser vs daemon behavior

    • πŸ’‘ Examples

    # Simple question
ask-deepseek.sh "What is HTTP?"
    Session (keeps context between questions)
    
ask-deepseek.sh "Explain OAuth2" --session work
ask-deepseek.sh "What about OpenID Connect?" --session work
ask-deepseek.sh --session work --end-session
    With daemon (fast startup ~35ms vs ~15s cold)
    
ask-deepseek.sh "Question" --daemon
    Pipe code or long prompts
    
cat code.py | ask-deepseek.sh "Find bugs"
ask-deepseek.sh --stdin < code.py
ask-deepseek.sh <<'EOF'
Long multi-line prompt here
EOF