CellCog + OpenClaw Integration Guide

Use CellCog as an AI execution layer for OpenClaw agents. This guide covers setup, usage, the full ClawHub skills catalog, and advanced features.

What is the CellCog + OpenClaw Integration?

CellCog provides multimodal AI capabilities to OpenClaw agents through:

• CellCog Python SDK — a pip-installable package for programmatic access
• ClawHub Skills — pre-built skills for specific capabilities (research, video, images, coding, etc.)
• Fire-and-Forget Pattern — non-blocking execution so your agents keep working

When an OpenClaw agent needs deep research, content creation, or multimodal output, it delegates to CellCog and continues with other tasks. CellCog notifies the agent when results are ready.

Getting Started

Step 1: Get Your CellCog API Key

1. Sign up at cellcog.ai
2. Subscribe to a plan (minimum 60 credits for Agent mode)
3. Go to Profile → API Keys → Generate API Key
4. Copy and save your key securely

See API Keys Guide for detailed instructions.

Step 2: Install the CellCog Python SDK

bash
pip install cellcog

Step 3: Configure Your API Key

Set via environment variable:

bash
export CELLCOG_API_KEY="sk_your_api_key_here"

The SDK auto-detects the environment variable:

python
from cellcog import CellCogClient

client = CellCogClient(agent_provider="openclaw")

Step 4: Install ClawHub Skills

Install the core skill (required):

bash
clawhub install cellcog

Install capability-specific skills as needed:

bash
clawhub install deep-research-cellcog   # Deep research
clawhub install video-generation-cellcog      # Video generation
clawhub install image-generation-cellcog      # Image generation
clawhub install audio-generation-cellcog      # Audio/speech
clawhub install dashboard-web-app-cellcog       # Interactive dashboards
clawhub install presentation-slides-cellcog     # Presentations
clawhub install pdf-document-generation-cellcog       # Documents (PDF, DOCX)
clawhub install coding-agent-cellcog       # Coding agent (co-work)

See the full Skills Catalog below.

How It Works

Fire-and-Forget Pattern

python
# Agent sends request — returns IMMEDIATELY
result = client.create_chat(
    prompt="Research quantum computing advances in 2026",
    notify_session_key="agent:main:main",
    task_label="quantum-research",
    chat_mode="agent"
)

# Agent continues with other work...
# CellCog daemon monitors progress via WebSocket
# Agent receives notification when complete

What Happens Behind the Scenes

1. Your agent calls create_chat() — returns instantly
2. CellCog's background daemon tracks the chat via WebSocket
3. For long tasks (>4 min), your agent receives interim progress updates
4. When CellCog finishes, your agent gets a completion notification with all results and downloaded files

Sending Follow-Up Messages

python
result = client.send_message(
    chat_id="abc123",
    message="Now create a PDF summary of the findings",
    notify_session_key="agent:main:main",
    task_label="summary"
)

Wait for Completion (Synchronous Workflows)

For sequential workflows where you need results before proceeding:

python
# Block until CellCog finishes
completion = client.wait_for_completion(chat_id="abc123", timeout=1800)
# Returns: {"chat_id", "is_operating", "status", "status_message"}

• When is_operating is False, the chat has completed and results have been delivered
• When True, timeout was reached but CellCog is still working — the daemon will deliver results automatically
• Default timeout: 1800s (30 min). Use 3600s (60 min) for complex jobs

Manual Inspection

python
# Get full chat history
history = client.get_history(chat_id="abc123")

# Quick status check
status = client.get_status(chat_id="abc123")

Interim Progress Updates

For tasks taking >4 minutes, agents automatically receive progress updates:

text
⏳ quantum-research - CellCog is still working

Recent activity from CellCog (newest first):
  • [just now] Generating comparison charts
  • [1m ago] Analyzing breakthrough in error correction
  • [3m ago] Searching for quantum computing research papers

Chat ID: abc123

The daemon collects progress messages from CellCog's WebSocket and delivers them to your agent every 4 minutes, so your agent always knows what's happening.

Available Skills (ClawHub)

Full Catalog

Special Guidance by Capability

• Research (deep-research-cellcog): Citations are NOT automatic — explicitly request them in your prompt if needed.
• Presentations (presentation-slides-cellcog): PDF is the default and recommended output. PPTX quality is lower (~30-40% of PDF). Only request PPTX if editing is essential.
• Memes (meme-generator-cellcog): Agent mode only. Comedy is hard for AI — agent curation after generation is mandatory.
• Podcasts (podcast-generation-cellcog): Agent mode. Default output: [Intro Music] → [Dialogue] → [Outro Music].
• Thinking (brainstorming-strategy-cellcog): Conversational by design. Uses send_message() for back-and-forth, not fire-and-forget.
• Cinematics (cinematic-video-cellcog): Agent Team recommended. Full production pipeline — script, character design, scene generation, animation, score, editing.
• Music (music-generation-cellcog): Agent mode. 5 seconds to 10 minutes. Royalty-free.
• Finance (stock-analysis-cellcog): Agent Team recommended for deep analysis. Agent mode for quick lookups.
• Projects (project-management-cellcog): Agent mode. Context tree markdown view is the key differentiator for agents building memory systems.
• Coding (coding-agent-cellcog): Agent mode. Requires CellCog Desktop (Co-work) for direct codebase access. Pass hc_enabled=True and hc_working_directory to create_chat(). Multimedia and document tools load on demand if needed.

Chat Modes

Note: "agent core" is deprecated — requests using it are automatically routed to Agent mode.

python
# Agent mode (fast, 1x cost)
client.create_chat(prompt="...", chat_mode="agent")

# Agent Team mode (deep, 4x cost)
client.create_chat(prompt="...", chat_mode="agent team")

Default to Agent mode for most tasks. Use Agent Team when you need deep, multi-angled research or complex multi-deliverable outputs.

File Handling

Sending Files to CellCog

You can include local file references in your prompt. The SDK automatically uploads them:

python
prompt = """
Analyze this sales data and create a summary report.
"""
# Attach files via the SDK's file handling methods
result = client.create_chat(
    prompt=prompt,
    notify_session_key="agent:main:main",
    task_label="analysis"
)

Receiving Output Files

When CellCog generates files (reports, images, videos, etc.), they are automatically downloaded to your specified output path when the task completes.

Concurrency Limits

CellCog limits parallel chats to ensure reliable performance. Each 500 credits of effective balance allows 1 parallel (operating) chat, up to 8 max.

If the limit is exceeded, create_chat() raises MaxConcurrencyError. This is NOT a payment error — either wait for a running chat to finish or inform the user that adding credits unlocks more parallel slots.

Memory System & Context Trees via SDK

CellCog's internal agents use a general-purpose memory system called Context Trees — hierarchical document stores attached to projects, agent roles, and organizations. The same system is now available to your OpenClaw agents.

The SDK includes full project, document, and context tree management. Your agents can:

• Create and manage projects programmatically
• Upload documents to project context trees
• Read from context trees to inform their work
• Build the same persistent memory structures that power CellCog's internal agents

Getting Started with Context Trees

Install the project-management-cellcog ClawHub skill:

bash
clawhub install project-management-cellcog

This gives your agents access to project creation, document management, and context tree operations — the same memory infrastructure used across the entire CellCog platform.

See Memory System & Context Trees Guide for a detailed explanation of how context trees work and best practices for structuring agent memory.

Error Handling

PaymentRequiredError

Raised when the account has insufficient credits for the requested mode.

Attributes:

• min_credits_required: Minimum credits needed
• current_balance: User's current balance
• chat_mode_display: Human-readable mode name
• top_ups: List of top-up payment links

Present the top-up links to your human so they can add credits and retry.

MaxConcurrencyError

Raised when too many chats are running in parallel.

Attributes:

• operating_count: Currently running chats
• max_parallel: Maximum allowed with current balance

This is temporary — wait for a chat to finish, or inform the user that more credits unlock more parallel slots. Do NOT present payment links for this error.

Troubleshooting

"Invalid API key"

• Verify your key at Profile → API Keys
• Ensure you're using the full key (starts with sk_)
• Check for extra spaces when copying

"Insufficient credits"

• Check your balance at Profile → Billing
• Agent and Agent Creative modes require minimum 60 credits
• Agent Team requires minimum 1,000 credits; Agent Team Max requires 2,000

"SDK version too old"

bash
# Update the cellcog skill first
clawhub update cellcog

# Then install the required SDK version
pip install cellcog

Daemon not receiving notifications

bash
# Check if daemon is running
cat ~/.cellcog/daemon.pid
ps aux | grep cellcog

# View daemon logs
tail -f ~/.cellcog/daemon.log

Resources

• SDK Repository: github.com/CellCog/cellcog_python
• PyPI Package: pypi.org/project/cellcog
• ClawHub Skills: clawhub.ai (search: cellcog)
• CellCog Website: cellcog.ai

Related Guides

• API Keys Guide — Generating and managing API keys
• Memory System & Context Trees Guide — How the memory system works
• Billing Guide — Plans, credits, and subscriptions
• Plugin Guide — CellCog plugin for Cursor, Claude Code, and more
• Getting Started — Platform overview