# OpenClaw Integration

AVELIN API works seamlessly with [OpenClaw](https://openclaw.ai) — an open-source agentic coding platform that orchestrates multiple AI models for complex software engineering workflows.

> **Why AVELIN + OpenClaw?** OpenClaw's multi-agent architecture pairs perfectly with AVELIN's diverse model catalog. Use specialized models for different tasks — coding, reasoning, planning — all through one governed API.

---

## Quick Setup

### Step 1: Get your AVELIN API key

Sign up at [avelin.ai](https://avelin.ai) and generate an API key. It will look like `sk-ave...xxxx`.

### Step 2: Configure OpenClaw

OpenClaw supports both **Anthropic** and **OpenAI** API formats. We recommend the **Anthropic surface** for best compatibility.

#### Option A: Environment Variables

Set these in your shell profile or OpenClaw's configuration:

```bash
export OPENCLAW_API_KEY="sk-a...
export OPENCLAW_BASE_URL="https://api.avelin.ai"
```

#### Option B: Configuration File

Edit `~/.openclaw/config.json`:

```json
{
  "providers": {
    "avelin": {
      "type": "anthropic",
      "base_url": "https://api.avelin.ai",
      "api_key": "sk-a...
      "models": {
        "coding": "avelin-coding-pro",
        "reasoning": "avelin-ultra",
        "fast": "avelin-fast"
      }
    }
  },
  "default_provider": "avelin"
}
```

### Step 3: Start OpenClaw

```bash
openclaw
```

OpenClaw will use AVELIN as its backend provider.

---

## Multi-Model Workflows

OpenClaw's strength is orchestrating multiple AI agents for complex tasks. AVELIN's diverse model catalog is perfect for this:

### Recommended Model Assignments

```json
{
  "agents": {
    "architect": {
      "model": "avelin-coding-ultra",
      "purpose": "System design, architecture decisions, security reviews"
    },
    "coder": {
      "model": "avelin-coding-pro",
      "purpose": "Code generation, refactoring, debugging"
    },
    "planner": {
      "model": "avelin-ultra",
      "purpose": "Task decomposition, planning, research"
    },
    "reviewer": {
      "model": "avelin-coding-fast",
      "purpose": "Code review, test generation, documentation"
    },
    "assistant": {
      "model": "avelin-fast",
      "purpose": "Quick questions, simple tasks, high-volume operations"
    }
  }
}
```

### Example Workflow

```bash
$ openclaw run "Implement user authentication with JWT tokens"

OpenClaw orchestrates:
  → Planner (avelin-ultra): Decomposes task into subtasks
  → Architect (avelin-coding-ultra): Designs auth system architecture
  → Coder (avelin-coding-pro): Implements auth middleware and routes
  → Reviewer (avelin-coding-fast): Reviews code, generates tests
  → Assistant (avelin-fast): Updates README with usage examples

Result: Complete auth system with tests and documentation
```

---

## Why AVELIN for OpenClaw?

### 1. **Model Diversity**

OpenClaw thrives with specialized models for different tasks. AVELIN provides:

- **Coding models** (1M context): `avelin-coding-fast`, `avelin-coding-pro`, `avelin-coding-ultra`
- **Reasoning models** (256K context): `avelin-ultra`, `avelin-pro`
- **Fast models** (256K context): `avelin-fast`
- **Agentic models** (256K context): `avelin-agentic-pro`, `avelin-agentic-ultra`, `avelin-agentic-fast`

### 2. **Cost Optimization**

Multi-agent workflows can be expensive. AVELIN optimizes costs:

- **Route simple tasks to fast models**: Use `avelin-fast` for high-volume operations
- **Prompt caching**: ~80% cost reduction on repeated system prompts
- **Pay-per-token**: No subscription lock-in

### 3. **Reliability**

- **Automatic failover**: If one provider is slow, AVELIN switches to another
- **Retry logic**: Transient errors handled automatically
- **High throughput**: Support for parallel agent execution

### 4. **1M Context Windows**

OpenClaw agents often work with large codebases. AVELIN's coding models support 1M tokens — no chunking required.

---

## Configuration Examples

### Simple Single-Model Setup

For basic OpenClaw usage with one model:

```json
{
  "providers": {
    "avelin": {
      "type": "anthropic",
      "base_url": "https://api.avelin.ai",
      "api_key": "sk-a...
      "models": {
        "default": "avelin-coding-pro"
      }
    }
  }
}
```

### Advanced Multi-Model Setup

For complex workflows with specialized agents:

```json
{
  "providers": {
    "avelin": {
      "type": "anthropic",
      "base_url": "https://api.avelin.ai",
      "api_key": "sk-a...
    }
  },
  "workflows": {
    "feature_development": {
      "agents": [
        {
          "name": "planner",
          "model": "avelin-ultra",
          "max_tokens": 65536,
          "thinking": "enabled"
        },
        {
          "name": "architect",
          "model": "avelin-coding-ultra",
          "max_tokens": 65536,
          "thinking": "enabled"
        },
        {
          "name": "coder",
          "model": "avelin-coding-pro",
          "max_tokens": 65536,
          "thinking": "enabled"
        }
      ]
    },
    "quick_fix": {
      "agents": [
        {
          "name": "fixer",
          "model": "avelin-fast",
          "max_tokens": 8192,
          "thinking": "disabled"
        }
      ]
    }
  }
}
```

---

## Tool Calling Best Practices

OpenClaw relies heavily on tool calling for file operations, command execution, and API interactions. AVELIN's models excel at this:

### Reliable Tool Formats

Both Anthropic and OpenAI tool formats work:

```json
{
  "tools": [
    {
      "name": "read_file",
      "description": "Read file contents",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        },
        "required": ["path"]
      }
    }
  ]
}
```

### Streaming with Tools

Enable streaming for real-time feedback:

```json
{
  "stream": true,
  "tools": [...]
}
```

---

## Troubleshooting

| Issue | Solution |
|---|---|
| **"Provider not found"** | Check that `OPENCLAW_BASE_URL` points to `https://api.avelin.ai` |
| **"Model not available"** | Use a valid AVELIN model name from the [Model Catalog](../../models/README.md) |
| **Slow multi-agent execution** | Ensure you're using high-throughput models like `avelin-coding-pro` |
| **Tool calls failing** | Use `avelin-coding-pro` or `avelin-coding-fast` — these have first-class function calling |
| **Context errors** | Set `context_length: 1000000` for coding models |
| **Rate limiting** | AVELIN has generous limits. If hit, OpenClaw's retry logic handles it automatically |

---

## Cost Optimization Tips

### 1. Route by Task Complexity

```json
{
  "routing": {
    "simple_queries": "avelin-fast",
    "code_generation": "avelin-coding-fast",
    "complex_refactors": "avelin-coding-pro",
    "architecture_design": "avelin-coding-ultra"
  }
}
```

### 2. Enable Prompt Caching

AVELIN automatically caches repeated system prompts (~80% cost reduction). No configuration needed.

### 3. Use Thinking Wisely

Enable thinking only for complex tasks:

```json
{
  "agents": {
    "planner": {
      "model": "avelin-ultra",
      "thinking": "enabled"
    },
    "assistant": {
      "model": "avelin-fast",
      "thinking": "disabled"
    }
  }
}
```

---

## Example Use Cases

### Feature Development Workflow

```bash
openclaw run "Add user authentication with JWT, including:
- Auth middleware
- Login/register endpoints
- Password hashing
- Comprehensive tests
- API documentation"
```

OpenClaw orchestrates multiple agents to deliver the complete feature.

### Codebase Refactoring

```bash
openclaw run "Refactor the database layer to use repository pattern.
Update all services, add tests, and create migration guide."
```

Large context windows allow agents to understand the entire codebase.

### Bug Investigation

```bash
openclaw run "Investigate the memory leak in the caching service.
Analyze logs, profile the code, and implement a fix."
```

Multiple agents collaborate on diagnosis and solution.

---

## Related

- [API Quickstart](../../api/quickstart.md) — First API call in 5 minutes
- [Hermes Agent Guide](../hermes.md) — Another agentic coding tool
- [Claude Code Guide](claude-code.md) — Anthropic's CLI tool
- [Model Catalog](../../models/README.md) — Full model comparison
- [OpenClaw Docs](https://docs.openclaw.ai) — Official OpenClaw documentation