返回指南
设置·2026年9月5日·更新于 2026年10月3日·阅读约 7 分钟

安装 Claude Code —— 一条命令，以及之后会卡住的两个地方

安装本身只需一条命令。要运行起来，还要通过两个关卡——npm 全局安装权限和登录阶段的支付。

Claude Code 的安装本身只需一行命令，真正容易卡住的是后面的步骤。大多数介绍安装的文章到「安装完成」就结束了，但在韩国从安装到实际运行还要经过两个关卡——全局安装权限和登录与支付。本文按顺序整理这三个步骤，以及每一步卡住时的解决方法。

第 1 步——安装（一行命令）

前置条件只有一个：Node.js 18 或更高版本。macOS、Windows（WSL）和 Linux 都使用相同的命令。

# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version

# 설치
npm install -g @anthropic-ai/claude-code

# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --version

claude --version输出此版本后，安装就完成了。如果停在这里，说明属于下面两个小节之一。

第 2 步——权限与路径错误

安装阶段最常见的两种错误。

症状原因与解决方法
EACCES权限错误没有 npm 全局目录的写入权限——将全局路径移到主目录
command not found: claudenpm 全局 bin 不在 PATH 中——添加到 PATH，然后重新打开终端

不建议在 EACCES 后附加 sudo。虽然当下可以安装成功，但之后每次更新都会重复遇到同样的问题，而且全局目录的所有者会变成 root，问题会更加复杂。将路径移到主目录更简洁。

# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

如果使用 Windows，请在 WSL 中安装。项目文件也应放在 WSL 文件系统中，这样文件监视和路径处理才能正常工作。

第 3 步——登录与支付（韩国实际最容易卡住的地方）

安装完成后运行 claude，系统会要求登录。这是韩国用户最常卡住的步骤，原因与安装无关。

  • 被禁止境外支付的银行卡——订阅支付会失败。在发卡行应用或网站中启用境外支付后，大多数情况下即可解决。
  • KakaoPay·Toss——不支持 claude.ai 网页支付（仅存在于移动应用订阅的商店支付方式中）。如果期待使用韩国本地的快捷支付，会在这一步卡住。
  • 如果没有支持境外支付的银行卡，就无法使用网页订阅路径。下面的密钥认证方式会先为 Kunavo 余额充值；当支付页面显示韩元时，会提供 KakaoPay、Naver Pay、PAYCO、Samsung Pay 和韩国国内银行卡（未开通境外支付的银行卡）作为付款方式，因此无需支持境外支付的银行卡也能充值（不支持 Toss）。

不同支付方式哪些可用、哪些不可用，已整理在 Claude 支付方式 中。

订阅支付受阻时——保持现有安装，通过密钥运行

Claude Code 除订阅登录外，还支持 API 密钥认证。设置下面两个环境变量后，无需经过登录页面即可运行；删除变量后会恢复原状。不需要重新安装。

~/.zshrc
# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

claude

此路径按实际使用的令牌量计费，而不是按月收费，因此没有工作的月份不会产生费用。密钥申请流程见 申请 Claude API 密钥；订阅和按量付费哪种更便宜，见 Claude Code 价格。

安装后的首次运行——3 分钟验证

运行后，在项目目录中启动 claude，并运行一次 /init。它会读取代码库并创建 CLAUDE.md，之后会在所有会话中自动读取。从这里开始的使用方式——编写规则、设置权限、自定义命令——请参阅 Claude Code 使用方法。

运行后出现的错误（401·429·529）与安装阶段的原因完全不同。区分方法已单独整理在 Claude Code 错误汇总 中。

常见问题

如何安装 Claude Code？

只需运行一行 npm 全局安装命令。执行 npm install -g @anthropic-ai/claude-code 后，用 claude --version 进行确认。唯一的前置条件是 Node.js 18 或更高版本；macOS、Windows 和 Linux 使用相同命令。在 Windows 上，建议在 WSL 中安装，这样遇到的问题更少。

已安装但无法运行。需要检查什么？

首先确认是否能输出 claude --version。如果能输出，说明安装已完成，剩下的是认证问题。如果提示找不到命令，通常是 npm 全局路径不在 PATH 中；将 npm config get prefix 输出路径下的 bin 添加到 PATH，然后重新打开终端即可解决。

安装时出现 EACCES 权限错误。

这表示你没有向 npm 全局目录写入的权限。使用 sudo 安装虽然暂时可行，但之后会反复出现权限问题，因此不建议这样做。更安全的方式是使用 npm config set prefix ~/.npm-global 将全局路径移到主目录，并将其添加到 PATH。

安装后在登录步骤中支付失败。

这是韩国最常见的受阻点。被禁止境外支付的银行卡会导致订阅付款失败；在发卡行应用或网站中启用境外支付后，大多数问题都能解决。claude.ai 网页付款不支持 KakaoPay 和 Toss，它们仅出现在用于移动应用订阅的 App Store·Google Play 韩国付款方式列表中。如果需要绕过付款限制，可以改用 API 密钥进行身份验证。通过此路径充值 Kunavo 余额时，当支付页面显示韩元，会提供 KakaoPay、Naver Pay、PAYCO、Samsung Pay 和韩国国内银行卡作为付款方式（不支持 Toss）。

不订阅也能使用 Claude Code 吗？

可以。除订阅登录外，Claude Code 还支持 API 密钥认证；设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 这两个环境变量后，无需登录即可运行。此时按实际使用的令牌量计费，而不是按月收费；没有使用的月份不会产生费用。

如何在 Windows 上安装？

建议在 WSL（Windows Subsystem for Linux）中安装。在 WSL 终端中安装 Node.js 18 或更高版本，然后运行相同的 npm 命令即可。此时要操作的项目也应放在 WSL 文件系统中，这样文件监视和路径处理才能正常工作。