【Claude Code】2026 最全配置指南：API Key / 模型切换 / MCP 工具 / 常见报错，一篇搞定

【Claude Code】2026 最全配置指南：API Key / 模型切换 / MCP 工具 / 常见报错，一篇搞定

Claude Code 是 Anthropic 推出的 AI 编程助手，能在终端里直接帮你写代码、改 Bug、跑测试。但国内用起来，配置这一步就能劝退不少人——API Key 怎么配？想用 DeepSeek/通义千问替代怎么办？MCP 工具怎么装？报错了怎么排查？

这篇文章把安装、API 配置、模型切换、MCP 工具集成、常见报错全部讲清楚，每个步骤都给了具体命令，复制就能跑。

一、安装 Claude Code

前置条件

• Node.js >= 18（推荐 20+）
• 一个终端（macOS Terminal / Windows PowerShell 或 WSL2 / Linux Bash）

安装命令

npminstall-g@anthropic-ai/claude-code

安装完成后，终端输入claude验证：

claude--version

看到版本号就说明安装成功。

Windows 用户注意：Claude Code 在 Windows 上需要Git for Windows或WSL2。推荐用 WSL2，兼容性更好。WSL1 不支持沙箱功能，别装错了。

二、API Key 配置

Claude Code 支持多种认证方式，这里按使用场景分类讲。

2.1 官方 Anthropic API（海外用户）

直接用 Anthropic 官方 API Key：

# macOS / LinuxexportANTHROPIC_API_KEY="sk-ant-xxxxx"# Windows PowerShell$env:ANTHROPIC_API_KEY="sk-ant-xxxxx"# Windows CMDsetANTHROPIC_API_KEY=sk-ant-xxxxx

API Key 在 Anthropic Console 申请。

2.2 DeepSeek 接入（国内推荐，性价比最高）

DeepSeek 提供了 Anthropic 兼容接口，可以直接在 Claude Code 里用 DeepSeek 的模型。

API Key 申请：https://platform.deepseek.com/api_keys

配置方法：

# macOS / LinuxexportANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"exportANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key"exportANTHROPIC_MODEL="deepseek-v4-pro"exportANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro"exportANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro"exportANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"exportCLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"exportCLAUDE_CODE_EFFORT_LEVEL="max"

# Windows PowerShell$env:ANTHROPIC_BASE_URL ="https://api.deepseek.com/anthropic"$env:ANTHROPIC_AUTH_TOKEN ="你的DeepSeek API Key"$env:ANTHROPIC_MODEL ="deepseek-v4-pro"$env:ANTHROPIC_DEFAULT_OPUS_MODEL ="deepseek-v4-pro"$env:ANTHROPIC_DEFAULT_SONNET_MODEL ="deepseek-v4-pro"$env:ANTHROPIC_DEFAULT_HAIKU_MODEL ="deepseek-v4-flash"$env:CLAUDE_CODE_SUBAGENT_MODEL ="deepseek-v4-flash"$env:CLAUDE_CODE_EFFORT_LEVEL ="max"

参数说明：

提示：CLAUDE_CODE_EFFORT_LEVEL设为max才能让 DeepSeek 用满血推理能力。如果只是简单任务，可以设为low省钱。

2.3 阿里百炼（通义千问）接入

阿里云百炼支持 Anthropic 兼容接口，可以用通义千问系列模型。

API Key 申请：https://bailian.console.aliyun.com

配置方法：

# macOS / LinuxexportANTHROPIC_AUTH_TOKEN="你的百炼API Key"exportANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/apps/anthropic"exportANTHROPIC_MODEL="qwen3-coder-plus"

# Windows PowerShell$env:ANTHROPIC_AUTH_TOKEN ="你的百炼API Key"$env:ANTHROPIC_BASE_URL ="https://dashscope.aliyuncs.com/apps/anthropic"$env:ANTHROPIC_MODEL ="qwen3-coder-plus"

可选模型：qwen3-max、qwen3-coder-plus、qwen3-coder等。

2.4 智谱 GLM 接入

API Key 申请：https://open.bigmodel.cn

exportANTHROPIC_AUTH_TOKEN="你的GLM API Key"exportANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/paas/v4/anthropic"exportANTHROPIC_MODEL="glm-4-plus"

2.5 MiniMax 接入

API Key 申请：https://platform.minimaxi.com

exportANTHROPIC_AUTH_TOKEN="你的MiniMax API Key"exportANTHROPIC_BASE_URL="https://api.minimax.chat/v1/anthropic"exportANTHROPIC_MODEL="MiniMax-Text-01"

2.6 通过 settings.json 持久化配置（推荐）

每次都 export 环境变量太麻烦，可以直接写到配置文件里。

配置文件路径：~/.claude/settings.json

# 如果 .claude 目录不存在，先创建mkdir-p~/.claude

编辑~/.claude/settings.json：

{"env":{"ANTHROPIC_BASE_URL":"https://api.deepseek.com/anthropic","ANTHROPIC_AUTH_TOKEN":"你的API Key","ANTHROPIC_MODEL":"deepseek-v4-pro","ANTHROPIC_DEFAULT_OPUS_MODEL":"deepseek-v4-pro","ANTHROPIC_DEFAULT_SONNET_MODEL":"deepseek-v4-pro","ANTHROPIC_DEFAULT_HAIKU_MODEL":"deepseek-v4-flash","CLAUDE_CODE_SUBAGENT_MODEL":"deepseek-v4-flash","CLAUDE_CODE_EFFORT_LEVEL":"max"}}

这样每次启动 Claude Code 都会自动加载配置，不用重复设置。

三、模型切换

3.1 启动时指定模型

claude--modeldeepseek-v4-pro

3.2 交互模式中切换

进入 Claude Code 后，直接输入：

/model deepseek-v4-flash

3.3 查看当前可用模型

/model

3.4 多模型配置对照表

3.5 通过 OpenRouter 接入更多模型

如果你想用 Claude 官方模型但不在海外，可以通过 OpenRouter 中转：

exportANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"exportANTHROPIC_AUTH_TOKEN="你的OpenRouter API Key"exportANTHROPIC_MODEL="anthropic/claude-sonnet-4-20250514"

OpenRouter 支持的模型列表：https://openrouter.ai/models

3.6 通过 Ollama 接入本地模型

想完全离线跑？用 Ollama 挂本地模型：

# 先安装 Ollama 并拉取模型ollama pull qwen2.5-coder:14b# 配置 Claude Code 使用 OllamaexportANTHROPIC_BASE_URL="http://localhost:11434/anthropic"exportANTHROPIC_MODEL="qwen2.5-coder:14b"

四、MCP 工具集成

MCP（Model Context Protocol）是 Anthropic 推出的开源通信标准，让 Claude Code 能调用外部工具——访问文件系统、连接 API、操作数据库、集成 GitHub 等。

4.1 MCP 配置文件

MCP 工具的配置文件在~/.claude/mcp.json（全局）或项目目录下的.claude/mcp.json（项目级）。

4.2 内置 MCP 工具：文件系统

{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@anthropic-ai/mcp-server-filesystem","/path/to/your/project"]}}}

4.3 GitHub 集成

{"mcpServers":{"github":{"command":"npx","args":["-y","@anthropic-ai/mcp-server-github"],"env":{"GITHUB_TOKEN":"你的GitHub Personal Access Token"}}}}

GitHub Token 在 Settings → Developer settings → Personal access tokens 创建，需要勾选repo权限。

4.4 数据库集成（PostgreSQL）

{"mcpServers":{"postgres":{"command":"npx","args":["-y","@anthropic-ai/mcp-server-postgres","postgresql://user:password@localhost:5432/mydb"]}}}

4.5 Puppeteer 浏览器自动化

{"mcpServers":{"puppeteer":{"command":"npx","args":["-y","@anthropic-ai/mcp-server-puppeteer"]}}}

4.6 Slack 集成

{"mcpServers":{"slack":{"command":"npx","args":["-y","@anthropic-ai/mcp-server-slack"],"env":{"SLACK_BOT_TOKEN":"xoxb-你的token","SLACK_TEAM_ID":"T你的team_id"}}}}

4.7 验证 MCP 工具是否生效

启动 Claude Code 后，输入：

/mcp

能看到已加载的 MCP 工具列表就说明配置成功。

五、常见报错与解决方案

5.1 认证相关报错

报错：authentication_error/401 Unauthorized

原因：API Key 无效、过期、或配错了工作区。

解决方案：

1. 检查 API Key 是否正确复制（注意前后空格）
2. 确认 Key 没有过期或被撤销
3. 如果用 Anthropic 官方 Key，确认 Console 里的工作区权限
4. macOS 用户如果突然认证失败，尝试删除 Keychain 中存储的旧凭证，重新登录

# macOS 清除 Keychain 中的 Claude 凭证security delete-generic-password-s"claude"2>/dev/null claude# 重新登录

5.2 速率限制报错

报错：429 Too Many Requests/rate_limit_error

原因：请求频率超过 API 限额。Anthropic 的限额会随使用量自动从 Tier 1 升到 Tier 4，但突然的高并发仍会触发限流。

解决方案：

1. 等待retry-after头指定的时间后重试
2. 减少并发任务数（不要同时开多个 Claude Code 窗口跑大任务）
3. 子 Agent 模型用轻量版（如deepseek-v4-flash）减少配额消耗
4. 关注 Anthropic 的 状态页，确认不是平台侧问题

5.3 服务器错误

报错：500 Internal Server Error/529 Overloaded

原因：Anthropic 服务端临时故障。

解决方案：

1. 先查 Anthropic 状态页，确认是否是已知故障
2. 等几分钟后重试，带指数退避
3. 如果持续出现，用/bug命令上报

5.4 WSL 相关报错

报错：Claude Code 在 WSL 中无法启动、网络不通、或命令行为异常。

解决方案：

# 确认 WSL 版本（必须是 WSL2）wsl.exe-v# 确认发行版wsl.exe-l-v# 如果是 WSL1，升级到 WSL2wsl.exe --set-version Ubuntu2

如果 WSL2 内存不足导致卡顿，编辑~/.wslconfig限制资源：

[wsl2] memory=8GB processors=4 swap=4GB

5.5 配置文件损坏导致崩溃

报错：RangeError: Maximum call stack size exceeded/ Claude Code 启动直接崩溃。

原因：~/.claude.json文件损坏（可能被意外创建为文件夹）。

解决方案：

# 检查 ~/.claude.json 是否是文件夹ls-la~/.claude.json# 如果是文件夹，重命名后重建mv~/.claude.json ~/.claude.json.bakecho'{}'>~/.claude.json

5.6 MCP 工具加载失败

报错：MCP 工具不显示、或调用时报错。

解决方案：

1. 运行/doctor检查 MCP 配置是否有语法错误
2. 确认mcp.json是合法 JSON（注意不能有注释、尾逗号）
3. 手动测试 MCP Server 命令是否能正常运行：

npx-y@anthropic-ai/mcp-server-filesystem /path/to/project

4. 检查 Node.js 版本是否 >= 18

5.7 Windows localhost 不通

报错：Claude Code 无法访问本地服务（如 Ollama、本地数据库）。

原因：Windows 11 某些累积更新（如 KB5066835）会破坏 localhost 行为。

解决方案：

1. 检查 Windows 更新记录，回滚可疑更新
2. 在 WSL2 中用127.0.0.1代替localhost
3. 检查防火墙设置是否拦截了端口

5.8 通用排查流程

遇到任何报错，按这个顺序排查：

1. 查 Anthropic 状态页 → 排除平台故障 2. 运行 /doctor → 自动诊断常见问题 3. 检查环境变量 → echo $ANTHROPIC_BASE_URL 4. 检查配置文件 → cat ~/.claude/settings.json 5. 检查 MCP 配置 → cat ~/.claude/mcp.json 6. 仍无法解决 → 运行 /bug 上报

六、进阶技巧

6.1 CLAUDE.md 项目配置

在项目根目录创建CLAUDE.md，写入项目特定的指令：

# 项目规范 - 使用 TypeScript strict 模式 - 测试框架用 Vitest - 代码风格遵循 ESLint 配置 - 提交信息遵循 Conventional Commits

Claude Code 启动时会自动读取这个文件，按你的规范来写代码。

6.2 Claude Code 作为 MCP Server

Claude Code 本身也可以作为 MCP Server 被其他工具调用：

{"mcpServers":{"claude-code":{"command":"claude","args":["mcp"]}}}

6.3 API 管理工具：CC Switch

如果你需要频繁切换不同的 API 配置（官方 / DeepSeek / 通义千问），推荐用 CC Switch：

# 下载安装# https://github.com/farion1231/cc-switch/releases# 图形化管理 API 配置，一键切换

支持 Windows / macOS / Linux，不用手动改环境变量了。

七、速查表

写在最后

Claude Code 的配置确实比 Cursor 这些 GUI 工具麻烦一些，但一旦配好，终端里的 AI 编程体验是其他工具给不了的——直接在项目目录里改代码、跑测试、提交 Git，全程不用切窗口。

如果你在配置过程中遇到本文没覆盖的问题，可以在评论区留言，我会持续更新。

相关文章推荐：

• Claude Code 常见报错解决指南（持续更新）
• 在 Claude Code 里用 DeepSeek V4：两种方法完整配置指南