Claude Code

This guide explains how to configure Claude Code to work with the PwC AI-CoE Coding Agents Gateway.

Installation

First, install Claude Code using the Native installer (recommended over npm or Homebrew installations).

📖 Official installation guide: https://docs.anthropic.com/en/docs/claude-code/overview

VPN Requirement

You must be disconnected from PwC Global Protect VPN during installation, as the VPN blocks the installation script.

Configuration

Once installed, configure Claude Code by editing the settings file located at:

~/.claude/settings.json

Creating the Settings File

Common Issue

Many colleagues have reported that settings.json is not automatically created until you send your first message to Claude Code, which requires logging in with an Anthropic account. To bypass this, manually create the file at the path above.

Environment Variables

Add the following to your settings.json:

{
  "model": "sonnet",
  "env": {
    "ANTHROPIC_BASE_URL": "https://idi-coding-agents.pwc.it",
    "ANTHROPIC_AUTH_TOKEN": "apikey=<your-api-key>&tenantid=<your-tenant-id>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://idi-coding-agents.pwc.it",
    "OTEL_EXPORTER_OTLP_HEADERS": "authorization=Bearer apikey=<your-api-key>&tenantid=<your-tenant-id>",
    "OTEL_RESOURCE_ATTRIBUTES": "user.email=name.surname@pwc.com",
    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Replace <your-api-key> and <your-tenant-id> with the values obtained as described in Get Access.

Telemetry Settings (Required)

Why Telemetry?

Telemetry helps PwC track ROI, analyze usage patterns, and demonstrate the value of AI coding assistants across the organization. This data is essential for continued investment in these tools.

Privacy: We do not collect conversation content, code, or file names. Only aggregate usage metrics (session counts, token usage, costs) relevant for ROI calculation are collected.

Access blocked from Monday 9 March 2026

Starting Monday 9 March 2026, the gateway enforces two policies in PROD:

1. Personal API keys blocked — requests using personal @pwc.com API keys are rejected. You must use an API key requested through the Get Access page.
2. Telemetry required — if OTEL_RESOURCE_ATTRIBUTES is not set with a valid user.email, you will receive a 403 Telemetry not configured error.

Configure both before Monday to avoid losing access.

Variable	Description
CLAUDE_CODE_ENABLE_TELEMETRY	Set to 1 to enable telemetry
OTEL_METRICS_EXPORTER	Set to otlp to use OpenTelemetry Protocol
OTEL_LOGS_EXPORTER	Set to otlp to use OpenTelemetry Protocol
OTEL_EXPORTER_OTLP_PROTOCOL	Set to http/protobuf for HTTP transport
OTEL_EXPORTER_OTLP_ENDPOINT	The PwC OTEL collector endpoint
OTEL_EXPORTER_OTLP_HEADERS	Required — Authentication header (see below)
OTEL_RESOURCE_ATTRIBUTES	Required — Must include your PwC email (see below)

OTEL_EXPORTER_OTLP_HEADERS must use the format:

authorization=Bearer apikey=<your-api-key>&tenantid=<your-tenant-id>

Use the same API key and tenant ID from your ANTHROPIC_AUTH_TOKEN.

OTEL_RESOURCE_ATTRIBUTES must include your personal PwC email:

user.email=name.surname@pwc.com

Replace name.surname@pwc.com with your actual PwC email. The email must match the name.surname@pwc.com format — generic or shared mailboxes are not accepted.

Team and department are auto-populated from the PwC cost center registry based on your email. You do not need to set team.id or department manually.

Already configured telemetry but still getting a 403?

After setting OTEL_RESOURCE_ATTRIBUTES in settings.json, restart Claude Code. The gateway allows a 2-minute grace period for the OTEL exporter to send its first heartbeat. If you still get errors after 2 minutes:

1. Confirm OTEL_RESOURCE_ATTRIBUTES is inside the env block in ~/.claude/settings.json
2. Verify the email matches the name.surname@pwc.com format
3. Check you are using an API key from the Get Access page, not a personal one

Troubleshooting First Launch

If Claude Code prompts for login despite a correct settings.json, the env block is not loaded during the very first startup. Export the two required variables directly in your terminal session to bypass the login screen:

export ANTHROPIC_BASE_URL="https://idi-coding-agents.pwc.it"
export ANTHROPIC_AUTH_TOKEN="apikey=<your-api-key>&tenantid=<your-tenant-id>"

Then launch Claude Code:

claude

Claude Code should start without a login prompt. Once it does, you do not need to add these exports to ~/.zshrc — the env block in settings.json takes over for all subsequent launches.

If Claude Code still prompts for login, run these diagnostic checks:

1. Verify settings.json is valid JSON:

python3 -m json.tool ~/.claude/settings.json

2. Confirm the file exists and contains the expected variables:

grep -E "ANTHROPIC_BASE_URL|ANTHROPIC_AUTH_TOKEN" ~/.claude/settings.json

3. Check that Claude Code can reach the gateway (requires VPN):

curl -s -o /dev/null -w "%{http_code}" https://idi-coding-agents.pwc.it/health

Expected output: 200. Any other result means VPN is not active or the endpoint is unreachable.

Core Settings

Setting	Description
model	Default model to use. We recommend sonnet for the best balance of performance and cost. Options: sonnet, opus, haiku

Variable	Description
ANTHROPIC_BASE_URL	Gateway endpoint URL
ANTHROPIC_AUTH_TOKEN	Your credentials (see Get Access)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Disables update checks and other non-essential network traffic
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	Optional — Set to 1 to disable experimental beta features. Remove this variable to enable the 1M context window option in the model picker. The gateway whitelists only supported beta features.

Model Pinning (Strongly Recommended)

When Claude Code updates, it may default to newer model versions that are not yet available on the PwC GenAI Shared Service. This causes errors because the gateway doesn't recognize the new model ID. Pinning model versions prevents this issue by locking each model to a known, supported version.

Variable	Recommended Value	Description
ANTHROPIC_DEFAULT_OPUS_MODEL	claude-opus-4-7	Pin the Opus model version
ANTHROPIC_DEFAULT_SONNET_MODEL	claude-sonnet-4-6	Pin the Sonnet model version
ANTHROPIC_DEFAULT_HAIKU_MODEL	claude-haiku-4-5-20251001	Pin the Haiku model version

The values shown above use the vendor naming convention — the same format accepted by the gateway. See the Available Models page for the full list of supported model IDs and their accepted naming formats.

Pinned versions updated

When we add support for new models on the gateway, we'll update the recommended pinned versions in this guide. Check back here after gateway updates for the latest values.

Features

Auto Memory (CLAUDE_CODE_DISABLE_AUTO_MEMORY)

Auto Memory allows Claude to remember project patterns, conventions, and your preferences across sessions. It stores notes in a MEMORY.md file within your project's .claude/ directory, helping Claude provide more consistent and context-aware assistance over time.

Value	Behavior
"0"	Enabled (recommended) — Claude learns and remembers across sessions
"1"	Disabled — Claude starts fresh each session

Agent Teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS)

Agent Teams allows Claude to spawn multiple sub-agents that work in parallel on complex tasks. For example, one agent can research while another implements, or multiple agents can work on independent parts of a codebase simultaneously.

Value	Behavior
"1"	Enabled (recommended) — Claude can use multi-agent collaboration
Not set	Disabled — Claude works as a single agent

📖 Official docs: Agent Teams

1M Context Window (Opus)

Claude Opus 4.6 and Claude Sonnet 4 support a 1M-token context window — 5x the standard 200K limit. This is available as an opt-in feature through Claude Code's built-in model picker.

How to Enable

1. Remove CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS from your settings.json (or set it to 0). This variable was previously required; it is now optional.
2. In Claude Code, run /model and select "Opus (1M context)", or type /model opus[1m].
3. The gateway automatically captures the anthropic-beta: context-1m-2025-08-07 header and forwards it to the upstream provider.

Cost

Requests using the 1M context window that exceed 200K input tokens are billed at 2x the standard input rate. Requests under 200K tokens are billed at the normal rate, even with the 1M option selected.

Input Tokens	Input Price Multiplier
≤ 200K	1x (standard)
> 200K	2x

How to Disable

• Keep CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 in your settings.json to hide the 1M context option entirely and stay on the standard 200K limit.
• Alternatively, set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 to hide only the 1M option while allowing other beta features.

When to use 1M context

The 1M context window is useful for working with very large codebases or when you need Claude to hold extensive file contents in memory. However, be aware of context rot — performance can degrade in very large contexts. Use /compact regularly even with the larger window.

Verify Configuration

After saving your settings.json, verify the configuration is working:

1. Open a terminal and run claude
2. Claude Code should start without prompting for Anthropic login
3. Send a test message to confirm connectivity to the gateway

If successful, you'll see responses from Claude without needing an Anthropic account.

Network Requirements

You must be connected to the PwC VPN (Italy or Italy On-Premise) to reach the gateway endpoint. See the overview page for details on available endpoints.

Model Mapping

The gateway automatically maps Claude Code's model names (e.g., sonnet, opus, haiku) to the corresponding Anthropic models available on the PwC Shared Service. However, we strongly recommend pinning specific model versions in your settings.json (as shown in the Model Pinning section) to avoid breakage when Claude Code updates default to newer versions not yet supported by the gateway.

Usage Options

CLI (Recommended)

The configuration above works with Claude Code CLI. We recommend using modern terminals such as:

• Warp - Modern terminal with AI features
• Ghostty - Fast, native terminal

Using CLI allows you to add extensions that display remaining context window and budget in the status line through our utility tools.

VS Code Extension

This configuration also works with the Claude Code VS Code extension. All core features are available, though we recommend CLI for the full experience.

Additional Configuration

For all other Claude Code settings, including:

• Default model selection at startup
• Permissions configuration
• Plugins
• Default mode (plan, accept edits, etc.)

Refer to the official Claude Code documentation.

---

PwC Utility Tools

After setting up Claude Code, consider installing these optional tools created by the AI-CoE team:

Tool	Description
Status Line	Terminal status bar showing model, context window, costs, and remaining budget
Budget MCP Server	Query your remaining budget directly from Claude Code

See the Utility Tools section for installation instructions.