openclaw/CLAUDE_CODE_CLI_FEATURE.md

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)

openclaw configure --section model

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

Option B: Manual Configuration

Edit ~/.openclaw/config.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

# 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)

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

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:

   claude --version
   claude whoami
   

2. Configuration Test:

   openclaw configure --section model
   # Select Claude Code subscription
   

3. Functionality Test:

   openclaw message send "Test message"
   

4. Model List:

   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).