Claude Code 配置 Azure OpenAI 完整指南

本文将详细介绍如何将 Claude Code 配置为使用 Azure OpenAI 服务（以 gpt-4o 为例），包括完整步骤、常见问题及解决方案。

---

📌 目录

1. 前置准备
2. 快速配置流程
3. 详细配置步骤
4. 常见问题与解决方案
5. 成功配置示例
6. 总结与建议

---

前置准备

在开始之前，请确保你具备以下条件：

项目	说明
✅ Azure 账号	已开通 OpenAI 服务
✅ 模型部署	在 Azure OpenAI Studio 中已部署模型（推荐 gpt-4o）
✅ API Key	从 Azure 门户获取的密钥
✅ Endpoint	Azure OpenAI 资源的终结点地址
✅ Node.js	版本 18.0 或更高
✅ Claude Code	已全局安装

---

快速配置流程

如果你已经熟悉基本概念，可以直接参考以下精简步骤：

# 终端 1：启动代理
npx claude-bridge -u https://你的资源名.openai.azure.com/openai/v1 \
  -k 你的API密钥 \
  -m gpt-4o

# 终端 2：启动 Claude Code
export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_AUTH_TOKEN="dummy"
claude

⚠️ 注意：两个终端需要同时保持运行，关闭代理终端会导致 Claude Code 无法工作。

---

详细配置步骤

第一步：安装 Claude Code

使用国内 npm 镜像安装（避免网络问题）：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

验证安装：

claude --version

第二步：安装代理工具

claude-bridge 是一个轻量级代理，负责将 Claude Code 的请求格式转换为 Azure OpenAI 兼容的格式。

npx claude-bridge@latest

首次运行会提示安装，输入 y 确认。

第三步：获取 Azure OpenAI 信息

登录 Azure 门户，找到你的 OpenAI 资源：

1. 进入 “密钥和终结点” 页面
2. 复制 终结点（Endpoint），格式如：https://xxx.openai.azure.com/
3. 复制 KEY 1 或 KEY 2 作为 API 密钥
4. 进入 Azure OpenAI Studio -> Deployments，记录你的部署名称（如 gpt-4o）

🔑 关键提醒：部署名称是你自己创建的，不是模型名称！例如你可以将 gpt-4o 模型部署为 my-gpt4，那么后续命令中 -m 参数应使用 my-gpt4。

第四步：启动代理服务

终端 1 执行：

npx claude-bridge -u https://你的资源名.openai.azure.com/openai/v1 \
  -k 你的API密钥 \
  -m gpt-4o

成功启动后，你会看到：

🌉 Claude Bridge v1.0.0
✅ Server running at: http://localhost:8000
🎯 Target API: https://xxx.openai.azure.com/openai/v1
🤖 Model: gpt-4o

第五步：启动 Claude Code

终端 2 执行：

export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_AUTH_TOKEN="dummy"
claude

启动成功后会显示欢迎界面，输入 /model 确认当前模型为 gpt-4o，然后就可以正常使用了。

---

常见问题与解决方案

问题 1：404 Resource Not Found

错误信息：

API Error: 404 {"error":{"code":"404","message":"Resource not found"}}

原因： Azure 终结点 URL 格式错误，缺少 /openai 路径段。

解决方案：

❌ 错误格式	✅ 正确格式
https://xxx.openai.azure.com/v1	https://xxx.openai.azure.com/openai/v1
https://xxx.openai.azure.com/	https://xxx.openai.azure.com/openai/v1

---

问题 2：DeploymentNotFound

错误信息：

API Error: 404 {"error":{"code":"DeploymentNotFound","message":"The API deployment for this resource does not exist."}}

原因： -m 参数指定的部署名称与 Azure 中实际创建的部署名称不一致。

解决方案：

1. 登录 Azure OpenAI Studio
2. 进入 Deployments 页面
3. 查看并复制实际的部署名称
4. 使用正确的名称重启 claude-bridge

npx claude-bridge -u ... -k ... -m 实际部署名称

---

问题 3：Unsupported parameter: 'max_tokens'

错误信息：

Unsupported parameter: 'max_tokens' is not supported with this model. 
Use 'max_completion_tokens' instead.

原因： 较新的模型（如 GPT-5 系列）已弃用 max_tokens 参数，改用 max_completion_tokens。而 claude-bridge 作为通用适配器，默认仍发送 max_tokens。

临时解决方案：

npx claude-bridge ... --max-tokens 4096

根本解决方案：

切换到兼容性更好的模型（如 gpt-4o 或 gpt-4-turbo），这些模型同时支持两种参数格式，不会触发此错误。

# 使用 gpt-4o 替代 GPT-5 系列
npx claude-bridge ... -m gpt-4o

---

问题 4：The requested operation is unsupported

错误信息：

API Error: 400 {"error":{"message":"The requested operation is unsupported."}}

原因： 当前模型不支持流式响应（streaming）或工具调用（function calling）。

解决方案：

1. 确认使用的是支持工具调用的模型（如 gpt-4o、gpt-4-turbo）
2. 如必须使用受限模型，可尝试禁用流式响应：

export CLAUDE_BRIDGE_DISABLE_STREAMING=true
npx claude-bridge ...

---

问题 5：Failed to install Anthropic marketplace

错误信息：

Failed to install Anthropic marketplace · Will retry on next startup

原因： 网络环境无法访问 Anthropic 官方插件市场。

解决方案：

• 方案 A（推荐）：忽略此警告，不影响 Claude Code 核心功能
• 方案 B：删除损坏的配置文件

rm ~/.claude/settings.json
rm -rf ~/.claude/plugins/cache

---

问题 6：模型兼容性对比

根据实际测试，不同模型与 Claude Code 的兼容性如下：

模型	兼容性	工具调用	参数兼容	推荐度
gpt-4o	✅ 优秀	完整支持	良好	⭐⭐⭐⭐⭐
gpt-4-turbo	✅ 良好	完整支持	良好	⭐⭐⭐⭐
gpt-35-turbo	⚠️ 一般	基础支持	良好	⭐⭐⭐
gpt-5.4-mini	❌ 差	不稳定	有兼容问题	⭐
gpt-5.3-codex	❌ 差	不支持	有兼容问题	⭐

💡 结论：推荐使用 gpt-4o 获得最佳体验。

---

成功配置示例

以下是一次成功的完整配置日志：

终端 1（代理服务）

$ npx claude-bridge -u https://你的资源名.openai.azure.com/openai/v1 \
  -k XXX \
  -m gpt-4o

🌉 Claude Bridge v1.0.0
✅ Server running at: http://localhost:8000
🎯 Target API: https://你的资源名.openai.azure.com/openai/v1
🤖 Model: gpt-4o

📖 Usage with Claude Code CLI:
   export ANTHROPIC_BASE_URL=http://localhost:8000
   export ANTHROPIC_AUTH_TOKEN="dummy"
   claude

终端 2（Claude Code）

$ export ANTHROPIC_BASE_URL=http://localhost:8000
$ export ANTHROPIC_AUTH_TOKEN="dummy"
$ claude

╭─── Claude Code v2.1.132 ─────────────────────────────────────────────────╮
│                                                                          │
│                 Welcome back!                                            │
│                   ▗ ▗   ▖ ▖                                               │
│                     ▘▘ ▝▝                                                 │
│   Opus 4.7 (1M context) · API Usage Billing                              │
│                   ~/.claude                                              │
╰──────────────────────────────────────────────────────────────────────────╯

> 你好，请介绍一下自己

代理终端输出（正常请求）

[2026-05-07T06:15:23.456Z] POST /v1/messages - ::1
📨 Received Claude request: {
  model: 'gpt-4o',
  messageCount: 1,
  hasTools: true,
  streaming: true,
  maxTokens: 8192
}
[2026-05-07T06:15:24.789Z] ✅ API Response: 200 OK

---

总结与建议

关键要点

序号	要点	说明
1	URL 格式	必须包含 /openai/v1，不能写成 /v1
2	模型选择	优先使用 gpt-4o，避免 GPT-5 系列
3	部署名称	-m 参数使用 Azure 中的部署名称，不是模型名称
4	参数兼容	max_tokens 错误通过换模型解决，而非加参数
5	双终端	代理和 Claude Code 需要同时运行

最佳实践

1. 首次配置建议使用 gpt-4o，兼容性最好，问题最少
2. 保存 Azure 信息：将 Endpoint、API Key、部署名称保存在安全位置
3. 使用别名简化命令：

# 添加到 ~/.zshrc 或 ~/.bashrc
alias claude-azure='export ANTHROPIC_BASE_URL=http://localhost:8000 && export ANTHROPIC_AUTH_TOKEN="dummy" && claude'

4. 后台运行代理（可选）：

nohup npx claude-bridge -u ... -k ... -m gpt-4o > claude-bridge.log 2>&1 &

排错流程图

启动 Claude Code
        ↓
   连接失败？
   ├── 是 → 检查代理是否运行
   │         ↓
   │      404 错误？
   │      ├── 是 → 检查 URL 是否包含 /openai
   │      └── 否 → DeploymentNotFound？
   │              ├── 是 → 检查 -m 参数是否匹配 Azure 部署名
   │              └── 否 → max_tokens 错误？
   │                      ├── 是 → 切换到 gpt-4o
   │                      └── 否 → 查看详细错误日志
   │
   └── 否 → ✅ 配置成功，正常使用

---

相关资源

• Claude Code 官方文档
• claude-bridge GitHub
• Azure OpenAI 文档

---

本文档基于实际配置经验整理，最后更新于 2026年5月。如有问题或建议，欢迎交流讨论。