入門15 分鐘13 節

Claude Code 快速入門：安裝、登入同接入 PingAI

由認識 Claude Code 到裝好、登入、跑第一句對話，再教你用 ANTHROPIC_BASE_URL 接入 PingAI 呢類本地 / 第三方網關。

1. 認識 Claude Co…2. 安裝方式一：原生安裝（推…3. 安裝方式二：Homebr…4. 驗證安裝、更新與解除安裝 5. 登入認證：Claude …6. 第一次執行：啟動交互工作…7. 基礎交互一：用自然語言提…8. 基礎交互二：slash …9. Git 操作與常見工作流 10. 用 ANTHROPIC_…11. 設定 ANTHROPIC…12. 驗證網關連線與常見排錯 13. 進階設定：自訂請求頭、a…

1認識 Claude Code 與系統要求

Claude Code 是 Anthropic 官方的終端 AI 編程代理（CLI），可以直接讀取並修改本地程式庫、執行指令與 Git 操作。系統要求：

作業系統：macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
硬體：4GB+ 記憶體，x64 或 ARM64 處理器；需要連網
Shell：Bash、Zsh、PowerShell 或 CMD；且需在 Anthropic 支援的國家 / 地區使用
附加依賴：ripgrep 通常隨包內置；若搜尋失敗才需處理
用戶需具備 Pro / Max / Team / Enterprise 訂閱或 Claude Console（預付費 API）帳號；免費 Claude.ai 計劃不包含 Claude Code 存取權限

원문 읽기

2安裝方式一：原生安裝（推薦）

原生安裝會自動在背景更新到最新版本。三平台指令：

bash

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

Windows PowerShell：

powershell

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

Windows CMD：

batch

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

提示：看到「The token '&&' is not a valid statement separator」代表你其實在 PowerShell（提示符為 PS C:\）；看到「'irm' is not recognized」代表你在 CMD。原生 Windows 建議安裝 Git for Windows，讓 Claude Code 使用 Bash 工具，否則會退回以 PowerShell 作為 shell 工具；WSL 環境則不需要。

원문 읽기

3安裝方式二：Homebrew / WinGet / 套件管理器 / npm

Homebrew（macOS）：

bash

brew install --cask claude-code

claude-code 走 stable 通道（約慢一週、跳過有重大回歸的版本），claude-code@latest 走最新通道；Homebrew 不會自動更新，需手動 brew upgrade claude-code。

WinGet（Windows）：

powershell

winget install Anthropic.ClaudeCode

Linux 套件管理器（apt / dnf / apk，示例為 Debian/Ubuntu 的 stable 通道）：

bash

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code

npm（要求 Node.js 22+）：

bash

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

警告：不要使用 sudo npm install -g，會有權限與安全風險。

원문 읽기

4驗證安裝、更新與解除安裝

驗證安裝：

bash

claude --version

正常輸出形如 2.1.211 (Claude Code)。更詳細的唯讀診斷用 claude doctor。

更新：原生安裝自動背景更新；手動立即更新執行 claude update。可設定 release 通道（settings.json 中 "autoUpdatesChannel": "stable"，或經 /config）；停用背景自動更新設 DISABLE_AUTOUPDATER=1。

解除安裝示例（macOS / Linux 原生）：

bash

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

npm 安裝用 npm uninstall -g @anthropic-ai/claude-code；Homebrew 用 brew uninstall --cask claude-code。刪除設定會清空所有設定、允許的工具、MCP 設定與工作階段歷史：rm -rf ~/.claude && rm ~/.claude.json。

원문 읽기

5登入認證：Claude 帳號與 API Key

Claude Code 必須有帳號才能使用。首次執行 claude 會引導你在瀏覽器完成登入。

Claude 訂閱（Pro / Max / Team / Enterprise）或 Claude Console（API 預付費）帳號：按提示在瀏覽器完成認證
若已設定 ANTHROPIC_API_KEY 環境變數，Claude Code 會跳過登入提示，改為請求你批准該 key（交互模式下需一次性批准）
工作階段內輸入 /login 可切換帳號或重新認證；登入成功後憑據會儲存，之後毋須重複登入
也可經雲平台使用：Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 等第三方整合

원문 읽기

6第一次執行：啟動交互工作階段

在專案目錄開啟終端並啟動：

bash

cd /path/to/your/project
claude

Claude Code 會開啟交互工作階段，提示符上方顯示版本、當前模型與工作目錄。輸入 /help 查看可用指令，/resume 繼續之前的工作階段。

常用 shell（終端層）指令：

claude：啟動交互模式
claude "task"：執行一次性任務，如 claude "fix the build error"
claude -p "query"：執行一次性查詢後退出
claude -c：在當前目錄繼續最近一次工作階段
claude -r：恢復某個歷史工作階段

원문 읽기

7基礎交互一：用自然語言提問與改程式碼

直接以自然語言對話，Claude 按需讀取專案檔案，毋須手動添加上下文。示例：

理解程式庫：what does this project do?、what technologies does this project use?、where is the main entry point?
改程式碼：add a hello world function to the main file——Claude 會定位檔案、展示改動、請求批准後完成編輯
權限模式：預設模式下每次改動前都會詢問；按 Shift+Tab 循環切換：acceptEdits 自動批准檔案編輯，plan 只規劃不改動（部分帳號還有 auto 模式做背景安全檢查）
新手建議：請求寫具體（例如 fix the login bug where users see a blank screen after entering wrong credentials）、分步驟下指令、讓 Claude 先探索程式碼再動手

원문 읽기

8基礎交互二：slash 指令與 Tab 補全

工作階段內常用指令：

/clear：清空對話歷史
/help：顯示可用指令
/exit（或 Ctrl+D 兩次）：退出 Claude Code

常用快捷鍵：

輸入 /：列出全部指令與 skills
Tab：指令補全
↑：回看指令歷史
Shift+Tab：循環切換權限模式

更多常用指令：/model 切換模型、/config 開啟設定、/status 查看連線與憑據來源、/compact 壓縮超長工作階段。完整列表見官方 commands 參考文檔。

원문 읽기

9Git 操作與常見工作流

Git 操作可對話式完成，示例：

what files have I changed?、commit my changes with a descriptive message
create a new branch called feature/quickstart、show me the last 5 commits、help me resolve merge conflicts

其他常見工作流：

重構：refactor the authentication module to use async/await instead of callbacks
寫測試：write unit tests for the calculator functions
更新文檔：update the README with installation instructions
程式碼審查：review my changes and suggest improvements

技巧：像對待一位可靠嘅同事咁描述你的目標；複雜的資料庫改造可先叫佢 analyze the database schema 再動手。

원문 읽기

10用 ANTHROPIC_BASE_URL 對接第三方網關（概念與檢查）

LLM 網關是組織在 Claude Code 與模型提供方之間執行的代理；用網關時，Claude Code 以網關簽發的憑據認證，而非個人 claude.ai 登入。對香港用戶而言，這就是把 Claude Code 指向本地 / 第三方 Anthropic Messages API 相容網關的關鍵。

檢查是否已被管理員設定：

1執行 claude，若直接進入工作階段而非登入頁，說明已有設定
2執行 /status 查看狀態頁：出現 Anthropic base URL 行說明已指向網關；出現 Auth token 或 API key 行說明網關憑據生效
3發送任意提示，正常回覆即連線成功

원문 읽기

11設定 ANTHROPIC_BASE_URL 與憑據變數

需設定兩個變數：網關 base URL + 憑據。憑據按類型選擇：ANTHROPIC_AUTH_TOKEN（網關說 bearer token 或 Authorization header，發 Authorization: Bearer 頭）或 ANTHROPIC_API_KEY（說 API key 或 x-api-key，發 x-api-key 頭）；不確定就先試 ANTHROPIC_AUTH_TOKEN。

方式一（shell 匯出，僅當前終端工作階段）：

bash

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

PowerShell：

powershell

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

方式二（settings 檔案，全域生效）：寫入 ~/.claude/settings.json（Windows 為 %USERPROFILE%\.claude\settings.json）的 env 區塊：

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

注意：不要把憑據寫進專案 .claude/settings.json（會隨倉庫提交共享）；settings 檔案優先於 shell 匯出。

원문 읽기

12驗證網關連線與常見排錯

匯出變數後先發一個 1-token 請求直接驗證 URL 與憑據：

bash

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

返回以 {"id":"msg_ 開頭並含 "content":[...] 即成功（報未知模型也證明認證通過）；401 表示憑據被拒，換另一個變數再試。

常見排錯：連線拒絕→URL 或 VPN/防火牆路徑問題；HTTP 200 空/畸形回應→網關返回了非 API 內容；400 報未知欄位→設 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1；上下文超限→/compact；TLS/自簽證書錯誤→設 NODE_EXTRA_CA_CERTS 指向 CA bundle。

원문 읽기

13進階設定：自訂請求頭、apiKeyHelper 與模型發現

按需啟用，管理員點名或網路受限時再設定：

自訂請求頭（路由 / 租戶識別等）：

bash

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

settings.json 中多行用 \n 分隔："ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"。

網關模型發現（把網關模型加入 /model 選擇器，需 v2.1.129+）：

bash

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

發現的模型以 From gateway 標籤出現。

apiKeyHelper（憑據輪換 / 來自 vault 時，動態取憑據）：

json

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

結果快取 5 分鐘，可用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 調整；其值同時發 Authorization 與 x-api-key 頭。

關停網關外非必要流量（版本檢查 / 遙測等，同時停用自動更新與模型發現）：

bash

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

원문 읽기

더 보고 싶으신가요?

PingAI 에 가입하여 모든 튜토리얼을 확인하세요. 더 많은 주제가 추가됩니다.

튜토리얼은 완전 무료입니다. PingAI 계정으로 시청하세요.

3安裝方式二：Homebrew / WinGet / 套件管理器 / npm

Homebrew（macOS）：

bash

brew install --cask claude-code

claude-code 走 stable 通道（約慢一週、跳過有重大回歸的版本），claude-code@latest 走最新通道；Homebrew 不會自動更新，需手動 brew upgrade claude-code。

WinGet（Windows）：

powershell

winget install Anthropic.ClaudeCode

Linux 套件管理器（apt / dnf / apk，示例為 Debian/Ubuntu 的 stable 通道）：

bash

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code

npm（要求 Node.js 22+）：

bash

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

警告：不要使用 sudo npm install -g，會有權限與安全風險。

원문 읽기