# Claws - OpenClaw AI Platform - Complete Documentation

> Production-ready OpenClaw AI platform for the PlatPhorm News Network
> Base URL: https://localhost:3000
> Version: 1.0.0
> Last Updated: 2026-04-10T15:59:33.668Z

## Table of Contents

1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Core API](#core-api)
4. [MCP Protocol](#mcp-protocol)
5. [Integrations](#integrations)
6. [Tools Reference](#tools-reference)
7. [Error Handling](#error-handling)
8. [Rate Limiting](#rate-limiting)
9. [Webhook System](#webhook-system)
10. [OpenClaw Workspace](#openclaw-workspace)

## Overview

Claws is a production-grade OpenClaw AI platform that brings MCP (Model Context Protocol) to the PlatPhorm News Network. It provides seamless integration with 84 federated sites and 150+ tools across AI, analytics, and content management.

### Key Features

- **OpenClaw MCP Server**: Full JSON-RPC 2.0 protocol implementation
- **Multi-Tenant Architecture**: Isolated workspaces per tenant
- **Tool Ecosystem**: 150+ verified MCP tools
- **Network Integration**: 84 federated sites with unified API
- **Performance Analytics**: SEO, AEO (AI-Era Optimization), GEO insights
- **Observability**: Trace, sessions, memory management
- **Webhooks**: Event-driven architecture with retry logic
- **API First**: Complete REST API with OpenAPI documentation

## Authentication

### API Key Authentication

```
Authorization: Bearer sk_live_xxxxx
```

Obtain API keys from your tenant dashboard. Keys include:
- Usage quota (default: 1000 RPM)
- Permission scopes (chat, tools, integrations)
- Expiration settings
- Rate limiting tiers

### Session Token

After login, sessions are maintained with secure HTTP-only cookies.

## Core API

### Health Check
```
GET /api/v1/health
Response: { status: "ok", version: "1.0.0", checks: {...} }
```

### MCP Server (JSON-RPC 2.0)
```
POST /api/v1/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "unique-id",
  "method": "tools/list",
  "params": {}
}

Response:
{
  "jsonrpc": "2.0",
  "id": "unique-id",
  "result": {
    "tools": [
      {
        "name": "tool_name",
        "description": "Tool description",
        "inputSchema": {
          "type": "object",
          "properties": {...}
        }
      }
    ]
  }
}
```

### Chat API
```
POST /api/chat
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "model": "xai/grok-3",
  "tools": true,
  "stream": true
}
```

## MCP Protocol

Claws implements the complete MCP specification:

### Tool Calling
```
{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "search_articles",
    "arguments": {
      "query": "AI innovation",
      "limit": 10
    }
  }
}
```

### Resource Access
```
{
  "jsonrpc": "2.0",
  "id": "resource-1",
  "method": "resources/read",
  "params": {
    "uri": "file:///workspace/AGENTS.md"
  }
}
```

### Prompts
```
{
  "jsonrpc": "2.0",
  "id": "prompt-1",
  "method": "prompts/get",
  "params": {
    "name": "analysis_framework",
    "arguments": {"topic": "content"}
  }
}
```

## Integrations

### PlatPhorm News API
- **Base URL**: https://platphormnews.com/api
- **MCP Endpoint**: https://mcp.platphormnews.com/api/mcp
- **Available Tools**: 71
- **Rate Limit**: 3000 RPM
- **Features**: Articles, feeds, author profiles, analytics

Example:
```
GET /api/v1/integrations/platphormnews?action=list_articles&limit=20
```

### Insights API
- **Base URL**: https://insights.platphormnews.com
- **Capabilities**: SEO scoring, Performance audit, Accessibility check, AI-Era Optimization
- **Input**: Domain or URL
- **Output**: Comprehensive metrics and recommendations

Example:
```
POST /api/v1/integrations/insights
{
  "url": "https://example.com",
  "checks": ["seo", "performance", "accessibility", "ai-readiness"]
}
```

### Trace Observatory
- **Purpose**: Monitor and debug AI agent tool calls
- **Features**: Execution tracing, performance profiling, error tracking
- **Integration**: Automatic for all tool executions

### GridNet AI
- **Type**: Distributed AI computation network
- **Capabilities**: Model inference, embeddings, agent orchestration
- **Rate Limit**: 1000 RPM

### Network Graph
- **Endpoint**: /api/v1/integrations/graph
- **Features**: Node traversal, relationship discovery, capability mapping
- **Use Cases**: Network analysis, integration discovery

## Tools Reference

### Most Used Tools

Tools data loading...

### Tool Execution Flow

1. Tool listed by MCP server
2. Client/agent selects tool
3. Arguments validated against schema
4. Tool executed with timeout (30s default)
5. Output returned or error handled
6. Execution logged to analytics
7. Trace created for debugging

## Error Handling

### HTTP Status Codes

- 200: Success
- 201: Created
- 202: Accepted (async processing)
- 400: Bad Request - Invalid parameters
- 401: Unauthorized - Auth required
- 403: Forbidden - Permission denied
- 404: Not Found - Resource doesn't exist
- 429: Too Many Requests - Rate limited
- 500: Internal Server Error - Server issue
- 503: Service Unavailable - Maintenance

### Error Response Format

```json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Query parameter 'limit' must be between 1 and 100",
    "details": {
      "parameter": "limit",
      "received": 500,
      "max": 100
    }
  }
}
```

## Rate Limiting

### Default Limits

- Anonymous: 60 requests/minute
- Authenticated: 300 requests/minute
- Pro: 1000 requests/minute
- Enterprise: Custom

### Headers

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1234567890
X-RateLimit-Retry-After: 5
```

## Webhook System

### Event Types

- chat:message_created
- chat:message_completed
- tool:execution_started
- tool:execution_completed
- tool:execution_failed
- integration:synced
- memory:written

### Webhook Signature

All webhooks are signed with HMAC-SHA256:

```
X-Webhook-Signature: sha256=<hex_digest>
X-Webhook-Delivery-Id: <uuid>
X-Webhook-Attempt: 1
```

### Retry Policy

- Max attempts: 5
- Backoff: Exponential (60s, 120s, 240s, 480s, 960s)
- Delivery status: pending → delivered/failed/retrying

## OpenClaw Workspace

### Directory Structure

```
workspace/
├── AGENTS.md          # Agent personas and behaviors
├── SOUL.md            # Core identity document
├── TOOLS.md           # Tool descriptions
├── USER.md            # User preferences
├── IDENTITY.md        # System identity
├── BOOT.md            # Session initialization
├── BOOTSTRAP.md       # System bootstrap
├── MEMORY.md          # Memory config
└── HEARTBEAT.md       # Health monitoring
```

### Workspace Access

```
GET /api/v1/openclaw/workspace
POST /api/v1/openclaw/workspace (to update)
```

## Support & Resources

- **API Docs**: https://localhost:3000/api/docs
- **Sitemap**: https://localhost:3000/sitemap.xml
- **Status**: https://localhost:3000/api/v1/health
- **Issues**: Report via Dashboard
- **Email**: api@platphormnews.com