OpenClaw integration

Claude Octopus ships with an OpenClaw compatibility layer that exposes workflows to messaging platforms (Telegram, Discord, Signal, WhatsApp) through the OpenClaw framework — without modifying the core Claude Code plugin.

What is OpenClaw

OpenClaw is an open-source AI assistant framework that connects Claude to messaging platforms, IDEs, and custom interfaces. It provides:

Multi-platform messaging — Telegram, Discord, Signal, WhatsApp
Extension API — Plugin architecture for custom tools
MCP client — Connects to Model Context Protocol servers
Web dashboard — Conversation management UI

Architecture

Claud Octopus integrates with OpenClaw through two components:

Claude Code Plugin (unchanged)
  └── .mcp.json ─── MCP Server ─── orchestrate.sh
                        ↑
OpenClaw Extension ────┘

Component	Location	Purpose
MCP Server	`mcp-server/`	Exposes 10 Octopus tools via Model Context Protocol
OpenClaw Extension	`openclaw/`	Wraps workflows for OpenClaw’s extension API
Skill Schema	`mcp-server/src/schema/skill-schema.json`	Universal skill metadata format

This architecture preserves exact behavioral parity with the Claude Code plugin — all execution flows through the same orchestrate.sh infrastructure.

MCP server architecture

The MCP server auto-starts when the plugin is enabled (via .mcp.json):

{
  "mcpServers": {
    "octo-claw": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "CLAUDE_OCTOPUS_MCP_MODE": "true"
      }
    }
  }
}

See .mcp.json in source code:~/workspace/source/.mcp.json

Server lifecycle

Claude Code loads .mcp.json on plugin activation
Spawns node mcp-server/dist/index.js via stdio transport
Server registers 10 Octopus tools with MCP protocol
Any MCP client can connect and invoke tools
Server delegates to orchestrate.sh for execution

Installing the OpenClaw extension

Option 1: From git (recommended)

cd your-openclaw-installation
npm install github:nyldn/claude-octopus#main

This installs the extension from the openclaw/ directory of the Claude Octopus repository.

Option 2: From local clone

If you’ve cloned Claude Octopus:

cd claude-octopus/openclaw
npm install
npm run build

# Link to OpenClaw
cd your-openclaw-installation  
npm link ../claude-octopus/openclaw

Option 3: From npm (when published)

cd your-openclaw-installation
npm install @octo-claw/octo-claw

Configure OpenClaw

Add to your OpenClaw configuration:

# openclaw.config.yaml
extensions:
  - name: octo-claw
    enabled: true
    config:
      enabledWorkflows:
        - discover
        - define  
        - develop
        - deliver
        - embrace
        - debate
        - review
        - security
      autonomyMode: supervised  # supervised | semi-autonomous | autonomous

Exposed tools and capabilities

The MCP server exposes 11 tools:

Workflow tools

`octopus_discover`

Run the Discover (Probe) phase — multi-provider research. Parameters:

prompt (string, required) — Topic to research

Example:

await invoke("octopus_discover", {
  prompt: "Research OAuth 2.0 security patterns"
});

`octopus_define`

Run the Define (Grasp) phase — consensus building on requirements. Parameters:

prompt (string, required) — Requirements to define

`octopus_develop`

Run the Develop (Tangle) phase — implementation with quality gates. Parameters:

prompt (string, required) — What to implement
quality_threshold (number, optional) — Minimum quality score (0-100, default: 75)

`octopus_deliver`

Run the Deliver (Ink) phase — final validation and delivery. Parameters:

prompt (string, required) — What to validate and deliver

`octopus_embrace`

Run the full Double Diamond workflow (all 4 phases). Parameters:

prompt (string, required) — Full task or project
autonomy (enum, optional) — supervised | semi-autonomous | autonomous (default: supervised)

Example:

await invoke("octopus_embrace", {
  prompt: "Build user authentication system",
  autonomy: "semi-autonomous"
});

Specialized tools

`octopus_debate`

Three-way AI debate between Claude, Gemini, and Codex. Parameters:

question (string, required) — Question to debate
rounds (number, optional) — Debate rounds (1-10, default: 1)
style (enum, optional) — quick | thorough | adversarial | collaborative
mode (enum, optional) — cross-critique | blinded (default: cross-critique)

`octopus_review`

Expert code review with multi-provider analysis. Parameters:

target (string, required) — File path or directory to review

`octopus_security`

Comprehensive security audit with OWASP compliance. Parameters:

target (string, required) — File path or directory to audit

Introspection tools

`octopus_list_skills`

List all available Claude Octopus skills with descriptions. Parameters: None

`octopus_status`

Check provider availability and configuration status. Parameters: None

IDE integration tool

`octopus_set_editor_context`

Inject IDE editor state (active file, selection, cursor) into workflows. Parameters:

filename (string, optional) — Absolute path to active file
selection (string, optional) — Selected text (max 50KB)
cursor_line (number, optional) — Current cursor line (1-based)
language_id (string, optional) — Language ID (e.g., typescript, python)
workspace_root (string, optional) — Workspace root directory

Call octopus_set_editor_context before running workflow tools to give Octopus awareness of what the user is working on.

Build and validate

Claude Octopus includes scripts for building and validating the OpenClaw integration:

Build the skill registry

./scripts/build-openclaw.sh

This regenerates the skill registry from frontmatter metadata in .claude/skills/*.md.

Validate integration

./tests/validate-openclaw.sh

Runs 13-check validation suite:

✓ MCP server builds without errors
✓ OpenClaw extension builds without errors
✓ All 11 tools are registered
✓ Skill schema is valid JSON Schema
✓ orchestrate.sh is executable
✓ No TypeScript errors in MCP server
✓ No TypeScript errors in OpenClaw extension
✓ MCP server package.json is valid
✓ OpenClaw extension package.json is valid
✓ Security: blocked env vars are enforced
✓ Security: path traversal prevention
✓ IDE context: selection size limit
✓ Hook execution order is correct

CI mode

./scripts/build-openclaw.sh --check

Exits with non-zero status if the skill registry is out of sync (useful for CI pipelines).

Security considerations

Environment variable isolation

The MCP server blocks security-critical environment variables from being overridden:

const BLOCKED_ENV_VARS = new Set([
  "OCTOPUS_SECURITY_V870",
  "OCTOPUS_GEMINI_SANDBOX",
  "OCTOPUS_CODEX_SANDBOX",
  "CLAUDE_OCTOPUS_AUTONOMY",
]);

See mcp-server/src/index.ts in source code:~/workspace/source/mcp-server/src/index.ts:54

Path traversal prevention

IDE context paths are validated to reject .. sequences:

if (value && /\.\.[\\/ ]/.test(value)) {
  return { isError: true, text: `Error: ${label} cannot contain '..'` };
}

API key sanitization

Error messages sanitize potential API key leaks:

const sanitized = msg.replace(/[A-Za-z_]+KEY=[^\s]+/g, "[REDACTED]");

Source code reference

MCP server: mcp-server/src/index.ts in source code:~/workspace/source/mcp-server/src/index.ts
OpenClaw extension: openclaw/src/index.ts in source code:~/workspace/source/openclaw/src/index.ts
MCP config: .mcp.json in source code:~/workspace/source/.mcp.json
Extension config: openclaw/package.json in source code:~/workspace/source/openclaw/package.json

MCP Server details — Deep dive into MCP architecture
Workflows — Understanding Double Diamond phases
Configuration — Environment variables and autonomy modes

Extension & Integration

Troubleshooting

What is OpenClaw

Architecture

MCP server architecture

Server lifecycle

Installing the OpenClaw extension

Option 1: From git (recommended)

Option 2: From local clone

Option 3: From npm (when published)

Configure OpenClaw

Exposed tools and capabilities

Workflow tools

`octopus_discover`

`octopus_define`

`octopus_develop`

`octopus_deliver`

`octopus_embrace`

Specialized tools

`octopus_debate`

`octopus_review`

`octopus_security`

Introspection tools

`octopus_list_skills`

`octopus_status`

IDE integration tool

`octopus_set_editor_context`

Build and validate

Build the skill registry

Validate integration

CI mode

Security considerations

Environment variable isolation

Path traversal prevention

API key sanitization

Source code reference

Build docs developers (and LLMs) love

Extension & Integration

Troubleshooting

​What is OpenClaw

​Architecture

​MCP server architecture

​Server lifecycle

​Installing the OpenClaw extension

​Option 1: From git (recommended)

​Option 2: From local clone

​Option 3: From npm (when published)

​Configure OpenClaw

​Exposed tools and capabilities

​Workflow tools

​octopus_discover

​octopus_define

​octopus_develop

​octopus_deliver

​octopus_embrace

​Specialized tools

​octopus_debate

​octopus_review

​octopus_security

​Introspection tools

​octopus_list_skills

​octopus_status

​IDE integration tool

​octopus_set_editor_context

​Build and validate

​Build the skill registry

​Validate integration

​CI mode

​Security considerations

​Environment variable isolation

​Path traversal prevention

​API key sanitization

​Source code reference

​Related documentation

Build docs developers (and LLMs) love

What is OpenClaw

Architecture

MCP server architecture

Server lifecycle

Installing the OpenClaw extension

Option 1: From git (recommended)

Option 2: From local clone

Option 3: From npm (when published)

Configure OpenClaw

Exposed tools and capabilities

Workflow tools

`octopus_discover`

`octopus_define`

`octopus_develop`

`octopus_deliver`

`octopus_embrace`

Specialized tools

`octopus_debate`

`octopus_review`

`octopus_security`

Introspection tools

`octopus_list_skills`

`octopus_status`

IDE integration tool

`octopus_set_editor_context`

Build and validate

Build the skill registry

Validate integration

CI mode

Security considerations

Environment variable isolation

Path traversal prevention

API key sanitization

Source code reference

Related documentation