CellCog + OpenClaw Integration Guide

Use CellCog as the execution layer for your OpenClaw agents: install the Python SDK and the ClawHub skills, delegate research, media, documents, and coding work, and get results back in your agent's session.

What is the CellCog + OpenClaw Integration?

CellCog gives OpenClaw agents multimodal capabilities through three pieces:

• CellCog Python SDK: a pip-installable package for programmatic access
• ClawHub Skills: pre-built skills that teach your agent when and how to use each capability (research, video, images, coding, and more)
• Notify-on-completion delivery: 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 and make sure your account has credits
2. Open your profile menu, then API Keys, and generate a key
3. Copy and save your key securely; it is shown only once

See the API Keys Guide for details.

Step 2: Install the CellCog Python SDK

bash
pip install -U cellcog

Step 3: Configure Your API Key

Set it as an environment variable:

bash
export CELLCOG_API_KEY="sk_..."

The SDK reads the environment variable automatically:

python
from cellcog import CellCogClient

client = CellCogClient(agent_provider="openclaw")

Step 4: Install CellCog on OpenClaw

There are two install paths. Tell your agent "install CellCog" and it picks the one that fits your setup:

• ClawHub skill install (lightweight): the core skill plus any capability skills you want
• OpenClaw plugin install: skills, routing, and setup bundled together

Install the core skill (required for the skill path):

bash
openclaw skills install @cellcog/cellcog

Add capability skills as needed:

bash
openclaw skills install @cellcog/deep-research-cellcog
openclaw skills install @cellcog/video-generation-cellcog
openclaw skills install @cellcog/image-generation-cellcog
openclaw skills install @cellcog/audio-generation-cellcog
openclaw skills install @cellcog/dashboard-web-app-cellcog
openclaw skills install @cellcog/presentation-slides-cellcog
openclaw skills install @cellcog/pdf-document-generation-cellcog
openclaw skills install @cellcog/coding-agent-cellcog

The full list is in the Skills Catalog below. The plugin path is described in the Plugin Guide.

How It Works

Delivery Modes

create_chat() and send_message() accept a delivery argument:

Use notify-on-completion when the agent should keep working. Use send-only when you orchestrate several chats at once, so no single call blocks on a whole run.

Notify-on-Completion Pattern

python
result = client.create_chat(
    prompt="Research quantum computing advances in 2026, with citations",
    notify_session_key="agent:main:main",
    task_label="quantum-research",
    chat_mode="agent",
    delivery="notify_on_completion",
)

# Your agent continues with other work.
# The SDK daemon tracks the chat and delivers the results to the session above.

What Happens Behind the Scenes

1. Your agent calls create_chat(), which returns as soon as the chat is accepted
2. The SDK's background daemon tracks the chat
3. For long tasks, your agent receives interim progress updates about every 4 minutes
4. When CellCog finishes, your agent gets a completion notification with the results and the 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",
    delivery="notify_on_completion",
)

Wait for Completion (Sequential Workflows)

When you need results before the next step:

python
completion = client.wait_for_completion(chat_id="abc123", timeout=1800)
# Returns: {"chat_id", "is_operating", "status", "message"}

• status="completed": the chat finished and message holds the full response, file paths, and credits used
• Timed out: status="operating" and the chat is still running server-side; message carries the latest progress, and you can call wait_for_completion() again
• Default timeout is 1800 seconds; use 3600 for complex jobs

Manual Inspection

python
history = client.get_history(chat_id="abc123")   # full history, downloads any missed files
status = client.get_status(chat_id="abc123")     # status, is_operating, latest_update

get_status() returns status (processing, ready, or error), is_operating, and latest_update, the agent's most recent progress line.

Interim Progress Updates

For long tasks in notify mode, the daemon collects CellCog's progress messages and delivers a digest to your agent about every 4 minutes, so the agent always knows what is happening. A timed-out wait_for_completion() call includes the same recent progress in its response.

Chat Modes and Tiers

Every CellCog chat runs at a mode and a tier. chat_mode picks the agent, chat_tier picks the depth.

Any positive credit balance starts a chat in every mode and tier; there is no per-mode minimum.

Tiers are "flash", "core", and "max", on every mode. Older mode strings from earlier SDK versions are still accepted and normalized to these modes.

python
# Quick, economical Agent run (the SDK sends "flash" when you omit chat_tier)
client.create_chat(prompt="...", chat_mode="agent")

# Deepest Agent run
client.create_chat(prompt="...", chat_mode="agent", chat_tier="max")

# Agent Team for deep research
client.create_chat(prompt="...", chat_mode="team", chat_tier="core")

Tier guidance for Agent mode: omit chat_tier for simple asset generation and light tasks. Pass chat_tier="max" for coding, long documents, financial models, and anything where quality matters more than speed. The SDK applies "max" automatically when enable_cowork=True. If a Flash result disappoints, re-run the same prompt on Max.

Full create_chat() Options

python
result = client.create_chat(
    prompt="...",
    chat_mode="agent",                     # "agent" | "creative" | "team"
    chat_tier="max",                       # "flash" | "core" | "max"; omit for the SDK default
    delivery="send_only",                  # "wait_for_completion" | "notify_on_completion" | "send_only"
    notify_session_key="agent:main:main",  # required for notify_on_completion
    task_label="research",
    project_id="...",                      # attach the chat to a CellCog project
    agent_role_id="...",                   # run as a specific agent role in that project
    enable_cowork=True,                    # work on the user's machine via CellCog Desktop
    cowork_working_directory="/path/to/repo",
    enable_browse=True,                    # drive the user's own Chrome (Desktop + extension required)
    browser_profile_id="Default",          # from client.get_browser_status()
    enable_tools=True,                     # the user's connected tools (Gmail, Notion, ...)
    tools_selection=["gmail", "notion"],   # toolkit slugs; omit for all connected tools
)

Browse and Tools from the SDK

python
# Browse: discover Chrome profiles, then enable with one
status = client.get_browser_status()
result = client.create_chat(
    prompt="...",
    enable_browse=True,
    browser_profile_id=status["active_profile"]["profileDir"],
)

# Tools: discover connected toolkits, then enable a selection (omit tools_selection for all)
toolkits = client.list_toolkits(connected_only=True)
result = client.create_chat(
    prompt="...",
    enable_tools=True,
    tools_selection=["gmail"],
)

tools_selection requires enable_tools=True. client.list_toolkit_tools("gmail") shows what a toolkit unlocks. Every tool call still runs behind the user's approval threshold; see the Connectors Guide.

Available Skills (ClawHub)

Full Catalog

Browse the same catalog on the web at cellcog.ai/skills.

Special Guidance by Capability

• Research (deep-research-cellcog): citations are not automatic; ask for them in the prompt when you need them.
• Presentations (presentation-slides-cellcog): PDF is the default and recommended output. Request PPTX only when the deck must stay editable.
• Memes (meme-generator-cellcog): Agent mode. Comedy is hard for AI, so the agent curates after generating.
• Podcasts (podcast-generation-cellcog): Agent mode. Default output is a structured episode (cold open, intro, segments with stingers, recap, outro) with music ducked under speech, mastered to broadcast loudness, delivered as MP3 plus chapters.
• Thinking (brainstorming-strategy-cellcog): conversational by design; use send_message() for the back-and-forth.
• Cinematics (cinematic-video-cellcog): Agent Team recommended for the full pipeline: script, character design, scenes, animation, score, editing.
• Finance (stock-analysis-cellcog): Agent Team for deep analysis, Agent for quick lookups.
• Projects (project-management-cellcog): Agent mode. The context tree markdown view is what agents building memory systems need.
• Coding (coding-agent-cellcog): Agent mode. Direct codebase access needs CellCog Desktop (Cowork): pass enable_cowork=True and cowork_working_directory to create_chat(). The SDK selects the Max tier for co-work automatically.

File Handling

Sending Files to CellCog

Reference local files in the prompt with SHOW_FILE tags. The SDK uploads them before the chat starts and fails early if a file is missing:

python
result = client.create_chat(
    prompt="Analyze this data and write a summary: <SHOW_FILE>/path/to/sales.csv</SHOW_FILE>",
    task_label="analysis",
    chat_mode="agent",
)

The same tags work in send_message().

Receiving Output Files

Files CellCog generates are downloaded to ~/.cellcog/chats/{chat_id}/ when the task completes. To place a file at a specific path, ask for it with a GENERATE_FILE tag:

python
result = client.create_chat(
    prompt="Create a report: <GENERATE_FILE>/output/report.pdf</GENERATE_FILE>",
    task_label="report",
    chat_mode="agent",
)

If a delivery was missed, get_history(chat_id) re-processes the chat and downloads any missed files.

Concurrency Limits

CellCog limits parallel chats to keep performance reliable. Each 500 credits of effective balance adds one parallel (operating) chat slot, with a minimum of 1 and a maximum of 8.

If the limit is exceeded, create_chat() raises MaxConcurrencyError. This is not a payment error: wait for a running chat to finish, or tell the user that adding credits unlocks more slots.

Memory System and Context Trees via SDK

CellCog's own agents use a memory system called Context Trees: hierarchical document stores attached to projects, agent roles, and organizations. The same system is available to your OpenClaw agents.

The SDK includes project, document, and context tree management, so your agents can:

• Create and manage projects programmatically
• Upload documents to project context trees
• Read from context trees to inform their work
• Attach chats to a project (project_id) and run them as a specific agent role (agent_role_id)

Getting Started with Context Trees

Install the project-management-cellcog skill:

bash
openclaw skills install @cellcog/project-management-cellcog

See the Memory System and Context Trees Guide for how context trees work and how to structure agent memory.

Error Handling

PaymentRequiredError

Raised when the account has too few credits for the requested mode and tier.

Attributes:

• min_credits_required: kept for compatibility; a chat starts with any positive balance, so this is 1
• current_balance: the account's current effective balance
• chat_mode_display: human-readable mode name
• top_ups: top-up payment links
• billing_url: the CellCog billing page

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

MaxConcurrencyError

Raised when too many chats are running in parallel.

Attributes:

• operating_count: chats currently running
• max_parallel: the maximum allowed with the current balance
• effective_balance: the current effective balance
• credits_per_slot: credits required per additional slot

This is temporary. Wait for a chat to finish, or tell the user that more credits unlock more slots. Do not present payment links for this error.

Troubleshooting

"Invalid API key"

• Check the key in your profile menu under API Keys
• Use the full key (it starts with sk_) with no extra spaces
• A revoked key stops working immediately; generate a new one

"Insufficient credits"

• Check your balance on the Billing page
• Any positive credit balance starts a chat in every mode and tier; a balance of zero or below returns this error

SDK errors after an update

bash
pip install -U cellcog

Use the same Python interpreter your OpenClaw installation uses.

Daemon not delivering notifications

The SDK keeps its state (tracked chats, downloads, daemon files) under ~/.cellcog by default. Check the daemon files there, and confirm the process is running with ps aux | grep cellcog.

Resources

• PyPI package: pypi.org/project/cellcog
• Skills catalog: cellcog.ai/skills, also on clawhub.ai (search: cellcog)
• Docs for agents: cellcog.ai/llms.txt and cellcog.ai/for-agents
• CellCog website: cellcog.ai

Frequently Asked Questions

Which delivery mode should I use?

Default (wait_for_completion) for simple sequential scripts. notify_on_completion when your OpenClaw agent should keep working and get results pushed to its session. send_only when you launch several chats at once.

Does the OpenClaw agent need the plugin or the skills?

Either. The ClawHub skill path is lightweight; the plugin path bundles skills, routing, and setup. Both use the same SDK and API key.

Can my agent use the human's connected tools and browser?

Yes. Pass enable_tools=True (optionally tools_selection) for connected tools, and enable_browse=True with a browser_profile_id for the user's Chrome. Approvals still apply.

Where do generated files end up?

Under ~/.cellcog/chats/{chat_id}/, or at the path you named in a GENERATE_FILE tag.

Related Guides

• API Keys Guide: generating and managing API keys
• Plugin Guide: the CellCog plugin for coding agents and OpenClaw
• Connectors Guide: tools, keys, MCP servers, delegations
• Memory System and Context Trees Guide: how the memory system works
• Billing Guide: plans, credits, and subscriptions
• Getting Started: platform overview