Agentic Research
EN
首頁/工具/安裝 Claude Code：終端機 Agent 的上手路線

安裝 Claude Code：終端機 Agent 的上手路線

2026/09/3019 分鐘Bryan Chan最後更新 2026/09/30
這篇屬於工具主題Claude CodeCLI安裝教學

做完這篇你會得到：一個能在 Terminal（終端機） 裡跑起來的 Claude Code、一個完成登入的帳號、以及你親眼看過的一次「它要求你核准、然後改掉一個檔案」的完整流程。你也會搞清楚它的權限模式怎麼切，因為這是新手最容易在不知情下開太大的地方。

動手做完大約 15 分鐘。它是一個 CLI（命令列介面） 工具，沒有圖形介面，全程都在終端機裡完成。

適用平台

官方 Advanced setup 文件列出的系統需求：

項目需求
作業系統macOS 13.0+；Windows 10 1809+ 或 Windows Server 2019+；Ubuntu 20.04+；Debian 10+；Alpine Linux 3.19+
硬體4 GB 以上記憶體，x64 或 ARM64 處理器
網路需要連線
ShellBash、Zsh、PowerShell 或 CMD
帳號Claude Pro、Max、Team、Enterprise，或 Claude Console（API 預付額度）。官方明講：免費的 claude.ai 方案不含 Claude Code

Windows 有兩條路：原生 Windows（不支援沙箱，建議另外裝 Git for Windows 才能用 Bash 工具，否則它改用 PowerShell 工具），或 WSL 2（支援沙箱）。

來源：code.claude.com/docs/en/setup、code.claude.com/docs/en/quickstart、code.claude.com/docs/en/permission-modes。

前置需求

  • 一個上面表格裡列的付費帳號。這是硬門檻，安裝成功但登入不了是最常見的卡點。
  • 你會打開終端機、貼指令、按 Enter，也認得命令提示字元。不確定就先讀 Terminal、Shell、CLI：三個詞的差別。
  • 一個專案目錄。Claude Code 是以「你當前所在的目錄」為工作範圍的，所以要先 cd 進去。
  • 若你要用 API key 而不是訂閱帳號登入：先讀 API Key 與 環境變數與 .env。範例中的金鑰一律是 sk-xxxxxxxx 這種佔位符。不要把金鑰貼進對話視窗，也不要 commit 進 git。

步驟

步驟一：確認系統與帳號都在門檻以上

macOS 使用者點左上角蘋果選單 →「關於這台 Mac」看版本號；Windows 在設定 → 系統 → 關於看版本；Linux 在終端機執行：

cat /etc/os-release

預期輸出：Linux 會印出發行版名稱與版本號，例如 PRETTY_NAME="Ubuntu 22.04.3 LTS" 這種形式的一行。macOS 與 Windows 則是在視窗裡看到版本號。同時你必須能回答「我的 Claude 帳號是哪個方案」—— 如果答案是免費方案，先升級或改用 Console，否則後面第五步會卡住。

步驟二：安裝

官方推薦的原生安裝（macOS、Linux、WSL）：

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

Windows PowerShell：

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

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

其他官方路線：Homebrew 用 brew install --cask claude-code（stable 通道，另有 claude-code@latest）；Windows 用 winget install Anthropic.ClaudeCode；已裝 Node.js 22 以上的人也可以用 npm：

npm install -g @anthropic-ai/claude-code

官方對 npm 路線有兩個明確提醒：不要用 sudo npm install -g（會帶來權限與安全問題）；Node 版本低於 22 時 npm 會印 EBADENGINE 警告但不會失敗，因為這個套件裝的是原生二進位檔，執行時不用你的 Node。

預期輸出：原生安裝腳本會印出下載與安裝進度，結束後把提示字元還給你；官方說這時要開一個新的終端機視窗再往下走。npm 路線結尾會印出它新增了幾個套件。原生安裝之後會在背景自動更新；Homebrew、WinGet、npm 與 Linux 套件管理器安裝則不會，要自己升級（npm 的正確升級指令是 npm install -g @anthropic-ai/claude-code@latest，官方特別說不要用 npm update -g）。

失敗長這樣：syntax error near unexpected token '<'、403、或其他 curl 錯誤 —— 官方有一份 troubleshoot-install 文件專門對照這些訊息與修法。

步驟三：驗證安裝

在新的終端機視窗執行：

claude --version

預期輸出：一個版本號後面接著 (Claude Code)，官方文件給的例子是 2.1.211 (Claude Code)。你看到的數字會依當下的發行版本而不同，形狀一樣就算成功。

失敗長這樣：command not found（或 Windows 的「不是內部或外部命令」）代表安裝目錄不在 PATH 與路徑 上，官方的 troubleshoot-install 文件有「Fix your PATH」一節。另外兩個官方點名的迷糊情況：看到 The token '&&' is not a valid statement separator 代表你在 PowerShell 裡貼了 CMD 的指令；看到 'irm' is not recognized as an internal or external command 代表你在 CMD 裡貼了 PowerShell 的指令。判別方式很簡單：PowerShell 的提示字元是 PS C:\ 開頭，CMD 是 C:\ 沒有 PS。

步驟四：進入專案並啟動

cd /path/to/your/project
claude

把 /path/to/your/project 換成你的實際路徑。

預期輸出：終端機被一個互動式介面接管。官方 Quickstart 說明畫面上會顯示版本、目前模型與工作目錄，下面是輸入提示。打 /help 會列出可用指令，/resume 可以接回先前的對話。第一次啟動會先要求登入（下一步）。

步驟五：登入

在剛啟動的 session 裡照畫面指示登入：它會帶你去瀏覽器完成授權。如果你已經設了 ANTHROPIC_API_KEY 這個 環境變數與 .env，官方說明 Claude Code 會跳過瀏覽器登入，改成要求你核准一次這把金鑰。之後要換帳號或重新登入，在 session 裡打：

/login

預期輸出：瀏覽器打開授權頁，你確認後回到終端機，session 正常開始。官方說明登入一次之後憑證會被存下來，之後不用再登。用 Console 帳號第一次登入時，Console 裡會自動建立一個名為「Claude Code」的 workspace 用來集中看成本。

失敗長這樣：瀏覽器沒開 —— 手動複製終端機上印出的網址。一直停在登入畫面 —— 確認你的方案確實在官方清單裡（免費 claude.ai 方案不行）。

步驟六：問第一個問題

在輸入提示打一句話，例如官方 Quickstart 用的：

what does this project do?

預期輸出：它會開始讀你的專案檔案（畫面上看得到它在讀哪些檔），然後給一段總結。官方說明它會依需要自己讀檔，你不需要手動把檔案加進脈絡。也可以問更具體的：where is the main entry point?、explain the folder structure。

步驟七：做第一個改動，並看懂權限模式

先要求一個小改動：

add a hello world function to the main file

預期輸出：它找到該改的檔案並顯示變更內容；如果它問你要不要套用，選 Yes 核准，檔案才會被改。

接著搞懂你剛剛看到的那個「問不問你」的開關。官方把它叫做權限模式，六種的差別是「哪些動作不用問你」：

模式不用問你就能做的事
default（介面顯示 Manual）只有讀取
acceptEdits讀取、檔案編輯，以及 mkdir／touch／mv／cp 等常見檔案系統命令
plan讀取，加上先研究再給計畫；不改程式碼
auto全部，但由背景的分類器模型逐項檢查安全性
dontAsk讀取與你事先核准的工具；其他該問你的一律直接拒絕
bypassPermissions全部，且不做檢查。官方警告：只用在容器、VM 這類隔離環境

切換方式有兩種。session 中按 Shift+Tab 循環，狀態列會顯示目前模式，官方列出的字樣包含 ⏸ manual mode on、⏵⏵ accept edits on、⏸ plan mode on、⏵⏵ auto mode on、⏵⏵ bypass permissions on。啟動時直接指定：

claude --permission-mode plan

預期輸出：按 Shift+Tab 每按一次，狀態列上那行模式文字就換一個；用旗標啟動時，session 一開始就顯示你指定的模式。新手建議從 plan 或 default 開始 —— 先讓它讀、給計畫，你看過再放行。

官方還說明了預設值：v2.1.283 之後，互動式終端機 session 的內建起始模式是 auto（更早的版本只在 Pro、Max、Team 方案上是 auto，其餘為 Manual）。要固定成 Manual，把下面這段寫進 ~/.claude/settings.json：

{
  "permissions": {
    "defaultMode": "default"
  }
}

步驟八：離開、回來、與一次性模式

官方 Quickstart 列的 shell 指令對照：

claude "fix the build error"   # 啟動互動模式並直接帶入第一個任務
claude -p "explain this function"   # 跑一次性查詢，印完結果就結束
claude -c                       # 接回這個目錄最近一次的對話
claude -r                       # 從清單裡挑一個先前對話接回

session 內部的指令：/clear 清掉對話歷史，/help 列出指令，/exit（或按兩次 Ctrl+D）離開。

預期輸出：/exit 之後你會回到一般的 shell 提示字元；claude -p 會在終端機印出回答然後自己結束，適合放進腳本；claude -c 會把上次的對話內容載回來，你看得見先前的訊息。

怎麼確認你裝對了

除了 claude --version，官方提供一個更完整的健檢指令：

claude doctor

預期輸出：一份唯讀的安裝與設定診斷報告，官方說明它包含安裝健康狀態、設定檔的驗證錯誤、以及每條警告與建議修法 —— 而且它不會啟動 session，印完就結束、把提示字元還給你。看到沒有錯誤項，就代表安裝、設定檔與更新機制都正常。

claude doctor 同時也會告訴你最近一次背景自動更新的結果，所以它也是「我的版本到底有沒有在更新」這個問題的答案。

常見錯誤與修法

症狀原因修法
command not found: claude安裝目錄不在 PATH 上開一個新終端機再試；仍不行就照官方 troubleshoot-install 的「Fix your PATH」一節修
The token '&&' is not a valid statement separator你在 PowerShell 裡貼了 CMD 版安裝指令改用 PowerShell 版的 irm 指令，或改開 CMD
'irm' is not recognized as an internal or external command你在 CMD 裡貼了 PowerShell 版指令改開 PowerShell（提示字元以 PS 開頭）再貼
syntax error near unexpected token '<' 或 403安裝腳本下載失敗，拿到的不是腳本內容照官方 troubleshoot-install 的錯誤對照表處理，或改用 Homebrew／npm 路線
npm 安裝時報權限錯誤用了 sudo npm install -g，或 npm 全域目錄不可寫官方明確警告不要用 sudo；claude doctor 會列出可用的修法
裝好了但登入不了免費 claude.ai 方案不含 Claude Code改用 Pro／Max／Team／Enterprise 訂閱，或開 Console 帳號用預付額度
--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons你用 root 或 sudo 跑，又要它跳過所有權限檢查這是刻意的安全設計。改用一般使用者，並用官方的 dev container 設定（以非 root 執行）
它改了你不想被改的檔案起始權限模式比你以為的寬用 Shift+Tab 或 --permission-mode 改回 default／plan；注意官方說明 .git、.claude、.zshrc 等受保護路徑在任何模式下（除 bypassPermissions）都不會自動放行

下一步

同主題 · 其他形態

看主題地圖全部組合

同形態 · 其他主題

第一次呼叫 LLM API：Token、計費與常見錯誤安裝 OpenAI Codex CLI：登入、權限與第一個任務