返回指南
設定·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 後，系統會要求登入。這是韓國最常卡住的地方，原因與安裝無關。

  • 封鎖海外付款的卡片——會在訂閱付款時失敗。在發卡行 App 或網站中允許海外付款，通常即可解決。
  • Kakao Pay、Toss——不支援 claude.ai 網頁付款（只存在於行動 App 訂閱的商店付款方式中）。如果預期能使用韓國本地的簡易付款方式，會在這個步驟卡住。
  • 沒有可進行海外交易的卡片時——無法使用網頁訂閱路徑。下方的金鑰驗證方式會先為 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

此方式不是支付月費，而是依實際使用的 Token 計費，因此沒有工作的月份不會產生費用。金鑰申請流程請參閱取得 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。

安裝後在登入階段付款失敗。

這是韓國最常遇到的阻礙。遭封鎖海外交易的卡片會導致訂閱付款失敗；在發卡行應用程式或網站允許海外交易後，大多數情況即可解決。KakaoPay 和 Toss 不支援 claude.ai 網頁付款，但會列在用於行動應用程式訂閱的 App Store·Google Play 韓國付款方式清單中。如果需要繞過付款限制，可以改用 API 金鑰進行驗證。此路徑的 Kunavo 餘額儲值在付款頁面顯示韓元時，提供 KakaoPay·Naver Pay·PAYCO·Samsung Pay·國內卡片作為付款方式（不支援 Toss）。

不訂閱也能使用 Claude Code 嗎？

可以。Claude Code 除了訂閱登入，也支援 API 金鑰驗證；設定 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 這兩個環境變數後，就能不登入直接執行。此時不是支付月費，而是依使用的 Token 計費；沒有使用的月份不會產生費用。

如何在 Windows 上安裝？

建議在 WSL（Windows Subsystem for Linux）中安裝。在 WSL 終端機中安裝 Node.js 18 以上後，執行相同的 npm 指令即可。同時，您要操作的專案也必須放在 WSL 檔案系統中，檔案監控與路徑處理才能正常運作。