Claude Code Specifics

Unable to connect to Anthropic services on first launch

Symptom: After installing Claude Code, the first claude run prints this error and exits:

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Please check your internet connection and network settings.

Fix: Open the config file ~/.claude.json for your system:

Windows

Press Win + R, type the following, and press Enter (opens in Notepad):

notepad %userprofile%\.claude.json

macOS

# Open with the default text editor
open -e ~/.claude.json

Linux

# Open with a terminal editor
nano ~/.claude.json

Add to the top-level JSON object:

"hasCompletedOnboarding": true

Full example:

{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "...",
  "projects": { },
  "hasCompletedOnboarding": true
}

Note: the } ending the projects field must be followed by a comma ,, or the JSON is invalid. Validate with:

Windows

Get-Content $env:USERPROFILE\.claude.json -Raw | ConvertFrom-Json

macOS / Linux

cat ~/.claude.json | python3 -m json.tool

No error means the format is valid. Run claude again to enter the interactive UI.

401 Invalid API Key / invalid token

The terminal returns 401 invalid x-api-key. This is usually caused by one of the following — check each scenario in turn.

Case 1: Base URL unset or wrong

Cause: ANTHROPIC_BASE_URL is unset or wrong, so the request hits the official endpoint.

Fix: make sure ~/.claude/settings.json has the correct Base URL and API Key:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-request-address",
    "ANTHROPIC_API_KEY": "sk-***"
  }
}

Note: the Claude Code Base URL does not need a /v1 suffix.

Case 2: IDE or MCP overrode the config

Symptom: the API Key is correct but you keep getting 401. Common after installing IDE plugins like Cursor or Continue.

Cause: the IDE plugin or MCP server overwrote the apiKey / baseURL fields in settings.json.

Fix (choose one):

• Recommended: reconfigure with CC Switch to overwrite the modified config in one click
• Manual: check and fix the overwritten fields in ~/.claude/settings.json
• Environment variables: set API Key and Base URL via system env vars (higher priority than config files, harder to override)

Prevention: re-verify Claude Code connectivity after installing a new IDE plugin or MCP.

Case 3: Old env vars left behind after switching services

Symptom: you previously used another proxy service; after switching, the new config is correct but you still get 401.

Cause: the old service left system env vars behind (ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_API_TOKEN), which take priority over config files.

Windows fix: Press Win + R → type sysdm.cpl → Advanced → Environment Variables, and delete ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_API_TOKEN from both "User variables" and "System variables". Reopen the terminal. If it still fails, delete these config files and reconfigure with CC Switch:

C:\Users\<name>\.claude\claude.json
C:\Users\<name>\.claude\claude.json.backup

Mac / Linux fix: Edit ~/.zshrc or ~/.bashrc, remove old lines starting with export ANTHROPIC_, run source ~/.zshrc, then restart the terminal.

OAuth login conflict invalidates the API Key

Symptom: you previously completed the official OAuth login via claude in the terminal; after switching to a proxy API, the config is ignored and requests go straight to api.anthropic.com. Especially common on servers (CentOS / Ubuntu).

Cause: ~/.claude.json holds an OAuth token (primaryApiKey / oauthToken), which takes priority over the API Key in settings.json.

Fix:

# Step 1: log out of OAuth
claude auth logout

# Step 2: write the proxy API config
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-API-key",
    "ANTHROPIC_BASE_URL": "https://your-request-address"
  }
}
EOF

# Step 3: verify it was written
cat ~/.claude/settings.json

# Step 4: relaunch
claude

Prevention: on servers, write settings.json before the first claude run to avoid triggering the OAuth flow.

401 Invalid API Key format — Key contains invisible characters

Symptom: the Key looks correct but still returns 401 or Invalid format.

Cause: copying the Key from a PDF / web page / screenshot introduced zero-width spaces, non-breaking spaces, \r, etc., or OCR misread similar characters (0/O, 1/l/I).

Detect:

echo "$ANTHROPIC_API_KEY" | cat -A
# Normal: only $ at end of line
# Abnormal: ^M$ or other extra characters

Fix: get the Key again via the console's "Copy" button — don't type it manually or route it through a PDF/screenshot. Assign without quotes:

export ANTHROPIC_API_KEY=sk-ant-api03-your-key

403 Missing API Key / config conflict

Cause: the config file was modified accidentally, or multiple configs conflict.

Fix: reconfigure with CC Switch to overwrite the modified files.

Asked to authenticate / login prompt on startup

Make sure ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY are set, and restart the terminal (close the whole window and reopen — not a new tab).

Environment variable priority

From highest to lowest: system env vars > ~/.claude.json (OAuth token) > ~/.claude/settings.json (written by CC Switch).

When troubleshooting, if editing settings.json has no effect, check for higher-priority env vars or OAuth leftovers first.

Switch Claude Code back to 200K context

To turn off the 1M context and go back to 200K, add the following to the env block of ~/.claude/settings.json (Windows: C:\Users\<name>\.claude\settings.json). The config is the same on Windows / macOS / Linux:

{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

Restart the terminal after saving.

WebFetch (web access) not working

Symptom: WebFetch errors out, but the target site opens fine in a browser and the proxy is in global mode.

Cause: before fetching the target page, Claude Code first sends a preflight to https://claude.ai/api/web/domain_info. If domestic networks / corporate firewalls block claude.ai, the preflight fails and WebFetch errors out entirely.

Fix: add to ~/.claude/settings.json (Windows: C:\Users\<name>\.claude\settings.json):

"skipWebFetchPreflight": true

If you already have other config, merge it:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-request-address",
    "ANTHROPIC_API_KEY": "sk-***"
  },
  "skipWebFetchPreflight": true
}

Restart Claude Code to skip the preflight and request the target page directly.

Permission denied — file read/write rejected

Three independent causes; diagnose each:

• Cause A — OS-level permissions: run ls -la /path/to/file to check the permission bits, fix with chmod 644 (files) or chmod 755 (directories)
• Cause B — Claude Code permission setting: you previously chose "Always deny" for this action; press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux), search Claude: Manage Permissions, and change the rule to "Ask" or "Allow"
• Cause C — .claudeignore rule mismatch: run cat .claudeignore to check whether a glob rule wrongly matches the target file; delete or tighten the offending rule

Prevention: use precise paths in .claudeignore instead of broad wildcards, periodically review "Always deny" rules, and keep project permissions at 644 (files) / 755 (directories).

skipAutoPermissionPrompt breaks Plan mode

Symptom: adding "skipAutoPermissionPrompt": true to settings.json makes Plan mode fail to run; removing it restores it.

Fix: open ~/.claude/settings.json, delete the entire skipAutoPermissionPrompt line, save, and restart the terminal.

Prevention: only add config options clearly documented for a purpose, and run a basic sanity check after changing permission-related config.

How does Claude Code's permission mechanism work?

Claude Code confirms actions like file operations and shell command execution. The first trigger pops a prompt with "Allow once", "Always allow", "Always deny". If you mistakenly pick "Always deny", that action type is blocked thereafter and must be changed manually in the Permission management UI.

How to enable the 1-hour context cache?

For dedicated groups that support long caching, add to the env of ~/.claude/settings.json:

"ENABLE_PROMPT_CACHING_1H": "1"

Tradeoff: rebuilding a 1-hour cache costs more, so for high-frequency use the default short cache is usually better. Enable it only for long-chain tasks.

Why do I see a mini / Haiku model being called when I selected a larger model?

Symptom: you selected a flagship model (e.g. gpt-5.6-sol / Claude Opus), but the request logs also show calls to a small model. Both Claude Code and Codex do this:

• Claude Code → uses the Haiku small model for background chores
• Codex → uses a small model like gpt-5-mini for background chores

This is usually normal — not a downgrade or a swap. Both tools split the "main conversation" from "background helper tasks" and use different models to save cost and time:

• Main model: only used to answer your actual questions
• Small model (mini / Haiku): automatically handles lightweight chores not worth a pricey model, such as:
  • Generating conversation titles / subtitles
  • Auto-summaries, session digests, /compact history compression
  • Intent detection, tool-routing decisions
  • An agent's internal planning steps, autocomplete

How to confirm it's normal:

1. Check the content of that mini request — if the prompt is "generate a title" or "summarize this", it's a helper task and perfectly fine
2. Check the model hit by your actual question — as long as the main answer uses the large model you selected, you're good

Duplicate cache creation causes double-charging in one session

Symptom: within the same request, the cache is created twice and billed twice. If time-to-first-byte exceeds 30 seconds, suspect this first.

Cause: after a backup-load account switch, the secondary forward carries certain headers, causing misrouting and duplicate cache creation.

Fix:

1. Confirm the symptom: review the request chain for duplicate cache creation in one request and a clearly >30s time-to-first-byte
2. Remove the ccs proxy to avoid the intermediate layer that triggers backup-load account switching
3. If you must keep the forwarding chain, inspect each header passed through on the secondary forward and remove the one causing misrouting
4. Issue a fresh standalone request to verify

Prevention: keep the request chain single and stable; on secondary forwards, only keep necessary headers.

How to check current token usage?

Type /cost in the Claude Code interactive UI to see the current session's token usage.