# Claude Code CLI Integration Feature

This document describes the Claude Code CLI integration feature added to OpenClaw, enabling users to use their Claude.ai subscription instead of API calls.

## Overview

OpenClaw now supports using Claude models via the Claude Code CLI, which allows users to leverage their Claude Pro subscription instead of paying for API calls on a per-token basis. This is especially beneficial for:

- Personal use and development
- Users with Claude Pro subscriptions
- Cost-conscious deployments
- Testing and experimentation

## What Was Added

### 1. Core Infrastructure

#### New Files Created:

- `src/agents/claude-code-models.ts` - Model definitions for Claude Code CLI
- `src/commands/auth-choice.apply.claude-code.ts` - Authentication handler for Claude Code
- `src/commands/configure.claude-code.ts` - Interactive configuration wizard
- `docs/models/claude-code-cli.md` - Comprehensive documentation
- `docs/quickstart/claude-code-subscription.md` - Quick start guide
- `docs/examples/config-claude-code-cli.yaml` - Example configuration

#### Modified Files:

- `src/agents/cli-backends.ts` - Enhanced documentation for Claude CLI backend
- `src/commands/auth-choice.apply.ts` - Added Claude Code handler
- `src/commands/auth-choice-options.ts` - Added Claude Code to auth choices
- `src/commands/auth-choice.preferred-provider.ts` - Set preferred provider

### 2. Available Models

The integration supports three Claude models via subscription:

1. **claude-cli/opus** - Claude Opus 4.6 (most capable)
2. **claude-cli/sonnet** - Claude Sonnet 4.5 (balanced, recommended)
3. **claude-cli/haiku** - Claude Haiku 4.5 (fast)

### 3. Configuration Options

Users can configure Claude Code CLI in three ways:

#### Option A: Interactive Wizard (Recommended)

```bash
openclaw configure --section model
```

Then select "Anthropic" → "Claude Code subscription (recommended)"

#### Option B: Manual Configuration

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

```yaml
agents:
  defaults:
    model:
      primary: claude-cli/sonnet
      fallbacks:
        - claude-cli/opus
        - claude-cli/haiku
```

#### Option C: Programmatic

Use the `configureClaudeCode()` function from `src/commands/configure.claude-code.ts`

### 4. Features

- **No API key required**: Uses Claude.ai subscription authentication
- **Automatic verification**: Checks if CLI is installed and authenticated
- **Fallback support**: Can mix subscription and API models
- **Model aliases**: Easy-to-remember model names
- **Full integration**: Works with all OpenClaw features (channels, gateway, etc.)
- **Cost tracking**: Zero-cost models (subscription-based)

## Usage Examples

### Basic Usage

```bash
# Install and authenticate
curl -fsSL https://claude.ai/install.sh | sh
claude login

# Configure OpenClaw
openclaw configure --section model

# Send a message
openclaw message send "Hello from my subscription!"
```

### Mixed Configuration (Subscription + API)

```yaml
agents:
  defaults:
    model:
      primary: claude-cli/sonnet # Use subscription
      fallbacks:
        - claude-cli/opus
        - anthropic/claude-opus-4-6 # Fall back to API if needed
```

### Per-Agent Configuration

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

## Implementation Details

### Authentication Flow

1. Check if `claude` CLI is installed (`claude --version`)
2. Verify authentication status (`claude whoami`)
3. If authenticated, configure models with `claude-cli` provider
4. Set default model to `claude-cli/sonnet` with fallbacks

### Model Selection

- Uses existing CLI backend infrastructure in `cli-backends.ts`
- Leverages `DEFAULT_CLAUDE_BACKEND` configuration
- Supports model aliases for easy reference
- Clear environment variables (`ANTHROPIC_API_KEY`) to avoid conflicts

### Error Handling

- Graceful failure if CLI not installed (shows installation instructions)
- Clear error messages if not authenticated (shows login command)
- Validation before applying configuration
- Fallback to API models if CLI fails

## Architecture

```
User Request
    ↓
Model Selection (claude-cli/sonnet)
    ↓
CLI Backend Resolution (cli-backends.ts)
    ↓
CLI Runner (cli-runner.ts)
    ↓
Execute: claude -p --output-format json --model sonnet <prompt>
    ↓
Parse Response
    ↓
Return to User
```

## Testing

To test the integration:

1. **Installation Check:**

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

2. **Configuration Test:**

   ```bash
   openclaw configure --section model
   # Select Claude Code subscription
   ```

3. **Functionality Test:**

   ```bash
   openclaw message send "Test message"
   ```

4. **Model List:**
   ```bash
   openclaw models list
   # Should show claude-cli models
   ```

## Benefits

### For Users

- **Cost savings**: No per-token API costs
- **Simplicity**: No API key management
- **Flexibility**: Mix subscription and API models
- **Development**: Unlimited testing within subscription limits

### For OpenClaw

- **Differentiation**: Unique feature compared to other tools
- **Accessibility**: Lowers barrier to entry
- **Flexibility**: Supports multiple authentication methods
- **Compatibility**: Works alongside existing API-based models

## Future Enhancements

Potential improvements:

1. **Auto-detection**: Automatically detect and offer Claude Code during onboarding
2. **Usage tracking**: Display subscription usage statistics
3. **Session management**: Better CLI session handling
4. **Streaming support**: Implement streaming for real-time responses
5. **Image support**: Enable vision models via CLI
6. **Rate limit handling**: Smart fallback when hitting subscription limits

## Documentation

Complete documentation available at:

- Quick Start: `docs/quickstart/claude-code-subscription.md`
- Full Guide: `docs/models/claude-code-cli.md`
- Example Config: `docs/examples/config-claude-code-cli.yaml`

## Compatibility

- **OpenClaw Version**: Compatible with current version
- **Claude CLI**: Requires Claude Code CLI v0.1.0+
- **Node.js**: Tested with Node.js 22+
- **Platforms**: macOS, Linux (Windows via WSL)

## Migration Guide

For users currently using Anthropic API:

1. Install Claude Code CLI
2. Run `openclaw configure --section model`
3. Select Claude Code subscription
4. Optional: Keep API as fallback
5. Test with a message

No breaking changes - API-based models continue to work.

## Support

- Documentation: https://docs.openclaw.ai/models/claude-code-cli
- Issues: https://github.com/openclaw/openclaw/issues
- Community: Discord server

## License

This feature follows OpenClaw's existing license (MIT/Apache 2.0).