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

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

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

2. Authenticate

claude login

3. Configure OpenClaw

Add the following to your ~/.openclaw/config.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

# 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

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

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

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

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:

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:

agents:
  defaults:
    timeoutSeconds: 300 # 5 minutes

Usage Tips

1. Check CLI Status

Verify your Claude CLI is working:

claude --version
claude whoami

2. Model Selection

Use the openclaw models command to see available models:

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:

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:

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

"Not authenticated"

Run claude login to authenticate:

claude login

CLI session issues

If you encounter session-related errors, try:

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

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
• Agent Configuration
• CLI Backends
• Claude Code Documentation