Claude Code 是 Anthropic 推出的代理式（agentic）程式工具，你用一句話描述要做的事，它會自己讀檔案、改檔案、執行指令，然後把結果交回來。這篇 Claude Code 教學把整件事壓成三步：裝好、登入、跑完第一個真的會動到檔案的任務。全程大約 10 到 20 分鐘，其中大半時間在等下載。
先講兩個最常卡住人的前提。第一，免費 Claude 帳號不能用 Claude Code，官方文件寫得很直接：需要 Pro、Max、Team 或 Enterprise 訂閱，或是 Claude Console 的 API 額度。第二，它預設跑在終端機裡——Windows 的 PowerShell、macOS 的「終端機」App。如果光看到黑底白字就想關掉，文章後段有完全不碰終端機的桌面版路線。
沒有工程背景也能完成安裝。整個過程只需要複製一行指令、貼上、按 Enter。真正需要判斷的只有兩個地方：確認自己開的是哪一種終端機視窗，以及第一個任務要不要讓它直接改檔案。下面每一步都會標出「畫面上應該出現什麼」，對得上就往下走，對不上就跳到後面的錯誤訊息對照表。
開始之前：確認你的電腦和帳號過關
Claude Code 的官方系統需求不高，但有幾條是硬門檻，尤其是 32 位元 Windows 直接不支援。
| 項目 | 需求 |
|---|---|
| 作業系統 | macOS 13.0 以上、Windows 10 1809 以上（或 Windows Server 2019 以上）、Ubuntu 20.04 以上、Debian 10 以上、Alpine Linux 3.19 以上 |
| 硬體 | 4 GB 以上 RAM，x64 或 ARM64 處理器 |
| Shell | Bash、Zsh、PowerShell 或 CMD 任一種 |
| 網路 | 需要連網，並位於 Anthropic 支援的國家 |
| 帳號 | Claude Pro、Max、Team、Enterprise 訂閱，或 Claude Console（預付額度） |
特別提醒 Linux 使用者：在小型 VPS 上安裝需要大約 512 MB 的空閒記憶體，不夠的話安裝會被系統的 OOM killer 中止，畫面只會冒出一個 Killed。
第一步：安裝 Claude Code
官方推薦「原生安裝器」（Native Install），因為它會在背景自動更新。其他管道（Homebrew、WinGet、apt、npm）都要自己手動升級。
Windows：用 PowerShell 裝
- 按 Win + X，選「Windows PowerShell」或「終端機」。注意不要選到名字後面有 (x86) 的那個，那是 32 位元視窗，會直接報錯。
- 確認你開對了視窗：PowerShell 的每一行開頭是 PS C:\Users\你的名字>，CMD 則是沒有 PS 的 C:\Users\你的名字>。這兩者指令不通用，是新手最常踩的第一個坑。
- 貼上這行，按 Enter：irm https://claude.ai/install.ps1 | iex
- 畫面會跑一陣子文字，最後出現 Claude Code successfully installed! 就完成了。
如果你堅持用 CMD，指令是：curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
關於 Git for Windows：官方文件把它列為選配，不是必要條件。裝了它，Claude Code 會透過 Git Bash 使用 Bash 工具；沒裝，就改用 PowerShell 工具執行指令，兩種都能跑。如果你之後會碰到 Bash 腳本，裝了比較省事，安裝時記得在「Adjusting your PATH environment」那頁保持預設選項。
macOS 與 Linux：一行 curl
- macOS 按 Cmd + 空白鍵 打開 Spotlight，輸入 Terminal 後按 Enter；多數 Linux 發行版按 Ctrl + Alt + T。
- 貼上這行（macOS 貼上是 Cmd + V，Linux 終端機通常是 Ctrl + Shift + V），按 Enter：curl -fsSL https://claude.ai/install.sh | bash
- 同樣等到出現安裝成功的訊息。
WSL 使用者請注意：要在 WSL 的終端機裡執行上面這行 Linux 指令，而不是在 PowerShell 裡。WSL 環境不需要另外裝 Git for Windows。
其他安裝方式：什麼時候該用
| 方式 | 指令 | 自動更新 | 適合誰 |
|---|---|---|---|
| 原生安裝器 | 如上 | 會，背景自動更新 | 絕大多數人，官方推薦 |
| Homebrew（macOS） | brew install –cask claude-code | 不會，要 brew upgrade claude-code | 習慣用 brew 管理全部軟體的人 |
| WinGet（Windows） | winget install Anthropic.ClaudeCode | 不會，要 winget upgrade Anthropic.ClaudeCode | 公司電腦統一用 WinGet 管軟體 |
| apt / dnf / apk | 需先加入官方簽章與套件庫 | 不會，隨系統升級流程 | Linux 伺服器、要驗簽章的環境 |
| npm | npm install -g @anthropic-ai/claude-code | 會（但可能因權限失敗） | 已有 Node.js 22 以上的開發者 |
兩個細節值得記下來。Homebrew 有兩個 cask：claude-code 走穩定 channel，版本大約落後一週但會跳過有重大問題的版本；claude-code@latest 則是一有新版就更新。另外 npm 安裝絕對不要加 sudo，官方明確警告這會造成權限問題與安全風險。
第二步：確認真的裝好了
不要直接跳去用，先花十秒驗證。在終端機輸入：
claude –version
正常會印出一組版本號加上括號，例如 2.1.211 (Claude Code)。如果出現 command not found: claude 或 ‘claude’ is not recognized，安裝其實可能成功了，只是系統找不到它——這是 PATH 問題，修法在後面的對照表。
還有一個更完整的健檢指令：
claude doctor
它不會開啟對話，只印出安裝狀態、設定檔有沒有寫錯、最近一次自動更新的結果，以及對應的修正建議。之後任何時候覺得「怪怪的」，先跑這個。
第三步：登入
在終端機輸入 claude 並按 Enter，第一次執行會引導你登入，預設會自動開啟瀏覽器完成驗證，回到終端機就登入好了，之後不需要重複登入。
三個實務上會遇到的狀況：
- 瀏覽器沒有自動開：在登入畫面按 c 可以複製 OAuth 網址，自己貼到瀏覽器。在 SSH 或窄視窗裡網址被折行沒法點的時候也用這招。
- 在 WSL2、SSH 或容器裡登入：瀏覽器通常開在另一台主機上，回呼接不到。登入後瀏覽器會顯示一組代碼，把它貼回終端機的提示欄即可。貼不進去的話，改用 claude auth login，它會從標準輸入讀取代碼。
- 你的環境設過 ANTHROPIC_API_KEY：Claude Code 會跳過瀏覽器登入，改成請你核准這把金鑰。這件事有個副作用——如果那是以前專案留下的舊金鑰，它會蓋掉你的訂閱，畫面可能出現「This organization has been disabled」。解法在對照表。
想切換帳號或重新驗證，在對話中輸入 /login；想確認目前是用哪一種身分在跑，輸入 /status。
第四步：跑完第一個任務
大部分教學到「輸入 claude 就完成了」就結束，但真正讓人有感的是第一次看它改檔案。這一節走完一個完整循環：進資料夾、先讀、再改、檢查、能回退。
1. 先決定在哪個資料夾開工
Claude Code 的工作範圍是你啟動它的那個資料夾。所以先切過去再啟動：
Windows：cd C:\Users\你的名字\Documents\my-project
macOS／Linux：cd ~/Documents/my-project
然後輸入 claude。啟動後畫面上方會顯示版本、目前使用的模型、以及工作目錄，確認那個路徑是你要的再開始。
沒有現成專案也沒關係。官方的新手指南直接示範了「從零開始」的用法，例如請它做一個網頁：make me a simple webpage that says hello world。做完後直接雙擊產生的 HTML 檔就能在瀏覽器打開。
2. 先讓它唯讀探索，不要第一句就叫它改東西
第一句話建議用問句，成本低又能確認它真的讀得到你的檔案。官方 quickstart 列了幾個範例，直接用中文問也可以：
- 這個專案在做什麼？（what does this project do?）
- 這個專案用了哪些技術？
- 主程式進入點在哪裡？
- 解釋一下資料夾結構
這一步還有個附帶好處：你可以從回答判斷它讀到的範圍對不對。它會自己按需要讀檔案，不需要你手動把檔案貼進去。
3. 再給一個會真的動到檔案的任務
接著換成寫入型任務。最小可行的版本是官方示範的那句：
add a hello world function to the main file
這時候會分成兩種情況。如果它先詢問你，畫面會出現選項，選 Yes 按 Enter 就會動手；如果它直接做了，代表你這個 session 起始在 auto 模式（下一節會解釋）。
比起 hello world，更能看出價值的是那種「本來要手動做二十分鐘」的雜事。官方新手指南就舉了一個不需要任何程式背景的例子：請它看過桌面上的截圖，依照圖片內容重新命名檔案。描述得越具體越好——與其說「修一下 bug」，不如說「登入頁面輸入錯密碼後會變成空白畫面，把這個修掉」。
4. 檢查結果，不滿意就回退
任務跑完別急著關掉，用這幾個動作收尾：
- /diff：看工作目錄裡實際改了什麼。
- 直接問「哪些檔案被改了？」，Git 操作在 Claude Code 裡是用講的，包括提交、開分支、看最近幾筆 commit。
- /rewind：把程式碼和對話一起回捲到某個檢查點。這是新手最該先學會的一個指令。
- Esc：它做到一半方向歪了，按 Esc 直接中斷，不用等它做完。
要離開，輸入 /exit 或在空提示列連按兩次 Ctrl + D。下次想接著上次聊，用 claude -c 繼續最近一次對話，或 claude -r 挑一個舊的回去。
第一次用一定要知道的介面規則
終端機裡不能用滑鼠點，這點對習慣圖形介面的人衝擊最大。下面兩張表是最低限度的操作字典。
在終端機輸入的指令（啟動用）
| 指令 | 作用 |
|---|---|
| claude | 開啟互動模式 |
| claude “任務描述” | 開啟互動模式並直接帶入第一個問題 |
| claude -p “問題” | 問完就結束，不進入對話 |
| claude -c | 接續這個目錄最近一次對話 |
| claude -r | 挑一個之前的對話接續 |
在對話裡輸入的斜線指令
| 指令 | 作用 |
|---|---|
| /help | 列出所有可用指令 |
| /clear | 清空對話重新開始 |
| /compact | 把對話摘要起來，騰出 context 空間 |
| /context | 用彩色格狀圖看 context 用到哪了，並給優化建議 |
| /status | 查看目前 session 狀態（會立刻執行，不打斷回應） |
| /usage（等同 /cost） | 查 token 用量與費用 |
| /rewind | 回捲程式碼與對話到檢查點 |
| /doctor | 環境健檢，並可協助修復 |
| /init | 自動產生專案的 CLAUDE.md |
| /model | 換模型並存成預設 |
| /permissions | 管理允許、詢問、拒絕的權限規則 |
四個快捷鍵：打 / 會列出可用指令、Tab 自動補全、↑ 叫出上一句、Shift + Tab 切換權限模式。斜線指令只有放在訊息最前面才會被認得。
權限模式：它什麼時候會先問你
這是新手最該搞懂、卻最少人寫清楚的一段。權限模式決定 Claude 在你這個 session 裡可以不問就做哪些事。
| 模式 | 不問就能做的事 | 適合場景 |
|---|---|---|
| default（手動） | 只能讀 | 每個動作都要自己看過、敏感專案 |
| acceptEdits | 讀取、改檔案、常見檔案操作（mkdir、mv、cp 等） | 你會逐步審查的程式碼迭代 |
| plan | 讀取，外加分類器核准過的指令 | 動手改之前先摸清專案 |
| auto | 全部，背景有安全檢查 | 長任務，減少一直被打斷 |
| dontAsk | 讀取與事先核准的工具，其餘會被拒絕 | 鎖死的 CI 與腳本 |
| bypassPermissions | 全部，沒有任何檢查 | 僅限隔離的容器與虛擬機 |
auto 模式的運作方式是：由另一個模型（分類器）在背景審查動作，取代你一個一個按同意。官方文件說明，Pro、Max、Team 方案在終端機與 VS Code 擴充功能中，內建起始模式就是 auto；Enterprise 方案或使用 Console API key 則起始於 default。
這裡有個對新手非常關鍵、但很容易漏掉的細節：剛安裝完或剛升級後的第一個 session，起始模式是 default，除非 Claude Code 來得及抓到功能旗標。換句話說，你照這篇裝完、第一次跑任務時，它很可能會每一步都問你——這是正常的，不是壞掉。往後的 session 才會切到 auto。
隨時按 Shift + Tab 可以切換目前 session 的模式。bypassPermissions 不要在自己的主力電腦上用，官方定位是「僅限隔離環境」。
裝不起來？照錯誤訊息查修法
安裝階段失敗的原因九成是「複製到別種系統的指令」或「PATH 沒設好」。這張表把官方排錯文件裡最常見的錯誤訊息整理成對照，直接搜尋你畫面上那串字。
| 畫面上的訊息 | 真正原因 | 怎麼修 |
|---|---|---|
| ‘irm’ is not recognized | 你在 CMD，不是 PowerShell | 改開 PowerShell 跑原指令，或在 CMD 用 install.cmd 那一版 |
| The token ‘&&’ is not a valid statement separator | 你在 PowerShell 卻貼了 CMD 的指令 | 改用 irm https://claude.ai/install.ps1 | iex |
| A parameter cannot be found that matches parameter name ‘fsSL’ | 在 PowerShell 貼了 macOS／Linux 的 curl 指令（curl 在此是別名） | 改用 PowerShell 版安裝指令 |
| ‘bash’ is not recognized | 在 Windows 跑了 macOS／Linux 安裝指令 | 改用 PowerShell 版安裝指令 |
| 畫面印出一大段腳本文字，什麼也沒裝 | 只跑了「下載」那半段，少了執行的部分 | PowerShell 要接 | iex；CMD 要加 -o install.cmd 並執行它 |
| command not found: claude／’claude’ is not recognized | 裝好了，但安裝目錄不在 PATH | macOS／Linux 把 $HOME/.local/bin 加進 ~/.zshrc 或 ~/.bashrc；Windows 用 PowerShell 把 %USERPROFILE%\.local\bin 加進使用者 PATH，然後開新視窗 |
| syntax error near unexpected token ‘<‘ 或跑出 HTML | 安裝網址回傳了網頁而非腳本 | 若顯示 App unavailable in region，代表所在國家不支援；否則重試，或改用 Homebrew 安裝 |
| Could not create SSL/TLS secure channel | 較舊的 Windows 10 預設協定太舊 | 先執行一行把 SecurityProtocol 設為 Tls12，再重跑安裝 |
| Claude Code does not support 32-bit Windows | 你開到了「Windows PowerShell (x86)」 | 關掉，改開沒有 (x86) 的那一個 |
| The process cannot access the file（Windows 安裝時） | 下載資料夾被前一次安裝或防毒佔用 | 刪除 %USERPROFILE%\.claude\downloads 後重跑安裝 |
| 打 claude 卻開啟了桌面 App（Windows） | 舊版 Claude Desktop 在 WindowsApps 註冊的 Claude.exe 搶走 PATH 優先權 | 把 Claude Desktop 更新到最新版 |
| Claude Code on Windows requires either Git for Windows (for bash) or PowerShell | 兩種 shell 都找不到 | 把 powershell.exe 的預設路徑加回 PATH，或安裝 Git for Windows |
| running scripts is disabled on this system | PowerShell 執行原則擋住 npm 產生的 .ps1 啟動器 | 把執行原則改成 RemoteSigned（僅目前使用者），或乾脆改用原生安裝器 |
| API Error: 403 forbidden（登入後） | 訂閱失效、Console 角色不足，或公司 proxy 擋住 | 確認訂閱狀態；Console 使用者請管理員給 Claude Code 或 Developer 角色 |
| This organization has been disabled（明明有訂閱） | 環境變數 ANTHROPIC_API_KEY 蓋掉了訂閱憑證 | 取消該環境變數並從 shell 設定檔移除，再重新執行 claude |
| OAuth error: Invalid code | 登入代碼過期或複製不完整 | 重試並盡快完成；瀏覽器沒開就按 c 複製網址 |
| Killed（Linux，離開碼 137） | 記憶體不足，安裝約需 512 MB 空閒記憶體 | 加 swap、關掉其他程序，或換較大的機器 |
還有一個容易誤會的情況：只裝了 VS Code 擴充功能的人，終端機是找不到 claude 指令的。擴充功能自帶一份私有的 CLI 給它自己的聊天面板用，不會放進 PATH，要在終端機用就得另外跑一次獨立安裝。
完全不想碰終端機？桌面版與其他介面
Claude Code 不是只有 CLI 一種形態。如果終端機是你的主要阻力，可以直接跳過它。
| 介面 | 特點 | 適合誰 |
|---|---|---|
| 桌面 App（macOS／Windows／Linux beta） | 圖形介面，內建終端機、檔案編輯器、視覺化 diff 檢視、平行 session、排程任務 | 完全不想打指令的人 |
| VS Code／JetBrains 擴充功能 | 在既有編輯器裡直接用 | 已經在用這些 IDE 的人 |
| 網頁版（claude.ai/code） | 雲端 session，關掉視窗也會繼續跑 | 想跑長任務、或換機器接續 |
| GitHub Actions／GitLab CI | 接進 CI/CD 流程自動執行 | 團隊自動化 |
桌面 App 本身就含 Claude Code，不需要另外裝 Node.js 或 CLI。打開後切到 Code 分頁，選 Local 與一個資料夾，就能開始下任務；它也支援把 session 跑在 Cloud、透過 SSH 連遠端機器，或在 Windows 上跑進 WSL 2。如果點 Code 分頁時被要求升級，代表帳號還在免費方案。
桌面版的權限模式選單和 CLI 對應：Manual 是每個改動都等你按同意、Accept edits 自動接受檔案編輯、Auto 由分類器背景把關、Plan 只提方案不動檔案。想在動大手術前先看計畫，Plan 模式是最保險的起手式。
要花多少錢
Claude Code 沒有獨立售價，它綁在 Claude 的訂閱方案裡。以下是官方定價頁列出的數字。
| 方案 | 價格 | 是否含 Claude Code |
|---|---|---|
| Free | 0 美元 | 不含 |
| Pro | 年繳每月 17 美元／月繳每月 20 美元 | 含 |
| Max | 每月 100 美元起（僅月繳），可選 5 倍或 20 倍用量 | 含 |
| Team 標準席次 | 年繳每席 20 美元／月繳每席 25 美元 | 含 |
| Team 進階席次 | 年繳每席 100 美元／月繳每席 125 美元 | 含，用量為標準席次的 5 倍 |
| Enterprise | 每席 20 美元加上 API 費率的用量費，年繳 | 含 |
有一件事新手常忽略：Claude 聊天和 Claude Code 共用同一組用量限制，官方支援文件寫明兩邊的活動都算在同一份額度上。所以白天在網頁版聊掉的量，晚上寫程式時是會感覺到的。想知道還剩多少，在對話裡輸入 /status。
另一條路是用 Claude Console 的 API 額度計費，按 token 付費，第一次登入時 Console 會自動建立一個「Claude Code」workspace 方便集中追蹤成本。如果你的顧慮是把程式碼送上雲端，那其實是另一個題目——可以參考地端模型完整指南裡關於本機跑 LLM 的硬體取捨。
讓下一次更順：CLAUDE.md
Claude Code 每次開新 session 都是空白的 context。如果你每次都要重講一次「這個專案用 pnpm 不是 npm」「測試指令是什麼」，那就該寫進 CLAUDE.md。
最快的做法是在對話裡輸入 /init，它會分析專案、自動產生一份含建置指令、測試方式、專案慣例的 CLAUDE.md。已經有這個檔案的話，/init 會提出改進建議而不是直接覆蓋。
放置位置有不同作用範圍：
- ./CLAUDE.md 或 ./.claude/CLAUDE.md：專案層級，會跟著版本控制分享給團隊。
- ~/.claude/CLAUDE.md：個人層級，所有專案都套用，適合放你自己的偏好。
- ./CLAUDE.local.md：只給自己的專案偏好，記得加進 .gitignore。
官方建議單一檔案控制在 200 行以內，太長會吃掉 context 也會降低遵循度。寫法上要具體到可驗證：「使用 2 個空格縮排」比「格式要整齊」有效，「commit 前執行 npm test」比「記得測試」有效。想確認檔案有沒有被讀進去，在 session 裡跑 /context，看 Memory files 那一欄。
值得一提的是，Claude Code 還有一套自動記憶機制，會把你的糾正與偏好寫成筆記存在本機，每次對話載入索引。想看它記了什麼，輸入 /memory，那些都是可以直接編輯或刪掉的純 markdown。
接下來可以往哪走
跑完第一個任務之後，幾個自然的下一步：用 plan 模式在大改動前先看計畫、用 /rewind 大膽嘗試再回退、把重複性的流程寫成 skill。如果你的興趣是把 AI 串進更大的工作流程，n8n webhook 教學示範了怎麼用一個網址觸發自動化；想比較不同型態的 AI 助理各自的定位，可以看Hermes Agent 的拆解。
常見問題
不會寫程式可以用 Claude Code 嗎？
可以。官方的終端機新手指南明講「你不需要會寫程式，用日常語言描述想要什麼，Claude 會幫你寫」，並示範了做一個網頁、依內容重新命名桌面截圖、討論一個記帳工具該怎麼規劃這類任務。但終端機的基本操作還是要熟悉一點：不能用滑鼠點、用方向鍵移動、Esc 中斷、Ctrl + D 兩次離開。真的排斥終端機就用桌面 App。
免費帳號可以用嗎？
不行。官方文件寫明免費 Claude.ai 方案不包含 Claude Code 存取權，需要 Pro、Max、Team、Enterprise 訂閱，或 Claude Console 帳號，也可以透過 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 等企業雲端供應商使用。在桌面 App 點 Code 分頁時被要求升級，就是這個原因。
Windows 一定要先裝 WSL 或 Git for Windows 嗎？
都不用。原生 Windows 可以直接安裝，Git for Windows 是選配——裝了會啟用 Bash 工具，沒裝則改用 PowerShell 工具。要不要用 WSL 取決於你的專案在哪：專案是 Windows 原生的就用原生；需要 Linux 工具鏈、或想要沙箱化的指令執行環境，官方文件指出只有 WSL 2 支援 sandboxing。
它會不會亂改到不該改的檔案？
可控。預設狀態下改檔案前會問你，你可以用 Shift + Tab 隨時把 session 切回 default（每個動作都問）或 plan 模式（只提方案不動檔案）。真的改壞了用 /rewind 把程式碼和對話一起回捲到檢查點。最穩的做法還是老方法：在有 Git 版本控制的資料夾裡動手，改動隨時可以比對還原。至於 bypassPermissions 這種完全跳過檢查的模式，官方的定位就是只給隔離的容器與虛擬機用。
之後怎麼更新或移除？
原生安裝版會在啟動時與執行期間自動檢查更新，背景下載安裝，下次啟動生效；想立刻更新就跑 claude update，跑 claude doctor 可以看最近一次更新的結果。Homebrew、WinGet、apt 這些管道要自己下升級指令。移除的話，原生安裝在 macOS／Linux 是刪掉 ~/.local/bin/claude 與 ~/.local/share/claude，Windows 則是刪掉使用者資料夾底下對應的 .local\bin\claude.exe 與 .local\share\claude；設定檔另外存在 ~/.claude 與 ~/.claude.json，刪掉會一併清空所有設定、權限規則與對話紀錄。