openclaw/docs/models/claude-code-cli.md

# Using Claude Code CLI with OpenClaw

OpenClaw supports using Claude models via the Claude Code CLI subscription instead of direct API calls. This allows you to use your Claude.ai subscription without needing API keys.

## Benefits

- **No API keys needed**: Uses your Claude.ai subscription
- **Subscription-based**: No per-request costs if you have a Claude Pro subscription
- **Same models**: Access to Claude Opus 4.6, Sonnet 4.5, and Haiku 4.5
- **Seamless integration**: Works with all OpenClaw features

## Prerequisites

1. **Claude Code CLI installed**: Follow the installation guide at https://docs.anthropic.com/en/docs/claude-code
2. **Claude.ai account**: You need a Claude Pro or equivalent subscription
3. **Authenticated CLI**: Run `claude login` to authenticate

## Quick Start

### 1. Install Claude Code CLI

```bash
# macOS/Linux
curl -fsSL https://claude.ai/install.sh | sh

# Or use npm
npm install -g @anthropic-ai/claude-code
```

### 2. Authenticate

```bash
claude login
```

### 3. Configure OpenClaw

Add the following to your `~/.openclaw/config.yaml`:

```yaml
agents:
  defaults:
    # Add claude-cli models to allowlist (required)
    models:
      claude-cli/opus: {}
      claude-cli/sonnet: {}
      claude-cli/haiku: {}

    # Set claude-cli as your primary model provider
    model:
      primary: claude-cli/sonnet
      fallbacks:
        - claude-cli/opus
        - claude-cli/haiku
```

### 4. Start using it

```bash
# Send a message using Claude Code subscription
openclaw message send "Hello from Claude Code CLI!"

# Or use with any channel
# Messages will now use your subscription instead of API calls
```

## Available Models

When using `claude-cli` as the provider, you can use these model aliases:

- `claude-cli/opus` - Claude Opus 4.6 (most capable)
- `claude-cli/sonnet` - Claude Sonnet 4.5 (balanced)
- `claude-cli/haiku` - Claude Haiku 4.5 (fast)

## Configuration Examples

### Example 1: Use Claude Code for all models

```yaml
agents:
  defaults:
    # Register models (required)
    models:
      claude-cli/opus: {}
      claude-cli/sonnet: {}
      claude-cli/haiku: {}

    # Set primary and fallbacks
    model:
      primary: claude-cli/sonnet
      fallbacks:
        - claude-cli/opus
```

### Example 2: Mix Claude Code with API models

```yaml
agents:
  defaults:
    # Register both CLI and API models
    models:
      claude-cli/opus: {}
      claude-cli/sonnet: {}
      anthropic/claude-opus-4-6: {}

    # Use subscription for most requests
    model:
      primary: claude-cli/sonnet
      fallbacks:
        - anthropic/claude-opus-4-6 # Falls back to API if needed
```

### Example 3: Per-agent configuration

```yaml
agents:
  defaults:
    # Register all models globally
    models:
      claude-cli/opus: {}
      claude-cli/sonnet: {}
      anthropic/claude-sonnet-4-5: {}

  agents:
    work:
      # Use Claude Code subscription for work agent
      model:
        primary: claude-cli/opus
    personal:
      # Use API for personal agent
      model:
        primary: anthropic/claude-sonnet-4-5
```

### Example 4: Custom model aliases

```yaml
agents:
  defaults:
    models:
      claude-cli/opus:
        alias: subscription-opus
      claude-cli/sonnet:
        alias: subscription-sonnet
    model:
      primary: subscription-sonnet
```

## Advanced Configuration

### Custom CLI Backend Settings

You can customize the Claude CLI backend in your config:

```yaml
agents:
  defaults:
    cliBackends:
      claude-cli:
        # Use a custom claude binary path
        command: /custom/path/to/claude
        # Override model aliases
        modelAliases:
          my-opus: opus
          my-sonnet: sonnet
```

### Timeout Configuration

Adjust timeouts for long-running requests:

```yaml
agents:
  defaults:
    timeoutSeconds: 300 # 5 minutes
```

## Usage Tips

### 1. Check CLI Status

Verify your Claude CLI is working:

```bash
claude --version
claude whoami
```

### 2. Model Selection

Use the `openclaw models` command to see available models:

```bash
openclaw models list
```

### 3. Monitor Usage

The Claude Code CLI uses your subscription. Check your usage at https://claude.ai/settings

### 4. Fallback Strategy

Consider keeping API-based models as fallbacks in case the CLI is unavailable:

```yaml
agents:
  defaults:
    model:
      primary: claude-cli/sonnet
      fallbacks:
        - claude-cli/opus
        - anthropic/claude-sonnet-4-5 # API fallback
```

## Troubleshooting

### "claude: command not found"

The Claude CLI is not installed or not in your PATH. Install it:

```bash
curl -fsSL https://claude.ai/install.sh | sh
```

### "Not authenticated"

Run `claude login` to authenticate:

```bash
claude login
```

### CLI session issues

If you encounter session-related errors, try:

```bash
# Clear local CLI state
rm -rf ~/.claude/sessions

# Restart your OpenClaw gateway
openclaw gateway restart
```

### Serialization conflicts

By default, Claude CLI runs are serialized (one at a time). If you need concurrent requests, you can disable serialization (note: this may cause issues):

```yaml
agents:
  defaults:
    cliBackends:
      claude-cli:
        serialize: false
```

## Limitations

- **No streaming to external channels**: CLI responses are sent as complete messages, not streamed
- **Rate limits**: Subject to Claude.ai subscription rate limits
- **Session management**: CLI maintains its own session state
- **Image support**: Image support depends on your Claude Code CLI version

## Comparison: CLI vs API

| Feature         | Claude Code CLI                 | Anthropic API           |
| --------------- | ------------------------------- | ----------------------- |
| **Cost**        | Subscription-based              | Pay-per-token           |
| **Setup**       | `claude login`                  | API key required        |
| **Models**      | Opus 4.6, Sonnet 4.5, Haiku 4.5 | All Claude models       |
| **Streaming**   | Limited                         | Full support            |
| **Rate limits** | Subscription limits             | API tier limits         |
| **Best for**    | Individual use, development     | Production, high volume |

## Related Documentation

- [Model Configuration](/models/configuration)
- [Agent Configuration](/agents/configuration)
- [CLI Backends](/reference/cli-backends)
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)