# 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](https://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](./CellCog_API_Keys_Guide.md) 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](#available-skills-clawhub) below. The plugin path is described in the [Plugin Guide](./CellCog_Plugin_Guide.md).

---

## How It Works

### Delivery Modes

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

| Delivery | Behavior |
|----------|----------|
| `"wait_for_completion"` (default) | Blocks until CellCog finishes, then returns the full result |
| `"notify_on_completion"` | Returns immediately; the SDK daemon delivers results to your OpenClaw session when done |
| `"send_only"` | Returns as soon as the request is accepted; you poll with `get_status()` and fetch results with `wait_for_completion()` or `get_history()` |

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.

| Mode | API value | Best for |
|------|-----------|----------|
| **Agent** | `"agent"` | Most tasks: research, media, documents, coding, co-work |
| **Agent Creative** | `"creative"` | Our most imaginative agent: design, brand, voice, web and UI work |
| **Agent Team** | `"team"` | Deep research and multi-angled reasoning |

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](./CellCog_Connectors_Guide.md).

---

## Available Skills (ClawHub)

### Full Catalog

| Skill | Install | Use case |
|-------|---------|----------|
| `cellcog` | `openclaw skills install @cellcog/cellcog` | Core: SDK setup and the complete API reference |
| `deep-research-cellcog` | `openclaw skills install @cellcog/deep-research-cellcog` | Deep research, market analysis, competitive intelligence |
| `video-generation-cellcog` | `openclaw skills install @cellcog/video-generation-cellcog` | AI video generation, lip sync, marketing videos |
| `cinematic-video-cellcog` | `openclaw skills install @cellcog/cinematic-video-cellcog` | Grand cinematics, short films, music videos, brand films |
| `image-generation-cellcog` | `openclaw skills install @cellcog/image-generation-cellcog` | Image generation, consistent characters, style transfer |
| `audio-generation-cellcog` | `openclaw skills install @cellcog/audio-generation-cellcog` | Text-to-speech, voiceovers |
| `music-generation-cellcog` | `openclaw skills install @cellcog/music-generation-cellcog` | Original music: instrumentals, vocals, scores, jingles |
| `dashboard-web-app-cellcog` | `openclaw skills install @cellcog/dashboard-web-app-cellcog` | Interactive dashboards, data visualization |
| `presentation-slides-cellcog` | `openclaw skills install @cellcog/presentation-slides-cellcog` | Presentations (PDF by default, PPTX on request) |
| `excel-spreadsheet-cellcog` | `openclaw skills install @cellcog/excel-spreadsheet-cellcog` | Spreadsheets, financial models |
| `pdf-document-generation-cellcog` | `openclaw skills install @cellcog/pdf-document-generation-cellcog` | PDFs, reports, contracts, certificates |
| `meme-generator-cellcog` | `openclaw skills install @cellcog/meme-generator-cellcog` | AI meme generation |
| `podcast-generation-cellcog` | `openclaw skills install @cellcog/podcast-generation-cellcog` | Full podcast production: structured episodes, ducked music, mastered MP3 plus chapters |
| `logo-brand-identity-cellcog` | `openclaw skills install @cellcog/logo-brand-identity-cellcog` | Brand identity, logos, color palettes, brand kits |
| `comic-manga-generator-cellcog` | `openclaw skills install @cellcog/comic-manga-generator-cellcog` | Comics, manga, webtoons, character consistency |
| `game-asset-generation-cellcog` | `openclaw skills install @cellcog/game-asset-generation-cellcog` | Game assets, sprites, tilesets, game design docs |
| `instagram-reels-tiktok-cellcog` | `openclaw skills install @cellcog/instagram-reels-tiktok-cellcog` | Instagram and TikTok: Reels, carousels, Stories |
| `tutoring-education-cellcog` | `openclaw skills install @cellcog/tutoring-education-cellcog` | Tutoring, study guides, homework help |
| `creative-writing-cellcog` | `openclaw skills install @cellcog/creative-writing-cellcog` | Fiction, screenplays, world building |
| `brainstorming-strategy-cellcog` | `openclaw skills install @cellcog/brainstorming-strategy-cellcog` | Collaborative thinking partner (conversational) |
| `youtube-video-cellcog` | `openclaw skills install @cellcog/youtube-video-cellcog` | YouTube: Shorts, tutorials, thumbnails |
| `stock-analysis-cellcog` | `openclaw skills install @cellcog/stock-analysis-cellcog` | Stock analysis, valuation models, financial research |
| `ui-prototype-wireframe-cellcog` | `openclaw skills install @cellcog/ui-prototype-wireframe-cellcog` | UI/UX wireframes, app mockups, interactive prototypes |
| `crypto-research-cellcog` | `openclaw skills install @cellcog/crypto-research-cellcog` | Token analysis, DeFi research, on-chain metrics |
| `data-analysis-cellcog` | `openclaw skills install @cellcog/data-analysis-cellcog` | Data science, statistical analysis, visualization |
| `3d-model-generation-cellcog` | `openclaw skills install @cellcog/3d-model-generation-cellcog` | 3D model generation: any input to GLB |
| `resume-cover-letter-cellcog` | `openclaw skills install @cellcog/resume-cover-letter-cellcog` | ATS-optimized resumes, cover letters |
| `legal-documents-cellcog` | `openclaw skills install @cellcog/legal-documents-cellcog` | Contracts, NDAs, terms of service, compliance |
| `nano-banana-image-cellcog` | `openclaw skills install @cellcog/nano-banana-image-cellcog` | Image generation entry point for agents that search by this name |
| `seedance-video-generation-cellcog` | `openclaw skills install @cellcog/seedance-video-generation-cellcog` | Video production entry point for agents that search by this name |
| `travel-planning-cellcog` | `openclaw skills install @cellcog/travel-planning-cellcog` | Trip itineraries, travel research |
| `news-briefing-cellcog` | `openclaw skills install @cellcog/news-briefing-cellcog` | News briefings, digests, trend monitoring |
| `project-management-cellcog` | `openclaw skills install @cellcog/project-management-cellcog` | Projects, documents, context trees, memory management |
| `coding-agent-cellcog` | `openclaw skills install @cellcog/coding-agent-cellcog` | Coding: code generation, debugging, refactoring, co-work |
| `pair-programming-cellcog` | `openclaw skills install @cellcog/pair-programming-cellcog` | Co-work: direct machine access via CellCog Desktop |
| `avatar-creation-cellcog` | `openclaw skills install @cellcog/avatar-creation-cellcog` | Avatars: images, voice cloning, personality for consistent characters |
| `diagram-flowchart-cellcog` | `openclaw skills install @cellcog/diagram-flowchart-cellcog` | Diagrams: flowcharts, architecture, mind maps |
| `gif-generator-cellcog` | `openclaw skills install @cellcog/gif-generator-cellcog` | GIF creation and animation |
| `sticker-generator-cellcog` | `openclaw skills install @cellcog/sticker-generator-cellcog` | Sticker packs and custom emoji |

Browse the same catalog on the web at [cellcog.ai/skills](https://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.

| Effective balance | Max parallel chats |
|-------------------|--------------------|
| 0 to 499 | 1 |
| 500 to 999 | 2 |
| 1,000 to 1,499 | 3 |
| 3,500 or more | 8 (cap) |

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](./CellCog_Memory_System_Guide.md) 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](https://pypi.org/project/cellcog)
- **Skills catalog:** [cellcog.ai/skills](https://cellcog.ai/skills), also on [clawhub.ai](https://clawhub.ai) (search: cellcog)
- **Docs for agents:** [cellcog.ai/llms.txt](https://cellcog.ai/llms.txt) and [cellcog.ai/for-agents](https://cellcog.ai/for-agents)
- **CellCog website:** [cellcog.ai](https://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](./CellCog_API_Keys_Guide.md): generating and managing API keys
- [Plugin Guide](./CellCog_Plugin_Guide.md): the CellCog plugin for coding agents and OpenClaw
- [Connectors Guide](./CellCog_Connectors_Guide.md): tools, keys, MCP servers, delegations
- [Memory System and Context Trees Guide](./CellCog_Memory_System_Guide.md): how the memory system works
- [Billing Guide](./CellCog_Billing_Guide.md): plans, credits, and subscriptions
- [Getting Started](./CellCog_Getting_Started.md): platform overview

---

Markdown alternate of https://cellcog.ai/support/openclaw-guide (CellCog support guide, category: Integrations). All guides for agents: https://cellcog.ai/support/llms.txt. Site index: https://cellcog.ai/llms.txt. Try CellCog free, no credit card needed: https://cellcog.ai/signup