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:

You can use an installation script to automate the installation process.

🖥️ MacOs Installation Script: 📥 Download install-claude.sh

Run it with:

cd ~/Downloads
chmod +x install-claude.sh
sh install-claude.sh

💻 Windows Installation Script 📥 Download install-claude.ps1

Open a new PowerShell terminal and run the following commands:

cd C:\Users\<your-guid>\Downloads
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
./install-claude.ps1

You may need to close and reopen the terminal after each step, check whether the installation has been successful typing in a new shell:

claude

VPN Requirement

To run the installation script (Bash, Brew, npm) you must be disconnected from PwC Global Protect VPN during the whole process, as the VPN blocks the package download.

Manual Configuration

Not mandatory

A manual configuration is not needed if you used one of the installation scripts since they automatically create and set up the settings file

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.

For Opus, always pin using the bare vendor name (claude-opus-4-7, not bedrock.anthropic.claude-opus-4-7) so Claude Code correctly recognises the 1M context window and doesn't compact prematurely. See 1M Context Window for details.

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.7, Opus 4.6, and Sonnet 4 support a 1M-token context window — 5x the standard 200K limit. The gateway automatically enables 1M for all requests targeting these models — no opt-in needed.

What Claude Code sends to the gateway

The gateway recognises multiple ways Claude Code can request 1M context:

Scenario	Model name in request	anthropic-beta header	Gateway behaviour
Model picker → "Opus (1M context)"	claude-opus-4-7[1m]	context-1m-2025-08-07	strips [1m], auto-injects beta
Model picker → "Opus (200K)"	claude-opus-4-7	(absent)	auto-injects beta anyway (model is 1M-capable)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7	claude-opus-4-7	(absent)	auto-injects beta
ANTHROPIC_DEFAULT_OPUS_MODEL=GENAI_SHARED_BEDROCK_ANTHROPIC_CLAUDE_47_OPUS	same internal name	(absent)	auto-injects beta
ANTHROPIC_DEFAULT_OPUS_MODEL=bedrock.anthropic.claude-opus-4-7	same upstream ID	(absent)	auto-injects beta

The gateway strips the [1m] suffix before model resolution and auto-injects anthropic-beta: context-1m-2025-08-07 for every model in the 1M-capable set (Opus 4.7, Opus 4.6, Sonnet 4 — both Bedrock and Vertex).

Claude Code's local context window awareness

Claude Code uses its own heuristics to decide when to compact the conversation. If you pin a model with ANTHROPIC_DEFAULT_OPUS_MODEL, use the bare vendor name (e.g., claude-opus-4-7) rather than the provider-prefixed form (e.g., bedrock.anthropic.claude-opus-4-7). Claude Code recognises bare names as 1M-capable and will not compact prematurely. With provider-prefixed names, Claude Code treats the model as unknown and defaults to the 200K compaction threshold — even though the gateway is sending the 1M beta header upstream.

How to Enable (model picker)

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].

Using Opus 4.6 with 1M context

If you pin ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6, Claude Code still shows the 1M option in the model picker. Selecting it sends claude-opus-4-6[1m] to the gateway, which resolves correctly. Use the bare vendor name (not bedrock.anthropic.claude-opus-4-6) so Claude Code recognises the model and does not compact prematurely.

Do not add [1m] directly inside ANTHROPIC_DEFAULT_OPUS_MODEL — Claude Code ignores the suffix in that context and will still compact at 200K locally, even though the gateway would activate 1M upstream.

Cost

All requests to 1M-capable models have the 1M beta header injected by the gateway. This means extended context is always available. However, billing at 2x only applies when input exceeds 200K tokens.

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

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.