安裝 Claude Code CLI：5 分鐘完成設定指南（2026）

該如何設定 Claude Code？ 先用原生安裝程式 curl -fsSL https://claude.ai/install.sh | bash 安裝 CLI，透過瀏覽器完成驗證，再於專案根目錄建立 CLAUDE.md，寫下技術堆疊細節與程式碼撰寫慣例。接著在 .claude/settings.json 中設定權限，並加上一個格式化掛鉤，讓每次編輯後自動修正風格。整套設定花不到五分鐘。 {.answer-block}

ServiceNow 已將 Claude Code 推行至超過 29,000 名員工¹，Allianz 也宣布結盟，讓全體員工在 2026 年初都能使用 Claude²。這條採用曲線反映出一個現象：開發者只要在自己的終端機裡試過代理式的程式設計方式，就不會再回頭從聊天視窗複製貼上。以下的操作流程會帶您從零開始，約莫五分鐘就跑通一次 Claude Code 工作階段，而且過程中產出的設定，之後都能繼續沿用。

摘要： 用原生安裝程式（curl -fsSL https://claude.ai/install.sh | bash）安裝 Claude Code，透過瀏覽器完成驗證，建立一份寫有專案脈絡的 CLAUDE.md，再到 .claude/settings.json 設定權限。加上一個 Prettier 掛鉤，每次編輯後檔案就會自動格式化。整個過程不到五分鐘，而且設定會跨工作階段持續生效。

重點整理

• 獨立開發者： CLAUDE.md 加上一個格式化掛鉤，就能涵蓋八成需求。先用預設權限起步，隨著信任累積，再逐步預先核准常用工具。
• 團隊負責人： 把 .claude/settings.json 提交進儲存庫，整個團隊就會共用同一份權限允許清單與掛鉤設定。
• 資安工程師： 權限模型⁴（Ask/Manual、允許清單、auto 模式的分類器、--dangerously-skip-permissions）與信任層級一一對應。Ask 模式下，每一次寫入、每一道指令都必須明確核准；不過自 2026 年 8 月 14 日起，Pro/Max/Team 的工作階段預設改為 auto 模式——若您的威脅模型要求每次核准都有人把關，請以 "defaultMode": "manual" 固定住。

事前準備

安裝 Claude Code 之前，您需要兩樣東西。

一組 Anthropic 帳號。 Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳號，免費的 Claude.ai 方案並不包含使用權³。訂閱方案本身就含 Claude Code 用量（截至 2026 年年中，Max 5x 為每月 100 美元，Max 20x 為每月 200 美元，兩者皆為個人層級）⁶；您也可以在 console.anthropic.com 取得 API 金鑰，依 token 計費。驗證會在安裝完成後於瀏覽器進行，因此現在還不必先複製任何東西。

一個終端機。 Claude Code 可以在任何終端機模擬器裡執行：Terminal.app、iTerm2、Windows Terminal、Alacritty，或 VS Code 的整合式終端機都行。建議終端機寬度至少 120 欄，因為 Claude Code 會顯示檔案差異與工具輸出，橫向空間愈充裕愈好讀。

建議的安裝方式不需要 Node.js。只有在您選擇下文的 npm 替代方案時才會用到，而截至 v2.1.198，該方案需要 Node.js 22 以上。

安裝

使用 Anthropic 建議的原生安裝程式來安裝 Claude Code³：

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

在 Windows 上，請改於 PowerShell 執行 irm https://claude.ai/install.ps1 | iex。安裝程式會把執行檔放在 ~/.local/bin/claude；原生安裝會在背景自動更新，不必手動升級也能保持最新。

確認安裝是否成功：

claude --version

標準輸出應該會印出版本號。若出現「command not found」錯誤，代表 ~/.local/bin 不在您的 PATH 裡。把它加進 shell 設定檔並重新載入：

# Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

想更深入診斷安裝與設定狀況，可以執行 claude doctor——它會檢查執行檔、PATH、自動更新狀態，並指出彼此衝突的安裝（例如原生版本旁邊殘留的 npm 全域副本）。

其他安裝方式。 若您偏好由套件管理員接手，Homebrew 也可行：brew install --cask claude-code（以 brew upgrade --cask claude-code 更新，或自 v2.1.129 起設定 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1，讓套件管理員在背景更新）。npm 套件目前仍可運作，但屬於舊有做法，自 v2.1.15 起已不建議使用——npm install -g @anthropic-ai/claude-code（需 Node.js 22 以上，切勿搭配 sudo⁷），而且它底層安裝的其實是同一份原生執行檔。若您當初從 npm 起步、想轉往建議的做法，請先安裝原生版本，再以 npm uninstall -g @anthropic-ai/claude-code 移除 npm 副本，以免版本衝突。

首次啟動時，Claude Code 會開啟瀏覽器進行 OAuth 驗證。登入並授權後，Claude Code 會把執行期的驗證狀態存在本機的 ~/.claude.json。另一種做法是在啟動前設定 ANTHROPIC_API_KEY 環境變數。無論採用哪一種，憑證都只留在您自己的機器上，而且僅用於驗證 API 請求。

第一次工作階段

切換到任一專案目錄後執行：

cd ~/Projects/my-app
claude

Claude Code 會啟動互動式的 REPL 工作階段，並在啟動時載入您的 CLAUDE.md 與各項設定。在新專案裡輸入第一道提示詞時，Claude 會自行探索所需的資訊：

1. 掃描目錄結構，了解專案的組成方式
2. 讀取設定檔，例如 package.json、pyproject.toml 或 Cargo.toml，藉此判斷技術堆疊
3. 套用專案根目錄的 CLAUDE.md 指示，這些內容在啟動時就已載入

不妨先下一道簡單的提示詞，確認一切正常：

> Explain the structure of this project

Claude 會讀取檔案、整理出架構，並在終端機裡回覆。您會即時看到每一次工具呼叫（讀取的每個檔案、執行的每道指令），而任何寫入動作之前都會先跳出權限請求。

第一次工作階段該注意什麼。 請留意兩件事：在每個動作前即時顯示的工具呼叫，以及權限提示。工具呼叫會揭露 Claude 如何在您的程式碼庫裡穿梭。您會發現它讀了一些自己原本想不到要看的檔案，而這些檔案往往能帶出有用的脈絡。權限提示則在任何內容寫進磁碟之前，清楚告訴您 Claude 打算改動什麼。若某項修改看起來不對，就拒絕它並補上說明。Claude 會在同一次工作階段中依您的回饋調整做法⁸。

設定 CLAUDE.md

CLAUDE.md 是用好 Claude Code 最重要的一個檔案。少了它，Claude 只能從檔案內容推斷技術堆疊，做出看似合理的猜測；有了它，Claude 從第一道提示詞起就完全遵循您的慣例。這個差別之所以要緊，是因為靠推斷得來的行為會逐漸偏移：Claude 可能在 ESM 專案裡使用 CommonJS、挑錯測試執行器，或忽略您的資料庫遷移流程。CLAUDE.md 正是用來消除這種偏移。

在專案根目錄建立這個檔案：

touch CLAUDE.md

以下是一份適用於 Python 專案、可直接上手的起始範本：

# My App

## Project Context
FastAPI backend with HTMX frontend. PostgreSQL database.

## Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0 (async)
- Frontend: HTMX + Alpine.js, Jinja2 templates
- Database: PostgreSQL 16, Alembic migrations
- Testing: pytest with pytest-asyncio

## Code Standards
- Type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async database operations only (no sync SQLAlchemy)

## Commands
- `source venv/bin/activate` before any Python command
- `uvicorn app.main:app --reload` starts the dev server
- `python -m pytest -v` runs the test suite
- `alembic upgrade head` applies database migrations

若是 JavaScript／TypeScript 專案，結構也大同小異：

# My App

## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit, Playwright for e2e

## Code Standards
- ESM imports only (no require())
- All API endpoints need input validation with Zod
- Tests required for new endpoints before merging

## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the test suite
- `npx prisma migrate dev` runs database migrations

CLAUDE.md 裡最有價值的段落，是那些能避免重蹈覆轍的內容。如果 Claude 老是用 require() 而不是 import，就在 Code Standards 加上「ESM imports only」。如果執行測試指令前必須先啟用虛擬環境，就把這個順序寫下來。Claude 在每次工作階段開始時都會讀取 CLAUDE.md，因此其中的每一行都會變成長期有效的指示，在成百上千次互動中不斷發揮作用。關於怎樣寫出真正有效的 CLAUDE.md，我在 AGENTS.md 模式一文中整理過，也在脈絡即架構裡談了背後更廣的原則。開放規格 AGENTS.md⁹ 為其他代理式工具採用了類似做法，但 CLAUDE.md 支援技能與規則目錄等更豐富的功能。

層級關係很關鍵。 CLAUDE.md 可以放在三個位置，Claude 會依照由廣泛到專屬的順序合併：

1. ~/.claude/CLAUDE.md：套用於所有專案的全域指示（您個人的程式撰寫偏好）
2. ./CLAUDE.md：專案層級的指示（提交進儲存庫，與團隊共用）
3. ./src/CLAUDE.md：目錄層級的指示（範圍限於 monorepo 中的某個模組或子系統）

真正該納入版本控制的是專案層級的 CLAUDE.md。使用 Claude Code 的團隊成員會自動沿用您訂下的慣例。

權限基礎

Claude Code 有三種權限層級⁴，決定代理擁有多大的自主空間。您選擇的層級掌握著一個根本取捨：自主度愈高，工作階段推進得愈快，但對改動的掌握度也愈低。

Ask 模式（自 v2.1.200 起在 CLI 中顯示為「Manual」）要求在每次寫入檔案、執行指令或進行破壞性動作之前先取得核准。您能清楚看見 Claude 打算做什麼，並逐步核准或拒絕。請注意預設值已於 2026 年 8 月 14 日改變：Pro、Max 與 Team 的工作階段現在以 auto 模式啟動，改由安全分類器審查每個動作，而不再逐次詢問您——按 Shift+Tab 可以切回 Manual，也可以在設定裡以 "defaultMode": "manual" 固定。我仍然建議從 Manual 開始，因為那些核准提示本身就在教您 Claude Code 的運作方式。用過幾次之後，您自然會培養出判斷力：哪些操作可以安心預先核准，哪些每次都值得細看。

允許清單權限讓您預先核准特定工具與樣式，免得 Claude 每次都要問。相關設定寫在專案的 .claude/settings.json 裡：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(python -m pytest:*)",
      "Bash(alembic upgrade head)"
    ]
  }
}

上面這份設定允許 Claude 讀取檔案、搜尋程式碼庫，並直接執行您的測試與遷移指令，全程不必詢問。但在寫入檔案或執行其他 bash 指令之前，它仍會先徵詢同意。請留意其中的規律：只把讀取類操作與已知安全的指令列入允許清單；寫入類操作留在 Ask 模式，因為您會想在內容寫進磁碟之前，先看過 Claude 寫了什麼。

危險地略過權限檢查（--dangerously-skip-permissions）會關閉確認提示（自 v2.1.126 起仍保留一道安全網：毀滅性的刪除指令依然會提示）。這個旗標只為 CI/CD 流程與無人值守的自動化工作而存在。在您重視的程式碼庫上進行互動式工作階段時，千萬別用它。

正因為有這套權限機制，Claude Code 才能安心用在真實專案上。這個推進順序是刻意安排的：先在 Ask 模式建立理解，把重複出現的操作加入允許清單，同時讓寫入類操作維持受控，確保改動落地前您都能先審過一遍。

您的第一個掛鉤

掛鉤是在 Claude Code 生命週期的特定時點執行的 shell 指令⁵。我寫過一篇完整的掛鉤教學，從零打造五個能用於正式環境的掛鉤；而關於打造自訂技能的文章，則談到更進一階的自動化。掛鉤解決的是以 LLM 為核心的工具的一個根本問題：模型大多數時候會遵守您的格式規範，但「大多數時候」意味著每十次檔案編輯就會混進一次風格不一致。模型提供的是機率式保證，掛鉤提供的則是確定性保證。格式化掛鉤會在每次寫入檔案之後執行格式化工具，次次如此，與模型當下的判斷無關。以下就是一個實用的入門掛鉤：在 Claude 編輯檔案後自動格式化。

在專案中建立或編輯 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

PostToolUse 掛鉤⁵會在每次 Edit 或 Write 工具呼叫之後觸發。Claude Code 會把 $FILE_PATH 設為被修改檔案的路徑。Prettier 就地完成格式化，而結尾的 || true 可確保在 Prettier 尚未安裝、或檔案類型不受支援時，非零的結束碼不會擋住 Claude⁵。

我還建議幾個實用的入門掛鉤：

• 針對 Bash 的 PreToolUse：擋下 rm -rf / 或 git push --force 這類危險指令
• SessionStart：把當前日期、目前的 git 分支或環境變數注入脈絡（SessionStart 掛鉤的標準輸出會進入 Claude 的脈絡）
• Stop：在 Claude 完成任務時自動執行測試套件

掛鉤能把 Claude Code 從一個對話式工具，變成一套受治理的開發環境。就算只挑一兩個合適的掛鉤，也能一舉消除整整一類錯誤。

出狀況的時候

使用 Claude Code 的第一週，有四種情況會一再出現。事先了解它們，能省下不少除錯時間。

Claude 無視您 CLAUDE.md 裡的指示。 最常見的原因是：在您動手修改之前，Claude 早已讀過該檔案並快取了理解。執行 /clear 重設脈絡，或直接開一次新的工作階段。Claude 只在工作階段開始時重新讀取 CLAUDE.md，而不是每道提示詞都讀一次。若換了新的工作階段仍然被忽略，請檢查是否有優先權更高的 CLAUDE.md（使用者層級的 ~/.claude/CLAUDE.md）與您的專案層級檔案互相衝突。

Claude 做了您沒核准的改動。 如果允許清單的樣式寫得太寬鬆（例如放了一條包山包海的 Bash 規則，而不是 Bash(python -m pytest:*) 這種窄前綴），Claude 就能不經詢問直接執行指令。請把允許清單的樣式收窄。最安全的做法是：只把讀取類操作與具名的特定指令列入允許清單。若 Claude 已經做出不想要的改動，git diff 會清楚顯示改了什麼，git checkout -- <file> 則可以還原。

長時間工作階段中，上下文視窗被塞滿。 上下文視窗逐漸填滿時，Claude Code 會壓縮較早的訊息（截至 2026 年年中，預設模型都具備 100 萬 token 的視窗，因此比從前難碰到上限得多），但壓縮有可能丟掉對話早期的重要細節。超過 30 分鐘的工作階段，建議定期提交手上的改動，再用 /clear 開一次新的工作階段。全新的脈絡會重新讀取 CLAUDE.md，從乾淨的狀態出發。我自己是每完成一個子任務就提交一次，如此一來既有回復點，也形成了自然的工作階段分界。

Claude 改錯檔案，或做了不必要的更動。 當 Claude 開始「改良」您根本沒要它碰的程式碼時，問題通常出在提示詞太模糊。與其說「把 auth 模組整理一下」，不如說「在 app/auth/handlers.py 中，把 verify_user 更名為 verify_user_credentials，並更新所有呼叫端」。愈具體，非預期的副作用就愈少。若不想要的編輯已經發生，git diff 會清楚顯示改動內容，而 git checkout -- <file> 能逐一還原檔案，不會賠上其他工作成果。

下一步

以上流程涵蓋了最要緊的部分：安裝、第一次工作階段、專案設定、權限，以及一個入門掛鉤。若想把 Claude Code 與其他代理式工具做個比較，請看 Claude Code 與 Codex 比較。若需要涵蓋全部五大核心系統（CLAUDE.md 層級、完整的權限模型、掛鉤架構、自訂斜線指令、多代理工作流程）的完整參考，請閱讀 Claude Code 完全指南。

那份指南談的是上下文視窗管理、子代理委派、技能自動啟用，以及每天使用 Claude Code 數個月之後才會浮現的那些模式。如果這份快速入門對您有幫助，完整指南就是自然的下一步。若想快速查閱每一道指令、每個旗標與每組快速鍵，請參閱 Claude Code 速查表。

如果您的專案是 iOS 或 macOS 應用程式，iOS 代理開發指南整理了 Apple 平台專屬的 Claude Code 做法：用於建置與模擬器的 XcodeBuildMCP 整合、保護 .pbxproj 不被代理改動的 Apple 開發掛鉤，以及涵蓋 App Intents、MCP 伺服器、Foundation Models 與框架層級代理平台串接的 Apple 生態系系列。

參考資料

常見問題

安裝 Claude Code 需要哪些條件？

您需要一組 Anthropic 帳號（Pro、Max、Team、Enterprise 或 Console——免費方案不含 Claude Code），以及任何一款終端機模擬器。Claude Code 可在 macOS 13 以上、Linux 與 Windows（原生或 WSL）執行。建議的安裝方式是原生安裝程式——curl -fsSL https://claude.ai/install.sh | bash——它不需要 Node.js、不需要 Docker，也不依賴其他執行環境。只有選擇 npm 替代方案（npm install -g @anthropic-ai/claude-code）時才需要 Node.js 22 以上。

CLAUDE.md 是什麼？為什麼需要它？

CLAUDE.md 是放在專案根目錄的一份 markdown 檔案，用來告訴 Claude Code 您的技術堆疊、程式撰寫慣例與常用指令。少了它，Claude 只能從檔案內容推斷專案設定並做出看似合理的猜測，而這些猜測會在不同工作階段之間逐漸偏移。有了 CLAUDE.md，Claude 每次工作階段都會從第一道提示詞起完全遵循您的慣例。它支援三層階層：使用者層級（~/.claude/CLAUDE.md）、專案層級（./CLAUDE.md）與目錄層級（./src/CLAUDE.md），並依由廣泛到專屬的順序合併。

Claude Code 的費用是多少？

Claude Code 支援兩種計費方式。API 用多少付多少的模式，依 Anthropic 標準 API 費率逐 token 計費⁶。一次典型的 30 到 60 分鐘工作階段，視程式碼庫規模與生成量而定，大約花費 0.50 至 3.00 美元。另一種是 Anthropic 的 Max 方案⁶（截至 2026 年年中，Max 5x 為每月 100 美元，Max 20x 為每月 200 美元，兩者皆為個人層級），其中已包含 Claude Code 用量，並提供更高的速率上限。您可以在 console.anthropic.com 查看 API 使用量。

可以在 VS Code 裡使用 Claude Code 嗎？

可以。Claude Code 能在任何終端機裡執行，包括 VS Code 的整合式終端機。在 VS Code 打開終端機面板，切換到專案目錄，然後像在獨立終端機那樣執行 claude 就行。Claude Code 直接讀寫磁碟上的檔案，因此改動會立刻反映在 VS Code 的編輯器分頁裡。這套流程不需要任何擴充套件；不過若您偏好整合式面板，也有專屬的 VS Code 擴充套件可用。有些開發者會在編輯器旁固定一個專供 Claude Code 使用的終端機分割視窗，邊改邊看非常順手。

在正式環境的程式碼庫上使用 Claude Code 安全嗎？

Claude Code 的 Ask 模式要求在每次寫入檔案、每次執行指令之前都取得明確核准。未經您確認，磁碟上不會有任何變化。這套權限機制，再搭配能擋下強制推送、破壞性 shell 指令等危險操作的掛鉤，讓 Claude Code 足以勝任正式環境的工作。我自己每天都在服務真實使用者的專案上使用 Claude Code。關鍵在於：從 Ask 模式起步，核准之前先弄清楚每次工具呼叫究竟做了什麼，然後只把您真正信任的操作逐步列入允許清單。最後一道安全網是版本控制：在開始任何重要的 Claude Code 工作階段之前先提交一次，這樣隨時都能還原。

新手最常犯的錯誤是什麼？

把本該寫進 CLAUDE.md 的內容，全部塞進提示詞裡。新手往往把整套程式撰寫規範貼進每一道提示詞，既浪費上下文視窗，也讓不同工作階段的結果參差不齊。把反覆用到的指示一次搬進 CLAUDE.md，提示詞則留給該次工作階段特有的需求。第二常見的錯誤，是把 Bash(*) 而非具體指令列入允許清單。萬用字元式的 Bash 允許清單，會讓 Claude 不必詢問就能執行任何 shell 指令，權限機制也就形同虛設。