Skip to main content
Version: TRC

OpenClaw and Miriel Integration

Author(s)​

  • Alapan Das
  • Faizal Khan

Submission Date​

2026-05-13

Version History​

VersionDateChangesAuthor
1.02026-05-13Initial draft - OpenClaw and Miriel integrationAlapan Das, Faizal Khan

Objective​

Evaluate and demonstrate the integration of OpenClaw AI assistant framework with Miriel data management system. The POC will validate the OpenClaw CLI usage patterns, agent and skill creation mechanisms, MCP server configuration, and Miriel's data ingestion, retrieval, and redaction capabilities.

Scope​

This POC covers the following key areas:

  1. OpenClaw CLI Usage: Demonstrating gateway management, agent communication, and diagnostic tooling
  2. OpenClaw Agent Creation and Modification: Building specialized agents (e.g., web-crawler) with isolated identities and tool access
  3. OpenClaw Skill Modification: Creating modular skill instruction sets with YAML frontmatter and markdown documentation
  4. OpenClaw MCP Server Configuration: Configuring Model Context Protocol servers within the OpenClaw framework
  5. OpenClaw Main Agent Prompt Structure: Understanding and modifying core agent behavior through system prompts
  6. Miriel Data Ingestion and Retrieval: Demonstrating data import and query capabilities within the OpenClaw ecosystem
  7. Miriel Data Redaction: Validating data privacy and redaction mechanisms
  • OpenClaw CLI: Single unified command-line interface for gateway control, agent management, skill configuration, and diagnostics
  • OpenClaw Agents: Isolated AI assistant instances with configurable identity, model, workspace, and toolset
  • OpenClaw Skills: Modular instruction sets that extend agent capabilities for specific task domains (e.g., calculations, web research, code review)
  • OpenClaw MCP Server: Model Context Protocol server integration for extended tool and resource management
  • OpenClaw Agent Identity System: YAML-frontmatter based agent configuration with plain-text versioning
  • Miriel Data Platform: Data ingestion pipeline, query/retrieval system, and privacy-preserving redaction mechanisms
  • Multi-Agent Routing: Support for multiple specialized agents operating within the same gateway
  • Channel Integration: Support for WhatsApp, Telegram, Slack, and other communication channels

Technical Approach​

OpenClaw CLI as Single Control Plane​

OpenClaw CLI serves as the primary command-line interface controlling all aspects of the AI assistant framework (gateway, agents, skills, channels, sessions, configuration) from the terminal.

Key Commands:

openclaw gateway                          # Start the gateway
openclaw agent --message "Hello"          # Send message to agent
openclaw status                           # Check gateway health
openclaw doctor --deep --yes              # Run full diagnostics
openclaw agents list --verbose            # List registered agents
openclaw agents add <name> [options]      # Register new agent
openclaw skills list                      # List available skills
openclaw skills install <name>            # Install skill from registry
openclaw gateway restart                  # Restart with new configuration

Agent Creation and Configuration​

Agents are isolated AI assistant instances with custom identity files (agent.md), model configuration, and tool access scopes. Agent identity files use YAML frontmatter with markdown documentation.

Implementation Method:

Method 1 — CLI (preferred)

Step 1: Create the agent identity folder and agent.md file

mkdir -p ~/.openclaw/agents/web-crawler
cat > ~/.openclaw/agents/web-crawler/agent.md << 'EOF'
---
name: web-crawler
description: Crawls a website URL and summarises what it is about.
---

# Web Crawler Agent

You are a web research agent. When given a URL, visit the site, read its content, and explain what it does, who it is for, and what makes it notable. Always visit the actual URL — never guess.
EOF

Step 2: Register the agent via CLI

openclaw agents add web-crawler \
   --identity ~/.openclaw/agents/web-crawler/agent.md \
   --model anthropic:claude-sonnet-4-6 \
   --tools browser

Step 3: Verify registration

openclaw agents list --verbose

Step 4: Restart gateway to apply changes

openclaw gateway restart

To modify an agent, edit the agent.md identity file and restart the gateway. Model or tool changes may also be applied by re-running the openclaw agents add command with updated flags or by editing openclaw.json directly.

Method 2 — Edit openclaw.json directly

Add or modify an agents block in ~/.openclaw/openclaw.json for batch configuration, then restart the gateway. This is useful when configuring multiple agents at once.

Example - Web Crawler Agent (summary): A dedicated agent that visits URLs and summarizes website purpose, topics, and target audience.

Skill Creation and Management​

Skills are modular instruction sets defined in SKILL.md files with YAML frontmatter (name + description) and markdown body containing detailed instructions, output formats, and rules.

Implementation Method:

Method 1 — CLI

Step 1: Create the skill folder and SKILL.md

mkdir -p ~/.openclaw/skills/calculator
cat > ~/.openclaw/skills/calculator/SKILL.md << 'EOF'
---
name: calculator
description: Performs arithmetic and mathematical calculations including addition, subtraction, multiplication, division, percentages, powers, square roots, and unit conversions. Use when the user asks to calculate, compute, or evaluate a math expression.
---

# Calculator Skill

You are a precise calculator. Parse the user's expression, compute it step by step, and present the result clearly.

## Output Format
Expression: <interpreted expression>
Steps:
   1. <step>
   2. <step>
Result: <final answer> <unit if applicable>

## Rules
- Never guess — ask for clarification if the expression is ambiguous.
- State clearly if division by zero is attempted.
- Round to a maximum of 6 decimal places.
EOF

Step 2: Restart the gateway to load the skill

openclaw gateway restart

Step 3: Verify the skill is listed

openclaw skills list

To modify a skill, edit the SKILL.md file and restart the gateway. The description field controls when the skill is triggered.

Method 2 — Install from ClawHub Registry

If the skill exists in the OpenClaw registry:

openclaw skills install calculator

Example - Calculator Skill (summary): Handles arithmetic, percentages, and unit conversions with step-by-step output and defined rules for precision and error handling.

Configuration Management​

Two configuration approaches:

  • Method 1 - CLI (Preferred): One-command registration with all parameters specified inline
  • Method 2 - Config File: Direct editing of ~/.openclaw/openclaw.json for batch configuration, followed by gateway restart

OpenClaw MCP Server Configuration​

This section covers how to add MCP servers to OpenClaw via openclaw.json, and how those MCP servers become available as tools that agents can use.

Where the config lives

OpenClaw reads its main config from openclaw.json:

  • Linux/macOS: ~/.openclaw/openclaw.json
  • Windows: %USERPROFILE%\.openclaw\openclaw.json

Adding an MCP server

{
  "mcp": {
    "servers": {
      "miriel": {
        "url": "https://api.prod2.miriel.ai/api/v2/mcp/protocol/...",
        "transport": "sse"
      },
      "my-internal-tools": {
        "url": "https://tools.mycompany.example/mcp",
        "transport": "sse"
      }
    }
  }
}
  • mcp.servers is a map keyed by a short server ID of your choice.
  • transport is "sse" for all standard server connections.
  • Restart the gateway after editing so it reloads config and reconnects.

How MCP servers become tools

On startup, OpenClaw connects to each configured MCP server, calls tools/list on each, and registers the advertised tools into its internal tool registry. Agents can invoke those tools only if the tool policy permits them.

Granting MCP tools to an agent

Add the exact registered tool name(s) to the agent's tools.allow list in openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "engineering-bot",
        "name": "engineering-bot",
        "model": { "primary": "openrouter/qwen/qwen3-235b-a22b" },
        "tools": {
          "allow": [
            "web",
            "sessions_send",
            "miriel_retrieve"
          ]
        }
      }
    ]
  }
}

To get the exact tool name: add the server, restart OpenClaw, and check the gateway startup logs for the tool registration output.

Troubleshooting

IssueCheck
OpenClaw doesn't see config changesConfirm you're editing the correct file; OPENCLAW_CONFIG_PATH takes priority. Restart the gateway.
MCP server connects but no tools appearVerify the endpoint URL. Confirm the server implements tools/list and returns at least one tool. Check gateway logs.
Agent can't call MCP toolsEnsure the exact tool name is in tools.allow. Check that tools.deny or a restrictive tools.profile isn't blocking it.

OpenClaw Main Agent Prompt Structure and Modification​

This section covers the structure and modification approach for the OpenClaw main agent prompt system. The agent's behavior is governed by four files, each controlling a distinct layer of the agent's runtime. All four must remain consistent with each other.

File Overview

FileLocationControls
SOUL.md~/.openclaw/soul/SOUL.mdPersonality, tone, and identity
AGENTS.md~/.openclaw/agents/AGENTS.mdRules, boundaries, and behavior guidelines
TOOLS.md~/.openclaw/tools/TOOLS.mdHow and when to use each tool
openclaw.json~/.openclaw/openclaw.jsonModel, temperature, tokens, and tool list

1. SOUL.md — Personality and Identity

Serves as the agent's system prompt. Defines the agent's name, role, tone, and communication style. This is the first context the model receives on every turn.

You are Aria, a senior engineering assistant for Acme Corp.
You are precise and direct. You do not guess — if uncertain,
ask for clarification. You specialize in backend systems and APIs.
Respond in plain English unless code is explicitly requested.
  • Define one clear role. Conflicting role descriptions cause inconsistent behavior.
  • Avoid vague directives such as "be helpful" — specify what that means in context.
  • Restart the gateway after editing for changes to take effect.

2. AGENTS.md — Rules and Boundaries

Defines the behavioral contract: what the agent must always do, must never do, and how it handles edge cases. Rules here take precedence over personality traits defined in SOUL.md.

1. Never delete files without explicit user confirmation.
2. Never expose API keys or credentials in any output.
3. Summarize the intended action before executing it.
4. If a task spans more than 3 steps, request approval first.
5. Decline tasks outside the engineering domain.
  • Be explicit. Vague rules produce inconsistent enforcement.
  • Include an error-handling rule — specify retry limits and escalation behavior.
  • Review this file whenever the agent's scope changes.

3. TOOLS.md — Tool Usage Guidance

Instructs the agent on when and how to use each tool in its allowlist. Every tool listed in openclaw.json under tools.allow should have a corresponding entry here.

web
  Use for: current documentation, external URLs.
  Do not use for: internal or private resources.
  Always cite the source URL in the response.

create_issue  [MCP: github-server]
  Use for: logging bugs or feature requests.
  Always set: title, labels, and assignee before submitting.
  Search for duplicates before creating a new issue.
  • Update this file every time a new MCP tool is added to the agent.
  • For high-risk tools (file writes, issue creation), add an explicit confirmation requirement.
  • Keep entries short — one use-case, one constraint, one output expectation.

4. openclaw.json — Model and Runtime Configuration

Controls the runtime parameters: which model runs, generation settings, and which tools are available to the agent. Changes to this file require a gateway restart.

FieldDescription
model.primaryThe model used for agent responses
temperatureOutput randomness. Lower (0.1–0.4) for precision; higher (0.6–0.9) for creativity
max_tokensMaximum output length per response
tools.allowWhitelist of tools the agent may call
tools.denyBlocklist — overrides allow if both are set
mcp.serversMCP server connections (url + transport)
{
  "agents": {
    "list": [{
      "id": "aria",
      "name": "aria",
      "model": { "primary": "openrouter/qwen/qwen3-235b-a22b" },
      "temperature": 0.3,
      "max_tokens": 4096,
      "tools": {
        "allow": ["web", "sessions_send", "create_issue"]
      }
    }]
  },
  "mcp": {
    "servers": {
      "github-server": {
        "url": "https://github-tools.example.com/mcp/sse",
        "transport": "sse"
      }
    }
  }
}
  • Tool names in tools.allow must match the exact names registered from the MCP server — verify in gateway startup logs.
  • Use temperature 0.3 or lower for technical agents where determinism is preferred.
  • If the config was written by a newer OpenClaw version, update the Docker image before editing — version mismatches silently drop MCP config sections.

Note: All four files must remain consistent. If a tool is removed from tools.allow in openclaw.json, its entry in TOOLS.md should also be removed to avoid agent confusion.

Miriel Integration​

Data ingestion pipeline for importing external data, query and retrieval system for accessing stored data, and privacy-preserving redaction mechanisms for sensitive information.

Miriel Data Ingestion and Retrieval​

This section covers how Miriel handles document storage and context retrieval across three access methods: the dashboard, the Python client library, and the MCP server. Vectorization on ingest and embedding on retrieval are handled automatically by Miriel in all cases.

What is Miriel

Miriel is a context engine for AI-native applications. It provides managed vector storage organized into projects, with automatic embedding on ingest and semantic search on retrieval. It accepts strings, file paths, directories, URLs, S3 buckets, and more — without requiring direct vector database management.

How It Works

The core workflow is two steps: learn() to store content, query() to retrieve it. Miriel vectorizes content automatically on learn() and performs reverse embedding on query(). Documents must be fully ingested before they can be queried.

StepActionHandled by
1Store content via dashboard, Python, or MCPUser
2Vectorization of stored contentMiriel (automatic)
3Issue a natural language queryUser / Agent
4Reverse embedding and semantic rankingMiriel (automatic)
5Return ranked context chunks + LLM resultMiriel

1. Dashboard

The Miriel dashboard provides a visual interface to create projects, upload documents, and inspect stored content without writing code. Documents uploaded here are immediately available for retrieval via the Python client and MCP — all three methods share the same underlying project store.

2. Python Client

Install via pip:

pip install miriel-python

Initialize with your API key, then use learn() to ingest and query() to retrieve:

from miriel import Miriel

m = Miriel(api_key="your_api_key")

# Ingest
m.learn("Your content here", project="my_project", wait_for_complete=True)

# Retrieve
resp = m.query("Your question here", project="my_project")
print(resp["results"]["llm_result"])

Key Parameters

MethodParameterPurpose
learn()projectAssigns the document to a named project
learn()metadata={}Attaches key-value tags for filtering
learn()priorityControls ranking: default 100, "pin" always top, "norank" excluded
learn()wait_for_completeBlocks script until ingestion finishes
query()projectScopes retrieval to a specific project
query()metadata_queryFilters results by metadata (e.g. "doc_type=runbook AND team=eng")
query()num_resultsMax results to return (default 10)
query()force_exhaustiveScans all documents; returns async query_id for polling

Additional Capabilities

  • A document can belong to multiple projects by passing project as a list.
  • get_projects() lists all known project names.
  • Exhaustive queries are async — a query_id is returned and must be polled via get_query().
  • Structured output, image input, and email delivery are supported as query() options.
  • For bulk ingest, enqueue multiple learn() jobs and block with wait_for_jobs().

Note: metadata_query supports =, >, <, >=, <= and AND / OR combinators. Keys and values are case-sensitive.

3. MCP Server

Miriel exposes an MCP server that allows OpenClaw agents and other MCP-compatible runtimes to query Miriel projects as a native tool call, with no Python code required inside the agent. Register it in openclaw.json under mcp.servers and add the registered tool name to the agent's tools.allow list.

"mcp": {
  "servers": {
    "miriel": {
      "url": "https://api.prod2.miriel.ai/api/v2/mcp/protocol/YOUR_TOKEN",
      "transport": "sse"
    }
  }
}
  • The MCP URL contains your auth token — do not commit it to version control.
  • Check gateway startup logs after restart to get the exact registered tool name.
  • Add retrieval guidance in TOOLS.md so the agent knows when to use Miriel vs. the web tool.
  • Pre-ingest domain-specific documentation into a dedicated project and scope agent queries to it.

Development Tasks & Estimates​

Testing & Validation​

Basic Tests​

  1. OpenClaw CLI Functionality:

    • Verify gateway starts and responds to status checks
    • Test agent communication via openclaw agent --message command
    • Validate diagnostic output from openclaw doctor --deep command

  2. Agent Creation and Isolation:

    • Create multiple agents with different identities and verify isolation
    • Confirm agents can independently access assigned tools
    • Test agent restart and persistence of configuration

  3. Skill Loading and Triggering:

    • Verify skills load on gateway restart
    • Confirm skill descriptions properly trigger execution
    • Test skill output formatting against defined standards

  4. MCP Server Integration:

    • Validate MCP server registration and discovery
    • Test tool availability through MCP interface
    • Verify error handling and fallback mechanisms

  5. Miriel Data Pipeline:

    • Ingest test datasets and verify integrity
    • Execute queries and validate result accuracy
    • Test data retrieval performance and response times

  6. Miriel Data Redaction:​

Validation Criteria​

  • OpenClaw CLI commands execute without errors and produce expected output
  • Agents are successfully created, registered, and remain isolated from one another
  • Skills load on demand and trigger based on configured descriptions
  • MCP server integrates seamlessly with OpenClaw framework
  • Agent system prompts can be modified and affect agent behavior as expected
  • Miriel ingests data without loss of integrity
  • Data retrieval queries return accurate results within acceptable time limits
  • Data redaction removes sensitive information while preserving query functionality
  • Full end-to-end workflow (ingest → query → redact) executes successfully
  • All commands are scriptable and automatable for CI/CD integration

Risks & Mitigations​

RiskImpactLikelihoodMitigation Strategy
OpenClaw gateway fails to initialize or restartHighLowImplement comprehensive diagnostic tools (openclaw doctor), detailed logging, and automated health checks
Agent isolation or tool access conflictsMediumMediumEstablish strict namespace conventions, implement validation checks in agent registration, use containerization for complete isolation
Skill descriptions too broad/narrowMediumMediumDevelop clear skill description guidelines, implement test suite for skill triggering, perform user testing for appropriateness
MCP server integration breaks OpenClaw stabilityHighLowThorough integration testing before deployment, implement graceful fallback mechanisms, maintain version compatibility matrix
Miriel data ingestion corrupts or loses dataHighLowImplement pre-import validation, transaction-based ingestion, automated integrity checks post-import, maintain audit logs
Miriel redaction rules over-redact dataMediumMediumImplement granular redaction control, test with diverse data types, provide redaction preview/audit capability
Performance degradation with large datasetsMediumMediumImplement query optimization, caching strategies, pagination for large result sets, perform load testing with realistic data volumes
Configuration conflicts between CLI and JSON configMediumMediumImplement unified configuration schema, provide conflict detection/resolution, clearly document precedence rules
Multi-agent routing failures or message lossHighLowImplement message queuing, delivery confirmations, dead-letter handling, comprehensive routing tests

Conclusion​

Expected Outcomes​

Upon successful completion of this POC, we will have demonstrated:

  1. OpenClaw Framework Viability: Proven that OpenClaw CLI provides a unified, scriptable control plane for managing AI agents and skills without UI or browser dependencies
  2. Agent Specialization: Shown that isolated, independently configured agents can operate within the same gateway with distinct identities, tool access, and behavior
  3. Skill Modularity: Validated that skills are maintainable, versionable, and can be dynamically loaded/unloaded without affecting other agents
  4. MCP Integration: Confirmed seamless integration of Model Context Protocol servers with OpenClaw's tool and resource management systems
  5. Miriel Readiness: Proven Miriel's data ingestion, retrieval, and redaction capabilities within the OpenClaw ecosystem
  6. Production-Ready Patterns: Established best practices for CLI usage, agent/skill creation, and configuration management

Key Advantages Demonstrated​

  • Single tool for all operations — No switching between UIs or management interfaces
  • Fully scriptable and automatable — Suitable for CI/CD pipelines, cron jobs, and shell scripts
  • Cross-platform compatibility — Works on any OS and environment (local, server, Docker)
  • Fast feedback loops — Configuration changes take effect immediately after gateway restart
  • Version control friendly — All configuration is plain text and Git-compatible
  • Auditable and reproducible — Changes are traceable across environments

Next Steps​

If the POC is successful:

  1. Production Deployment: Move OpenClaw and Miriel to production environments with hardened security and monitoring
  2. Channel Integration: Connect multiple communication channels (WhatsApp, Telegram, Slack) to deployed agents
  3. Skill Expansion: Build additional specialized skills for domain-specific tasks (customer support, data analysis, code review)
  4. Performance Optimization: Implement caching, query optimization, and load balancing for high-volume workloads

Note: Some OpenClaw and Miriel implementation details described in this document are based on observed behavior or experimental testing.