Claude Code Onboarding Bypass: How to Skip the Login Requirement with ~/.claude.json

Published on ClawList.io | Category: Development | Reading Time: ~6 min

---

If you've ever tried to set up Claude Code on a friend's machine — or deploy it in a headless environment — you've probably run into Anthropic's increasingly strict onboarding gate. Even if you've correctly configured your API keys via environment variables, Claude Code will stubbornly demand you go through its login flow before it lets you do anything useful. Frustrating? Absolutely. Unsolvable? Not quite.

In this post, we'll walk through the exact configuration workaround that lets you bypass Claude Code's mandatory login screen, explain why this happens, and cover what to expect after you apply the fix — including a mixed API/auth warning you'll want to understand before dismissing it.

---

Why Claude Code Forces Login Even With API Keys Set

This is the core mystery that trips up most developers: you've already exported your ANTHROPIC_API_KEY, you've double-checked it's valid, and yet Claude Code still refuses to budge past its onboarding screen. What gives?

The reason is architectural by design. Anthropic has decoupled authentication (proving who you are to Anthropic's services) from authorization (your API key granting you access to the model). Claude Code, unlike a raw API call, is an agentic tool that operates with elevated trust — it can read files, execute shell commands, and interact with your local environment. Anthropic has therefore added an explicit onboarding checkpoint to ensure every user has acknowledged terms, usage policies, and the scope of what Claude Code can do.

The onboarding gate checks for a completion flag in a local config file, not just the presence of an API key. This means:

• Setting ANTHROPIC_API_KEY ✅ — necessary, but not sufficient
• Setting ANTHROPIC_BASE_URL ✅ — also not sufficient on its own
• Completing the onboarding flow ✅ — what Claude Code actually checks for

The config file in question lives at:

~/.claude.json

If this file doesn't exist or doesn't contain the right flag, Claude Code will always redirect you to the login/onboarding screen on startup.

---

The Fix: Modifying ~/.claude.json

The workaround is straightforward once you know where to look. You need to manually set the hasCompletedOnboarding flag to true inside ~/.claude.json.

Step 1: Check If the File Exists

cat ~/.claude.json

If the file doesn't exist, you'll get a "No such file or directory" error. That's fine — we'll create it.

Step 2: Create or Edit the Config File

If the file doesn't exist, create it with the minimum required configuration:

cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true
}
EOF

If the file already exists (perhaps partially populated from a previous attempt), open it with your editor of choice and add or update the hasCompletedOnboarding key:

# Using nano
nano ~/.claude.json

# Using vim
vim ~/.claude.json

# Using VS Code
code ~/.claude.json

Your final ~/.claude.json should look something like this:

{
  "hasCompletedOnboarding": true
}

Or, if the file already has other keys populated (for example, from a partial login attempt):

{
  "hasCompletedOnboarding": true,
  "primaryApiKey": "sk-ant-...",
  "authType": "apiKey"
}

⚠️ Important: Don't hardcode your API key directly in this file if you're setting up on a shared or remote machine. Use environment variables instead and keep the JSON minimal.

Step 3: Set Your API Key via Environment Variable

Make sure your API key is exported in your shell profile (~/.bashrc, ~/.zshrc, etc.):

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Then reload your shell:

source ~/.zshrc   # or ~/.bashrc depending on your shell

Step 4: Launch Claude Code

claude

You should now bypass the onboarding screen entirely and land directly in the interactive session.

---

Understanding the API/Auth Mixed Warning

Here's where things get slightly nuanced. Even after successfully bypassing the onboarding screen, you'll likely see a warning about mixed API and authorization usage. It looks something like this:

⚠️  Warning: Mixed authentication detected. You are using an API key
    alongside session-based authorization. This may cause unexpected
    behavior in some agentic workflows.

What does this mean?

Claude Code is designed to support two primary authentication modes:

| Mode | Description | |---|---| | API Key Mode | You provide ANTHROPIC_API_KEY; requests go directly to Anthropic's API | | Session/OAuth Mode | You log in via browser; Claude Code manages token refresh automatically |

When you manually set hasCompletedOnboarding: true without completing the OAuth flow, Claude Code detects a mismatch: the config file thinks you've done a full login, but there's no active session token — only an API key. This triggers the mixed-auth warning.

Should you worry about it?

For most developer use cases — especially local development, CI/CD pipelines, and API-key-based deployments — the answer is no. The warning is informational. Your API key will still work, requests will still route correctly, and Claude Code will function normally. The edge cases where this could cause issues involve:

• Features that rely on Anthropic's session-based entitlements (e.g., certain Claude.ai integrations)
• Workflows that depend on automatic token refresh (not applicable with static API keys)
• Enterprise SSO configurations

If you're a solo developer or running Claude Code in an automated pipeline with a static API key, you can safely acknowledge the warning and move on.

---

Practical Use Cases for This Workaround

This configuration trick is particularly valuable in the following scenarios:

• Setting up Claude Code on a colleague's machine without requiring them to go through Anthropic's full browser-based onboarding
• Headless server environments where browser-based OAuth flows are impractical (Docker containers, remote VMs, CI runners)
• Automated deployment scripts that provision Claude Code as part of a developer toolchain
• Air-gapped or restricted networks where external login redirects are blocked
• Testing and QA environments where you need a clean, reproducible Claude Code setup

A quick provisioning script for these scenarios might look like:

#!/bin/bash
# provision-claude-code.sh

echo "Setting up Claude Code environment..."

# Write minimal config to skip onboarding
mkdir -p ~/.claude
cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true
}
EOF

# Export API key (in production, pull this from a secrets manager)
export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:?Error: ANTHROPIC_API_KEY not set}"

echo "Claude Code configured. Run 'claude' to start."

---

Conclusion

Anthropic's onboarding gate in Claude Code is a deliberate design choice — not a bug — aimed at ensuring users understand the elevated permissions that agentic AI tools operate with. That's a reasonable goal. But it creates friction for developers who already know what they're doing and just want to get to work.

The fix is simple: add "hasCompletedOnboarding": true to ~/.claude.json, pair it with a valid ANTHROPIC_API_KEY environment variable, and you're good to go. Accept the mixed-auth warning for what it is — an informational heads-up, not a blocker — and carry on building.

As Claude Code continues to evolve (and Anthropic continues to tighten its onboarding flows), it's worth keeping an eye on the official documentation and community channels for updated configuration options. For now, this workaround remains effective and widely used across the developer community.

---

Found this helpful? Share it with your team or bookmark it for your next Claude Code deployment. Have a different workaround that's working for you? Drop it in the comments or reach out on X. We're always looking for the latest developer tips to feature on ClawList.io.

Reference: @op7418 on X/Twitter

---

Tags: claude-code anthropic ai-tools developer-tools configuration onboarding api-keys automation openclaw