High🧠 Models

Anthropic API 401 — Missing, Expired, or Misconfigured Key

By Jason GuoPublished July 25, 2026Updated September 5, 2026

// When OpenClaw calls Claude and the gateway logs show HTTP 401 from api.anthropic.com, the model never runs — agents hang, heartbeats fail, and Discord/Telegram may show generic 'provider error' messages. Unlike 429 rate limits, 401 means authentication failed outright: no billing on the account, a revoked or typo'd key, wrong sk-ant- prefix, or the key living in the wrong config field while an stale ANTHROPIC_API_KEY env var overrides openclaw.json. This unofficial guide walks through verifying the key at console.anthropic.com, placing it correctly under providers in ~/.openclaw/openclaw.json, and resolving env-vs-config mismatches that trip even experienced self-hosters.

diagnose.sh

🔍 Is This Your Issue?

?Logs show `401` or `authentication_error` from api.anthropic.com

?Agents fail immediately with no model response — not slow, not 429

?You recently created a key but never added billing in Anthropic Console

?Key starts with sk- (OpenAI style) instead of sk-ant-

?You set a key in .env but a different (empty) key remains in openclaw.json

verify_key.sh

✅ Fix 1 — Verify Key Format & Anthropic Console

Verify prefix and live auth against Anthropic API

# Confirm key shape (never paste full key in public logs)
echo "$ANTHROPIC_API_KEY" | head -c 12
# Expected prefix: sk-ant-api

# Test key directly (replace with your key once)
curl -s 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-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Console checks: billing + active key status

# In browser: console.anthropic.com
# 1. Settings → Billing — payment method active
# 2. Settings → API Keys — key status Active
# 3. Regenerate if unsure; revoke old keys

# Note last 4 chars of new key for matching in config

openclaw.json

✅ Fix 2 — Set Provider Key in openclaw.json

Key in providers; agent provider id must match

// ~/.openclaw/openclaw.json — providers section
{
  "providers": [
    {
      "id": "anthropic",
      "type": "anthropic",
      "apiKey": "sk-ant-api03-XXXXXXXX"
    }
  ],
  "agents": {
    "defaults": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Prefer .env for secrets; restart gateway after edit

# Or reference env var instead of inline key
# openclaw.json:
#   "apiKeyEnv": "ANTHROPIC_API_KEY"

# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-ant-api03-XXXXXXXX

# Validate config
openclaw doctor
openclaw gateway restart

env_override.sh

✅ Fix 3 — Resolve ANTHROPIC_API_KEY Env Override

Locate every ANTHROPIC_API_KEY source on the host

# Find env overrides
env | grep -i ANTHROPIC
grep -r ANTHROPIC ~/.config/systemd/user/ 2>/dev/null

# Compare with config file
grep -i anthropic ~/.openclaw/openclaw.json
grep ANTHROPIC ~/.openclaw/.env 2>/dev/null

Env wins over json — delete stale Environment= lines

# Remove stale override from systemd (example)
# Edit ~/.config/systemd/user/openclaw-gateway.service
# Delete: Environment=ANTHROPIC_API_KEY=old-value

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

# Confirm gateway sees correct key
openclaw gateway status

💡 Pro Tip: One Source of Truth for Secrets

Store Anthropic keys in either ~/.openclaw/.env OR openclaw.json providers — not both with different values. Env vars override config silently. After any change, restart the gateway and run a single test message before re-enabling heartbeats.

🛡️ Prevention Checklist

• Create keys at console.anthropic.com with billing enabled — free-tier keys without credits often 401 immediately
• Use sk-ant-api03- prefix keys; legacy formats or OpenAI-style sk- keys will never work with Anthropic endpoints
• Keep ANTHROPIC_API_KEY out of systemd unit files unless you update them every rotation
• Run `openclaw doctor` after editing providers — it surfaces missing keys before agents hit production channels
• Never paste live keys into GitHub issues; rotate if accidentally exposed

← API Rate Limit 429 Node Version Too Old →

❓ FAQ

Q1. What does Anthropic 401 look like in OpenClaw logs?

Typical lines include `Anthropic API error: 401`, `authentication_error`, or `invalid x-api-key`. The gateway may retry briefly then mark the provider unhealthy. Agent runs fail before tool calls execute. Enable debug logging (log_level: debug) to see the full HTTP response body — Anthropic returns JSON with type and message fields that distinguish invalid key vs missing billing vs wrong organization.

Q2. My key works in curl but not OpenClaw — why?

OpenClaw may be reading a different key from ANTHROPIC_API_KEY in systemd, launchd, Docker compose, or ~/.openclaw/.env while you tested with curl -H manually. Run `openclaw config get providers` (or inspect openclaw.json) and compare the last four characters with your working key. Also confirm the provider id in agents.defaults.provider matches the anthropic entry you configured — a typo in provider name falls back to empty credentials.

Q3. Do I need a paid Anthropic account?

Anthropic requires billing setup for API access in most regions. Console may let you create a key, but requests 401 until payment method and usage limits are active. Check console.anthropic.com/settings/billing. Some team/org keys need the correct workspace selected when generating the key. Trial credits expire — expired credits produce 401-like errors on some endpoints.

Q4. Where exactly do I put the key in openclaw.json?

Under providers array, add or edit an object with type anthropic (or the id your agents reference). Common shape: `{ "id": "anthropic", "type": "anthropic", "apiKey": "sk-ant-api03-..." }`. Alternatively use apiKeyEnv: "ANTHROPIC_API_KEY" and set the var in ~/.openclaw/.env only. Do not put keys in channel sections or unrelated agent fields — only the provider block supplies model auth.

Q5. Can I use AWS Bedrock or Vertex instead to avoid direct Anthropic keys?

Yes if your OpenClaw version supports those provider types. Bedrock uses IAM roles instead of sk-ant- keys. Configure a separate provider entry and point agents.defaults.provider to it. This sidesteps console.anthropic.com billing but introduces cloud IAM setup. Community reports suggest direct Anthropic API is simpler for homelab Mac Mini setups.

Q6. I rotated my key — what else must I update?

Every place the old key was copied: ~/.openclaw/.env, openclaw.json providers.apiKey, Docker compose environment, systemd Environment= lines, and CI secrets if you run remote agents. Restart gateway after changes. Old keys revoked in console fail immediately with 401 — there is no grace period. Official project: github.com/openclaw/openclaw.