Claude Code 国内接入教程（2026 最新）

Claude Code 是 Anthropic 官方推出的终端 AI 编程工具，它能理解你的整个代码库，通过自然语言命令执行日常任务、解释复杂代码以及处理 Git 工作流

旗舰模型使用 Opus 4.6 模型，支持高达 1M 上下文窗口。国内开发者要直连官方服务，需要海外信用卡、网络工具，还面临封号风险——门槛不低。

通过 https://claudeapi.com 中转接入Claude API，5 分钟内跑通 Claude Code。全程国内网络直连，支持支付宝/微信充值，无需注册 Anthropic 账号。

一、前置准备

开始之前，确认两件事：本地环境就绪，以及拿到 API Key。

1.1 环境要求

💡 重要变更： 2026 年的原生安装器（Native Installer）消除了 Node.js 依赖，解决了以往因 Node.js 版本不兼容导致的绝大多数安装问题。如果你之前因为环境问题卡过壳，现在可以放心了。

1.2 注册 claudeapi.com 并获取 API Key

这一步拿到你的专属密钥，后面配置全靠它。

第一步：注册账号

打开 https://claudeapi.com 点击注册，用邮箱或手机号完成注册，进入后台控制面板。

第二步：充值余额

在后台找到「充值」入口，选择支付宝或微信支付。平台汇率为 1 元人民币 = 1 美元额度，建议先充 5-10 元用于测试，跑通之后再按需加量。

第三步：创建 API 令牌

进入「API 令牌」页面 → 点击「添加令牌」→ 名称随意填写（如 claude-code-main）→ 额度设为无限 → 点击创建。

页面会显示一串以 sk- 开头的密钥，立刻复制保存，离开页面后将无法再次查看。

⚠️ 提示： 复制 Key 时注意首尾不要带空格，这是后面最常见的报错原因之一。

二、安装 Claude Code

Claude Code 目前有多种安装方式，推荐优先使用原生安装器（Native Installer），它是绝大多数用户的最佳选择。

2.1 方式一：原生安装（推荐，无需 Node.js）

原生安装是最快的方式，不需要 Node.js，不需要管理依赖，并且会在后台自动更新。

macOS / Linux / WSL：

curl -fsSL https://claude.ai/install.sh | bash

curl -fsSL https://claude.ai/install.sh | bash

Windows（PowerShell）：

irm https://claude.ai/install.ps1 | iex

irm https://claude.ai/install.ps1 | iex

macOS（Homebrew）：

brew install --cask claude-code

brew install --cask claude-code

📌 Homebrew 安装不会自动更新，需要定期运行 brew upgrade claude-code 来获取最新功能和安全修复。

安装完成后验证：

claude --version

claude --version

安装脚本会自动下载二进制文件到系统目录并添加到 PATH。安装完成后请打开一个新的终端窗口，以确保 shell 加载新的 PATH 条目。

安装命令执行后"没反应"怎么办？

如果你运行 curl -fsSL https://claude.ai/install.sh | bash 之后，终端一片空白、看起来像卡住了——别急，通常是以下三种情况之一：

情况一：其实还在跑，只是没输出

这条命令的工作流程是"先下载脚本，再执行"。如果你的网络较慢、DNS 解析延迟，或者到 claude.ai 的连接不稳定，终端可能会先卡住几秒到几十秒，看起来像没反应，实际上 curl 还在等服务器响应。

先等 30 秒左右。如果一直没动静，按 Ctrl + C 中断，然后单独测试连通性：

curl -I https://claude.ai/install.sh

curl -I https://claude.ai/install.sh

• 如果这条命令也卡住不返回——说明问题出在网络层面，不是 Claude Code 的问题。
• 如果能正常返回 HTTP 状态码（如 200、301、302），说明网络是通的，重新执行安装命令即可。

情况二：你的网络到 claude.ai 不通

如果上一步的 curl -I 也卡住了，说明你的网络无法访问 claude.ai。常见原因包括：

• 开了异常代理（Clash 全局模式 / 规则误拦截）
• DNS 配置有问题
• 公司/学校网络限制了出站请求
• 本机证书策略或防火墙拦截

执行以下三条命令逐步排查：

curl -I https://claude.ai
nslookup claude.ai
ping claude.ai

curl -I https://claude.ai
nslookup claude.ai
ping claude.ai

判断标准：

💡 快速修复： 如果是代理工具导致的问题，先关掉代理再执行安装命令。或者将 claude.ai 加入代理的直连规则。

情况三：终端在等待输入，但你没注意到

有些安装脚本执行过程中会弹出确认提示（如 Do you want to continue? [Y/n]），或者触发系统级的权限弹窗（macOS 的安全提示）。如果你的终端窗口较小或输出被遮挡，可能没看到提示，导致脚本一直在等你输入。

遇到这种情况，可以换一种更透明的安装方式——先下载脚本到本地，再带调试输出执行：

curl -fSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash -x /tmp/claude-install.sh

curl -fSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash -x /tmp/claude-install.sh

这样做的好处：

• 下载和执行分开：如果下载阶段就卡住了，你能立刻确认是网络问题。
• bash -x 开启调试模式：脚本执行的每一步都会打印出来，出错点一目了然。
• 脚本保存在本地：如果中途失败，可以直接 bash -x /tmp/claude-install.sh 重试，不用重新下载。

⚠️ 注意： 如果以上方式都无法下载安装脚本，说明你当前的网络环境确实无法直连 claude.ai。可以尝试切换网络（如手机热点），或者使用下一节介绍的 npm 安装方式作为替代。

2.2 方式二：npm 安装（旧方式，已弃用但仍可用）

npm 安装方式（npm install -g @anthropic-ai/claude-code）仍然可用，但根据 2026 年 3 月的官方文档已被正式弃用。如果你的环境特殊（如需要锁定特定版本），仍可使用此方式：

# 确保 Node.js ≥ 18
node --version

# 安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

# 确保 Node.js ≥ 18
node --version

# 安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

⚠️ 如果遇到 EACCES 权限错误，不要使用 sudo。用 sudo npm install -g 会创建属于 root 的文件，导致后续每次 npm 全局安装都出现权限问题。应该通过更改 npm 默认目录或使用 nvm 来解决根本问题。

正确的权限修复方式：

# 方案 A：修改 npm 全局目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 然后将 export PATH=~/.npm-global/bin:$PATH 加入 shell 配置文件

# 方案 B：使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
nvm use 22
npm install -g @anthropic-ai/claude-code

# 方案 A：修改 npm 全局目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 然后将 export PATH=~/.npm-global/bin:$PATH 加入 shell 配置文件

# 方案 B：使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
nvm use 22
npm install -g @anthropic-ai/claude-code

2.3 从旧版 npm 安装迁移到原生安装

如果你之前通过 npm 安装了 Claude Code，建议迁移到原生安装器。npm 方式自 2026 年初已被正式弃用，虽然目前仍可运行，但终将停止接收更新。原生安装器启动更快、零依赖、并且自动处理更新。

迁移步骤：

# 1. 卸载 npm 版本
npm uninstall -g @anthropic-ai/claude-code

# 2. 安装原生版本
curl -fsSL https://claude.ai/install.sh | bash   # macOS/Linux
# 或
irm https://claude.ai/install.ps1 | iex           # Windows PowerShell

# 3. 验证
claude --version

# 1. 卸载 npm 版本
npm uninstall -g @anthropic-ai/claude-code

# 2. 安装原生版本
curl -fsSL https://claude.ai/install.sh | bash   # macOS/Linux
# 或
irm https://claude.ai/install.ps1 | iex           # Windows PowerShell

# 3. 验证
claude --version

💡 你的配置文件（~/.claude/settings.json）和项目设置（.claude/）在迁移过程中会被保留，无需重新配置。

2.4 Windows 用户特别说明

Claude Code 现已原生支持 Windows，可直接通过 PowerShell 或 CMD 安装。不再像以前那样必须依赖 WSL。

两种路线：

如果选择原生 Windows 安装，整个过程请在 PowerShell 中完成，不要在安装阶段混用 PowerShell、CMD、Git Bash 和 WSL。

三、配置接入 claudeapi.com（核心步骤）

Claude Code 通过两个环境变量来决定"连谁的服务器"和"用什么身份"：

• ANTHROPIC_AUTH_TOKEN：你的 API Key
• ANTHROPIC_BASE_URL：API 服务地址，设为 https://code0.ai

下面提供三种配置方式，从快到稳，按需选择。

3.1 方式一：临时配置（快速测试用）

直接在终端设置环境变量，关掉终端就失效。适合先验证能不能跑通：

cd your-project
export ANTHROPIC_AUTH_TOKEN=sk-你的Key
export ANTHROPIC_BASE_URL=https://code0.ai
claude

cd your-project
export ANTHROPIC_AUTH_TOKEN=sk-你的Key
export ANTHROPIC_BASE_URL=https://code0.ai
claude

如果一切正常，你会看到 Claude Code 的交互界面。这种方式每次打开新终端都要重新设置，所以只建议用来做第一次测试。

3.2 方式二：写入 Shell 配置文件（永久生效）

把环境变量写进 Shell 启动文件，以后每次开终端自动加载。

Zsh（macOS 默认）：

echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的Key' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL=https://code0.ai' >> ~/.zshrc
source ~/.zshrc

echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的Key' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL=https://code0.ai' >> ~/.zshrc
source ~/.zshrc

Bash（大多数 Linux / WSL 默认）：

echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的Key' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL=https://code0.ai' >> ~/.bashrc
source ~/.bashrc

echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的Key' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL=https://code0.ai' >> ~/.bashrc
source ~/.bashrc

Fish：

set -Ux ANTHROPIC_AUTH_TOKEN sk-你的Key
set -Ux ANTHROPIC_BASE_URL https://code0.ai

set -Ux ANTHROPIC_AUTH_TOKEN sk-你的Key
set -Ux ANTHROPIC_BASE_URL https://code0.ai

Windows PowerShell（永久）：

setx ANTHROPIC_AUTH_TOKEN "sk-你的Key"
setx ANTHROPIC_BASE_URL "https://code0.ai"

setx ANTHROPIC_AUTH_TOKEN "sk-你的Key"
setx ANTHROPIC_BASE_URL "https://code0.ai"

设置完成后关闭并重新打开 PowerShell 窗口使其生效。

这种方式简单直接，但会把密钥暴露在 Shell 配置文件里。如果你的 dotfiles 会同步到 GitHub，需要注意安全。

3.3 方式三：settings.json 配置文件（推荐✅）

这是 Claude Code 原生支持的配置方式，不污染 Shell 环境，维护起来也更清晰。

全局配置（所有项目生效）：

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

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai"
  }
}

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai"
  }
}

如果 ~/.claude 目录不存在，先创建：

mkdir -p ~/.claude

mkdir -p ~/.claude

项目级配置（仅当前项目生效）：

文件路径：你的项目根目录/.claude/settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-另一个Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai"
  }
}

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-另一个Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai"
  }
}

项目级配置的优先级高于全局配置。如果你在不同项目中使用不同的 Key（比如个人项目和公司项目分开计费），这个特性非常实用。

✅ 推荐方案： 大多数人直接用全局 settings.json 即可。一次配好，所有项目通用，不会在 Shell 环境里留下敏感信息。

3.4 验证配置成功

无论你选了哪种方式，现在打开一个终端，进入任意项目目录：

cd any-project-folder
claude

cd any-project-folder
claude

进入 Claude Code 交互界面后，输入：

你好，请告诉我你是哪个模型

你好，请告诉我你是哪个模型

成功标志： 收到正常中文回复，并显示当前模型为 Claude Opus 4.6 或 Sonnet 4.6。

💡 额外提示： 首次运行如果不确定环境是否正常，可以使用 /doctor 命令自动检测常见配置问题，它会检查你的 Node.js 版本、认证状态、MCP 服务器健康度和文件权限，建议在手动排错之前先运行一次。

四、VS Code 中使用 Claude Code

除了终端 CLI，如果你不喜欢命令行模式，可以在 VS Code 编辑器中安装 Claude Code 扩展。

4.1 安装扩展

打开 VS Code → 进入扩展市场（Cmd+Shift+X / Ctrl+Shift+X）→ 搜索 Claude Code → 安装。

在扩展中同样需要配置 API。最简便的方式是使用全局 ~/.claude/settings.json（上一章已配置），VS Code 扩展会自动读取。

或者在 VS Code 中输入 /config，进入设置界面进行配置。

4.3 实用功能

安装完成后，你可以：

• 选中代码让 Claude 解释或修改
• 使用 @文件名 引用文件内容
• 通过 Shift+Tab 切换权限模式（正常模式 / 计划模式 / 自动接受模式）
• 使用 /compact 手动压缩上下文

💡 本文以 CLI 使用方式为主进行讲解，因为 CLI 最稳定、最通用，也最接近 Claude Code 的设计初衷。VS Code 扩展是锦上添花的补充。

五、模型切换与选择建议

claudeapi.com 支持多个 Claude 模型，不同模型在能力和价格上有明显差异。根据任务类型选对模型，既能保证效果，又能控制成本。

5.1 可用模型对比

更详细的模型定价，可查看价格与模型选择指南。

5.2 在 Claude Code 中切换模型

方法一：运行时命令切换

在 Claude Code 交互界面中输入：

/model claude-sonnet-4-6

/model claude-sonnet-4-6

切换即时生效，不用重启。

方法二：在 settings.json 中指定默认模型

在你的全局或项目级 settings.json 中加入 ANTHROPIC_MODEL：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

这样每次启动 Claude Code 都会默认使用指定模型。

5.3 省钱建议

Claude Code 按 Token 计费，单条 Claude Code 命令通常会产生 8 到 12 次 API 调用，一次重度会话可能消耗 $0.50 到 $2.00 的 API 成本。以下几个习惯能显著降低开支：

• 日常开发用 Sonnet 4.6，遇到复杂架构问题再手动 /model 切到 Opus，用完切回来。
• 用 /compact 命令压缩上下文。对话长了之后，Token 消耗会急剧上升，/compact 能清理冗余历史，保留关键信息。
• 用 /effort 调低推理力度。处理简单任务（比如改个变量名、加个注释）时，低推理力度既快又省。

努力等级简化为 low/medium/high 三档，使用 /effort auto 可重置为默认。

六、常见报错与排查

配置过程中遇到问题？下面整理了 7 个最常见的报错场景，按「症状 → 原因 → 解决」的格式逐条排查。

6.1 Invalid API Key 或 401 Unauthorized

原因： API Key 复制不完整，或者首尾多了空格。

排查： 在终端运行：

echo $ANTHROPIC_AUTH_TOKEN

echo $ANTHROPIC_AUTH_TOKEN

检查输出是否以 sk- 开头，末尾是否有多余字符。

解决： 回到 claudeapi.com 后台 重新复制 Key。如果你用的是 settings.json 配置方式，打开文件确认引号内没有空格。

6.2 Connection refused 或 ECONNREFUSED

原因： ANTHROPIC_BASE_URL 写错了。

排查：

echo $ANTHROPIC_BASE_URL

echo $ANTHROPIC_BASE_URL

确认输出是 https://code0.ai，注意：

• 必须是 https 不是 http
• 末尾不要加 /
• 不要拼错域名

解决： 修正 URL 后重新加载配置（source ~/.zshrc 或重启终端）。

6.3 timeout 或长时间无响应

原因： 本地代理软件（Clash、V2Ray 等）与 Claude Code 的连接冲突。

排查步骤：

先用 curl 测试 API 是否可达：

curl -s https://code0.ai/v1/models \
  -H "Authorization: Bearer sk-你的Key"

curl -s https://code0.ai/v1/models \
  -H "Authorization: Bearer sk-你的Key"

• 如果 curl 正常返回 JSON 数据，但 Claude Code 卡住——大概率是代理工具的问题。
• 关掉 Clash / V2Ray 等代理工具，或者将 code0.ai 加入直连规则（不走代理），再试。

解决： claudeapi.com 本身就是面向国内网络优化的中转服务，正常情况下不需要代理。关掉代理直连反而更快。

6.4 显示 offline 状态

原因： Claude Code 启动时会尝试连接 Google 等外部服务来检测网络状态，国内自然不通。

结论： 这个状态提示不影响实际使用。忽略即可，正常输入指令照样能得到回复。

6.5 模型返回乱码或中断

原因： 代理软件的「增强模式」或「全局模式」干扰了 SSE（Server-Sent Events）流式传输。代理工具会缓冲数据包，导致流式输出出现乱码或突然中断。

解决方案（二选一）：

1. 关闭代理工具的「增强模式」。
2. 将 code0.ai 加入代理软件的直连规则列表，让 Claude Code 的流量绕过代理。

6.6 fetch failed

原因： Claude Code 的网页浏览功能（如 /web 命令）需要访问外部网站，这部分流量不经过 claudeapi.com 中转，在国内网络下可能无法直连。

解决： 浏览网页功能需要额外的网络工具支持，但正常的代码编写、问答、重构等核心功能完全不受影响。如果你不需要网页浏览功能，可以忽略这个错误。

6.7 权限错误（EACCES / Permission denied）

原因： .claude 目录所有权不正确，常见于之前用 sudo 安装过。

排查与解决：

# 修复 .claude 目录的所有权
sudo chown -R $(whoami) ~/.claude

# 如果是 npm 安装的权限问题，参考 2.2 节中的正确权限修复方式

# 修复 .claude 目录的所有权
sudo chown -R $(whoami) ~/.claude

# 如果是 npm 安装的权限问题，参考 2.2 节中的正确权限修复方式

💡 更多错误代码可查阅报错速查表。

七、进阶技巧

Claude Code 的能力远不止"在终端里聊天"。以下几个功能值得了解，能大幅提升开发效率。

7.1 循环任务（v2.1.71+）

让 Claude 定时执行某个检查：

/loop 5m check the deploy status

/loop 5m check the deploy status

每 5 分钟自动检查一次部署状态并汇报。适合等构建、等部署时用。

7.2 CLAUDE.md 项目说明书

在项目根目录创建一个 CLAUDE.md 文件，Claude Code 在每次会话开始时都会自动读取。它会成为 Claude 系统提示的一部分，使每次对话都能预先加载项目上下文。

# CLAUDE.md
## 项目简介
这是一个 Next.js 14 项目，使用 TypeScript + Tailwind CSS。

## 代码规范
- 组件使用函数式写法
- 状态管理使用 Zustand
- API 请求统一放在 /lib/api 目录

## 构建与测试
- npm run build  # 构建
- npm run test   # 运行测试

# CLAUDE.md
## 项目简介
这是一个 Next.js 14 项目，使用 TypeScript + Tailwind CSS。

## 代码规范
- 组件使用函数式写法
- 状态管理使用 Zustand
- API 请求统一放在 /lib/api 目录

## 构建与测试
- npm run build  # 构建
- npm run test   # 运行测试

💡 最佳实践： 运行 /init 命令可以自动生成 CLAUDE.md。

保持内容精简，采用"渐进式披露"原则——不要把所有内容都塞进去，而是告诉 Claude 如何查找重要信息。同时不要用 CLAUDE.md 替代 linter，代码风格约束只会让上下文窗口膨胀。

7.3 MCP Server 集成

MCP（Model Context Protocol）让 Claude 不再局限于当前项目的代码文件，而是能主动连接外部世界的资源与工具——GitHub、数据库、Figma、Jira 等，让 AI 直接读取你的仓库 Issue、查询数据库、获取设计稿信息。

# 添加 GitHub MCP 服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 添加数据库 MCP 服务器
claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@host:5432/dbname"

# 查看已配置的服务器
claude mcp list

# 添加 GitHub MCP 服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 添加数据库 MCP 服务器
claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@host:5432/dbname"

# 查看已配置的服务器
claude mcp list

MCP 的配置和使用涉及较多内容，详细教程请参考 Claude Code 进阶技巧。

7.4 Skills 系统

Skills 是 Claude Code 推出的重磅功能，可以理解为"前人验证好的工作流"。你可以在 ~/.claude/skills/ 目录下创建技能文件，修改后立刻生效，无需重启。这样团队成员可以共享经过验证的最佳实践。

💡 以上只是 Claude Code 能力的冰山一角。更多玩法（自定义 Slash 命令、Git 集成工作流、多文件批量重构、子代理、插件系统等）会在后续文章中持续更新。

八、总结

回顾一下，整个接入过程只有三步：

1. 注册 claudeapi.com，充值并创建 API Key。

2. 安装 Claude Code（推荐原生安装）：

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

3. 配置两个变量（推荐写入 ~/.claude/settings.json）：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai"
  }
}

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
    "ANTHROPIC_BASE_URL": "https://code0.ai"
  }
}

配置完成，打开终端输入 claude 就能开始用了。

遇到问题？ → 查看本文第六章：常见报错与排查，覆盖了 7 个最高频的错误场景。 → 使用 /doctor 自动诊断。 → 更多问题可访问 FAQ 页面或点击右侧联系客服给你解决。

想接入其他工具？ claudeapi.com 同样支持 Cursor、Cline、Cherry Studio 等主流 AI 编程工具，配置方式大同小异。完整列表见软件接入教程目录。

还没注册？