先把模型托管位置确认清楚
接到这类问题时,我不会先打开终端,而是先确认模型到底在哪个资源里。先确认你的模型托管位置:Azure OpenAI 服务目前只提供 OpenAI 自家的模型,不包含 Claude。如果你在 Azure 门户里能找到 Claude 模型,通常是通过 Azure AI Foundry(原 Azure AI Studio)的模型目录或 Azure 上其他第三方托管服务获得的。接入前先打开 Azure 门户,查看你创建的资源类型——如果资源类型是“Azure OpenAI”,则不能用它来配置 Claude Code;如果是“AI Foundry”或“机器学习”工作区,则可能支持 Anthropic API 兼容端点。这一步不核实清楚,后续所有配置都会偏离方向。
这里的关键是区分 Azure OpenAI 和 Azure AI Foundry:前者只提供 GPT 系列等 OpenAI 模型,后者才可能通过模型目录提供 Anthropic 模型。如果你是通过 Azure 的模型市场或第三方服务商购买的 Claude,还需要确认对方给出的接入地址是否为 Anthropic 兼容格式。很多时候,用户以为自己在用 Azure 官方,实际是第三方转售,这会影响后续 base_url 的拼法。
地址写错是最容易误判的地方
最常见的坑是把 Azure OpenAI 的 endpoint 直接当成 Anthropic 的 base_url。Azure OpenAI 的 endpoint 形如 https://resource.openai.azure.com,而 Anthropic 兼容路径需要在后面追加 /anthropic。很多人在配置文件里写了 export ANTHROPIC_BASE_URL=https://resource.openai.azure.com,结果请求落到了 /v1/messages 上,返回 404。另一个坑是模型别名:Azure 上的 Claude 部署名可能是 claude-3-5-sonnet 或自定义名称,但 Claude Code 内部可能会用 claude-opus-4 这类标识去请求,导致找…
当出现这类报错时,先别急着怀疑密钥。用 curl 分别请求 https://资源名.services.ai.azure.com/anthropic/v1/messages 和 https://资源名.openai.azure.com/v1/messages,看哪条路径返回非 404,就能判断地址有没有拼对。
环境变量要按 Anthropic 兼容方式设置
确认资源类型和地址形态后,需要把 Claude Code 指向 Anthropic 兼容端点。以 Claude Code 当前支持的接入方式为例,设置环境变量时不能直接沿用 OpenAI 的 AZURE_OPENAI_KEY 或 AZURE_OPENAI_ENDPOINT。你需要把 Claude Code 指向 Anthropic 兼容的 base_url,通常写法是:export ANTHROPIC_BASE_URL=https://your-resource-name.services.ai.azure.com/anthropic;同时设置 export ANTHROPIC_AUTH_TOKEN=你的密钥,并确保 ANTHROPIC_API_KEY 未被占用。配置完成后,在终端执行 claude 命令,如果出现模型名称输入提示,就选与你 Azure 账号匹配的 Claude 模型别名;没有别名就手动…
这里要特别留意 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 的区别。Claude Code 在检测到 ANTHROPIC_API_KEY 时,会优先用这个变量做 Bearer 认证,而 Azure 的认证通常要求用 OAuth token 或 API key 放进 x-api-key 头。所以最好在启动前先执行 unset ANTHROPIC_API_KEY,避免冲突。另外,ANTHROPIC_BASE_URL 末尾不要带斜杠,可写成 export ANTHROPIC_BASE_URL="https://your-resource-name.services.ai.azure.com/anthropic",但不要带 /v1,因为 Claude Code 会自动补上。
验证请求是否真的走通
配置完成后,不能只看终端有没有报错。验证接入是否成功的重点是看网络请求是否到达正确地址。启动 Claude Code 后,先运行一个简单命令,比如 /status,观察输出里是否有“Connected to”或“API endpoint”字段。如果提示 connection refused 或 404,说明 base_url 路径不对;如果提示 401,说明密钥或 token 无效。更保险的做法是在终端里用 curl 直接测试:curl -X POST $ANTHROPIC_BASE_URL/v1/messages -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -d '{"model":"替代为部署名","max_tokens":20}'。返回正常…
返回正常后,再回到 Claude Code 的 /status 看“API endpoint”字段,确认它显示的地址包含 /anthropic。如果显示的是官方 API,说明环境变量没有生效,多半是当前 shell 里仍保留了旧的 ANTHROPIC_BASE_URL。
接入后要留意的限制
Azure 托管的 Claude 不是官方 API,配额、容量和审核策略都可能不同。使用 Azure 托管的 Claude 模型时,注意托管平台的配额和内容审核策略与 Anthropic 官方 API 不完全一致。Azure AI Foundry 上的模型可能会受区域的网络隔离和防火墙规则影响,即使配置正确,公司内网也可能默认禁止访问外部 API。不能在 Claude Code 的配置里直接设置 ANTHROPIC_API_KEY,否则会覆盖 Azure 的认证信息。此外,部分 Azure 区域未提供 Claude 模型的按需付费,你可能会遇到“No available capacity”的错误,这种情况需要调整部署区域或等待资源空闲,而不是反复重试。
我的做法是:遇到容量错误时,先查当前区域的部署列表,用 az cognitiveservices account list-deployments 确认模型是否真的可用;如果可用但仍报容量不足,就暂时切换到另一个区域或改用代理资源。内容审核方面,Azure 的 AI Foundry 可能默认开启内容过滤,敏感代码或安全相关提示可能被拦截,这不是配置能解决的。
本地环境也要提前检查
最后检查运行环境。接入前需要确认本地环境满足基本条件:Node.js 版本不低于 18,因为 Claude Code 依赖 Node 运行;网络能直接访问 Azure 的 endpooint 域名,不能用 wss 代理模式,否则 WebSocket 建立会失败。如果你使用企业代理,需为 ANTHROPIC_BASE_URL 和 wss:/// 域名单独设置 no_proxy。另外,Azure 上的 Claude 模型可能有不同的上下文窗口上限,Claude Code 默认会请求 200k 上下文,如果 Azure 上部署的模型只支持 100k,会导致请求被拒绝。遇到这种错误时,在配置里显式设置 MAX_THINKING_TOKENS 和上下文相关参数,不要依赖默认值。
上下文窗口问题不容易一开始就暴露,往往是在发送大文件时才报错。所以建议在 .claude/settings.json 里显式声明最大上下文,比如把 model 的 context_window 设为 100k,或者通过环境变量限制单次请求的长度。如果发现 WebSocket 连接失败,检查网络出口是否放行了 wss://your-resource.services.ai.azure.com,并确认没有走额外代理。