Setting Up OpenClaw on a Headless VPS with Claude

⚠️ IMPORTANT: Subscription Authentication Policy Change (March 2026)

As of January 2026, Anthropic has actively enforced their Terms of Service regarding automated access to Claude subscriptions. Using Claude Pro/Max subscriptions through third-party tools like OpenClaw via the setup-token method violates Anthropic’s ToS and may result in account suspension or termination.

Per Anthropic’s Consumer Terms of Service (Section 3.7):

“Except when you are accessing our Services via an Anthropic API Key or where we otherwise explicitly permit it, [you may not] access the Services through automated or non-human means, whether through a bot, script, or otherwise.”

Recommended approach: Use an API key for OpenClaw deployments. This guide now covers the API method as the primary recommended approach, with subscription information retained for historical reference only.

Use subscription authentication at your own risk.

Running OpenClaw on a headless VPS gives you 24/7 availability, better uptime, and the ability to access your AI assistant from anywhere. This guide walks through deploying OpenClaw on a remote server with Claude, focusing on the API key method (recommended) while also documenting the subscription approach for reference.

Authentication Methods: API vs Subscription

Anthropic offers two ways to access Claude:

For OpenClaw deployments, use an API key. The subscription method documented below may result in account termination per Anthropic’s active enforcement policy (January 2026 onwards). For a full analysis of what prompted this enforcement action and who is affected, see Anthropic’s third-party subscription auth ban explained.

Prerequisites

• A VPS or cloud server (AWS, DigitalOcean, Linode, Hetzner, etc.)
• Debian/Ubuntu-based system (this guide uses Debian 12)
• Node.js 22+ installed (Node.js 24 recommended) [Updated March 2026]
• An Anthropic API key (get one at console.anthropic.com)

Step 1: Install OpenClaw on Your VPS

SSH into your server and install OpenClaw:

# Install Node.js 24 if not present
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install OpenClaw globally
npm install -g openclaw

# Verify installation
openclaw --version

Step 2: Initial Configuration

Run the onboarding wizard to set up the basic configuration:

openclaw onboard

This creates the initial config at ~/.openclaw/openclaw.json. For a headless server, you’ll want minimal configuration to start:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  }
}

Step 3: Configure Claude API Authentication (Recommended)

The API key method is the recommended and ToS-compliant way to use Claude with OpenClaw.

Get Your API Key

1. Go to console.anthropic.com
2. Navigate to API Keys section
3. Create a new API key (starts with sk-ant-api03-)

Configure OpenClaw with API Key

On your VPS:

# Set your API key via environment variable (recommended for security)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"

# Or configure directly in OpenClaw
openclaw models auth set-key --provider anthropic --key "sk-ant-api03-xxxxxxxxxxxx"

Set Claude as Your Default Model

# Set the default model (Opus for complex tasks)
openclaw models set anthropic/claude-opus-4-6

# Or Sonnet (faster, more cost-effective)
openclaw models set anthropic/claude-sonnet-4-6

# Verify
openclaw models list

Your config should now look like:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-6"
      }
    }
  }
}

API Pricing Reference

Cost estimate: A typical coding session with ~50K input tokens and ~10K output tokens on Sonnet costs ~$0.30. Heavy daily usage (~500K tokens) runs ~$3/day.

Cost Optimization: Batch API and Prompt Caching

Two Anthropic features can significantly reduce costs for high-volume VPS deployments:

• Batch API: Processes requests asynchronously with a 50% discount on both input and output tokens. Suitable for non-real-time workloads such as overnight summarization jobs or background document processing. Not appropriate for interactive chat sessions where low latency matters.
• Prompt caching: Cache hits cost 10% of the standard input price. OpenClaw’s session transcript design — storing conversation context as JSONL — pairs well with this feature for long-running sessions where the system prompt and early context remain constant.

To enable caching in your config:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        promptCaching: true
      }
    }
  }
}

For mixed workloads, a reasonable approach is to route interactive channels (WhatsApp, Telegram) to the standard API and schedule batch tasks (nightly reports, digest generation) through the Batch API endpoint to capture the 50% discount.

Alternative: Subscription Authentication (Not Recommended)

⚠️ Warning: The method below uses Claude Pro/Max subscription authentication with OpenClaw. As of January 2026, Anthropic actively enforces their ToS prohibiting automated access via subscriptions. Use at your own risk—accounts have been terminated for this.

For production use, switch to the API method above.

# Make sure you're logged into Claude
claude auth login

# Generate a setup token for your VPS
claude setup-token

Your setup token (expires in 30 minutes):

sk-ant-setup-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy this token and paste it into your OpenClaw configuration.

openclaw models auth paste-token --provider anthropic

openclaw models status

# Create the auth profiles file
mkdir -p ~/.openclaw/agents/main/agent
cat > ~/.openclaw/agents/main/agent/auth-profiles.json << 'EOF'
{
  "anthropic:your-email@example.com": {
    "provider": "anthropic",
    "mode": "token",
    "token": "sk-ant-setup-token-xxxxxxxx...",
    "email": "your-email@example.com"
  }
}
EOF

Step 4: Set Up a Channel (WhatsApp Example)

To actually use OpenClaw, you need to configure a messaging channel. Here’s a WhatsApp setup:

# Install the WhatsApp channel dependencies
openclaw plugins enable whatsapp

# Configure WhatsApp
openclaw config set channels.whatsapp.enabled true
openclaw config set channels.whatsapp.dmPolicy "allowlist"
openclaw config set channels.whatsapp.allowFrom '["+1234567890"]'  # Your phone number

For the first WhatsApp connection, you’ll need to scan a QR code. On a headless server, OpenClaw will display the QR code in the terminal—screenshot it and scan with WhatsApp on your phone.

Step 5: Running OpenClaw as a Service

To keep OpenClaw running after you disconnect SSH, use systemd:

# Create systemd service file
sudo tee /etc/systemd/system/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
Environment="HOME=/home/your-username"
ExecStart=/usr/local/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

# Check status
sudo systemctl status openclaw

Replace your-username with your actual Linux username.

Step 6: Connecting Remotely

To interact with your headless OpenClaw instance, you have several options:

Option A: Control UI via SSH Tunnel

# On your local machine, tunnel the Control UI
ssh -L 18789:localhost:18789 your-vps-ip

# Then open http://localhost:18789 in your browser

Option B: Use the CLI Remotely

# Set the gateway URL
openclaw config set gateway.url "http://your-vps-ip:18789"

# Or use environment variable
export OPENCLAW_GATEWAY_URL="http://your-vps-ip:18789"

Option C: Telegram Bot (Recommended for Mobile)

Configure Telegram for easy mobile access:

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "your-bot-token"
openclaw config set channels.telegram.dmPolicy "allowlist"
openclaw config set channels.telegram.allowFrom '["tg:your-user-id"]'

Troubleshooting

”Model is not allowed” Error

If you see:

Model "anthropic/claude-opus-4-6" is not allowed

Add the model to your allowlist:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        models: {
          "anthropic/claude-opus-4-6": { alias: "Opus" },
          "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }
        }
      }
    }
  }
}

Invalid API Key

If authentication fails:

# Verify your API key is set
echo $ANTHROPIC_API_KEY

# Test directly with curl
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 10, "messages": [{"role": "user", "content": "hi"}]}'

Rate Limits (API)

API rate limits are based on your tier. If you hit limits:

• Check your usage tier at console.anthropic.com
• Consider upgrading to Priority Tier for higher limits
• Add fallback models in your config:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "anthropic/claude-sonnet-4-6",
          "kimi-coding/k2p5"
        ]
      }
    }
  }
}

Kimi Fallback Model Tool-Calling Failures

If you use kimi-coding/k2p5 as a fallback model and see tool-call errors or the agent silently stops executing steps, this may be the confirmed tool-calling regression affecting certain OpenClaw releases. According to the GitHub issue tracker, versions between 2026.3.8 and 2026.3.12 exhibited intermittent tool-calling failures with the kimi-coding provider. Version 2026.3.13 resolves this. If you are on an affected version, either upgrade or temporarily replace the fallback with anthropic/claude-haiku-4-5 while updating.

npm update -g openclaw  # upgrades to latest (2026.3.13+)

Auth Profile Not Found

If OpenClaw can’t find your auth:

# Verify API key is set
openclaw models status --verbose

# Re-set the API key
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"

Security Considerations

1. Protect your API key — store it securely, use environment variables, never commit to git
2. Use allowlists — never leave channels in “open” mode on a public server
3. Firewall rules — restrict port 18789 to your IP only:

   sudo ufw allow from your-home-ip to any port 18789

4. Regular updates — keep OpenClaw updated:

   npm update -g openclaw

5. Monitor usage — check your API costs regularly at console.anthropic.com

What’s New in OpenClaw 2026.3.12–2026.3.13

If you are upgrading from an earlier 2026.x release, the two most recent versions ship several changes relevant to VPS deployments:

2026.3.12 (March 13, 2026)

• Dashboard v2: A modular Control UI with gateway overview, live chat, config editor, agent view, and session inspector. Accessible at http://localhost:18789 via SSH tunnel (see Step 6 above). Mobile-friendly layout with bottom tabs — useful for checking VPS status from a phone.
• Ephemeral device tokens: Improves the headless authentication flow. When rotating API keys, ephemeral tokens let you re-authenticate without restarting the systemd service.
• Plugin architecture for local models: Native plugin support for Ollama, SGLang, and vLLM backends — useful if you want to run a local fallback model on the same VPS to reduce API costs during off-hours.

2026.3.13 (March 14, 2026)

• Resolves the kimi-coding/k2p5 tool-calling regression introduced in 2026.3.8.
• Adds GPT-5.4 as an available provider (openai/gpt-5.4 and openai/gpt-5.4-pro).
• Chrome DevTools MCP attach mode, allowing the agent to debug live browser sessions — not relevant for most headless VPS setups, but useful if you’re also running a browser-control agent.

Comparison: API Key vs Subscription

Recommendation: Use API keys for any automated or server-based deployment. Subscriptions are designed for interactive human use through claude.ai or the official Claude Code CLI.

Conclusion

Setting up OpenClaw on a headless VPS with Claude via API key gives you a powerful, always-on AI assistant with full ToS compliance. While API costs scale with usage, they remain predictable for most workloads—a typical heavy user spends $50-150/month, far less than the risk of losing a Claude Max account to ToS enforcement.

Key takeaways:

• ✅ Use API keys for OpenClaw, bots, and any automated deployments
• ❌ Avoid subscription authentication for automation—it violates Anthropic’s ToS
• 💡 Monitor costs via the Anthropic console to stay within budget

Next steps:

• Configure additional channels (Telegram, Discord, Slack)
• Set up model fallbacks for cost optimization
• Explore multi-agent setups for different workspaces (see the technical deep dive on OpenClaw architecture for session isolation and multi-agent routing patterns)
• Add skills from ClawHub

Last updated: March 23, 2026. OpenClaw version 2026.3.13.