🚀 從零開始 — 給沒有開發背景的設定指南¶
預估時程：30-45 分鐘。你會申請第一個 API key、裝好 Python / uv，並跑出第一個 LLM hello world。 這份文件寫給「想學 AI agent，但還沒寫過 code」的人。已經熟 Python / git / CLI 的開發者，可以直接跳 Stage 1。
先選你的入門方式¶
依「想花多少時間 setup」由淺到深排序。完全沒接觸過 LLM 直接從 1️⃣ 開始就好。
1️⃣ 網頁版（最簡單，免費可試，零 setup）¶
打開瀏覽器就能用，第一次接觸 LLM 最推薦這條。免費 tier 通常夠你試一個禮拜。
| 服務 | 網址 | 備註 |
|---|---|---|
| Claude | https://claude.ai | Anthropic 官方。免費 tier 每天額度有限，付費版 $20/月 |
| ChatGPT | https://chatgpt.com | OpenAI 官方。免費可用 GPT-5（基本款），付費 $20/月升 Plus |
| Gemini | https://gemini.google.com | Google 官方。免費 tier 寬鬆，整合 Google 服務 |
| Le Chat | https://chat.mistral.ai | Mistral（歐洲開源 LLM）。免費、隱私導向 |
2️⃣ 桌面 App（免費，跨應用整合更好）¶
跑在你電腦上的原生 app——比網頁多了系統 shortcut、跟剪貼簿 / 截圖整合、可以拖拉檔案。
| App | 下載 | 平台 |
|---|---|---|
| Claude Desktop | https://claude.ai/download | macOS / Windows |
| ChatGPT Desktop | https://openai.com/chatgpt/download | macOS / Windows |
| Gemini | 暫無原生 desktop app | （用網頁版即可） |
| LM Studio | https://lmstudio.ai | macOS / Windows / Linux — 跑本機 LLM 的桌面 app，零成本但要 GPU/RAM |
3️⃣ IDE 內建 AI（在 code editor 裡邊寫 code 邊有 AI 助手）¶
跑在 IDE / code editor 裡——你正常寫 code，AI 在旁邊 suggest、修改、回答問題。已經有寫 code 習慣、想把 IDE 升級成 AI-native 的人這條最順。
| 工具 | 下載 | 形態 |
|---|---|---|
| Cursor | https://cursor.com | 獨立 IDE（VS Code fork） |
| Windsurf | https://codeium.com/windsurf | 獨立 IDE（Codeium 出） |
| Cline | https://cline.bot | VS Code extension（agentic 風格） |
| Continue | https://continue.dev | VS Code / JetBrains extension（開源） |
| Roo Code | https://github.com/RooCodeInc/Roo-Code | VS Code extension（Cline fork，社群活躍） |
| Zed | https://zed.dev | 獨立 editor，內建 AI assistant |
| GitHub Copilot | https://github.com/features/copilot | VS Code / JetBrains 等多 IDE extension |
→ 詳細比較 → branches/for-developer.md
4️⃣ CLI Agent（terminal，能讀寫檔案、跑指令、操作 git）¶
裝在 terminal 的 agent——你下一個 prompt（譬如「重構這個 module」），agent 自己讀檔、改檔、跑指令、commit。比 IDE 模式更自主、可以處理多步驟任務，但 setup 稍複雜（需要先有 Node.js 或 Python，看下面 B / D）。
| CLI Agent | 安裝 / 文件 | 主要 LLM |
|---|---|---|
| Claude Code | https://docs.anthropic.com/en/docs/claude-code/quickstart | Claude |
| Codex CLI | https://github.com/openai/codex | GPT 系列 |
| Gemini CLI | https://github.com/google-gemini/gemini-cli | Gemini |
| OpenCode | https://github.com/sst/opencode | 任意（多 provider） |
| goose | https://block.github.io/goose | 任意 |
| Aider | https://aider.chat | 任意（git-native） |
| Hermes Agent | https://github.com/NousResearch/hermes-agent | 200+（model-neutral） |
→ 想看 7 個 CLI 完整比較 → cli-agents-guide.md
→ Claude Code 第一次裝的詳細步驟 → 本指南 D
💡 IDE-based 跟 CLI agent 怎麼選？ 邊寫 code 邊要 AI 幫忙 → IDE；下單一 prompt 讓 agent 自己跑完一整個任務 → CLI。兩個可以並用。
5️⃣ API + 自己寫 code（最進階，能 batch、整合任何工具）¶
想自己寫 Python script、跑 batch job、把 LLM 接到自己的 app／automation？接下來的 A-C 就是給你的。
💡 API key 是什麼：簡單講就是「讓程式呼叫模型的密碼」。請把它當成信用卡資料一樣保管。
A — 申請第一個 API key（約 10 分鐘）¶
Anthropic Claude（推薦第一次）¶
- 開 https://console.anthropic.com/
- 用 Google、GitHub 或 email 註冊。
- 進帳號後找到 API Keys，按 Create Key。
- 立刻複製顯示出的 key。多數平台只會顯示一次。
- 先放在本機密碼管理器，或短暫放在本機文字檔；下一節會移到
.env。
⚠️ API key 三不規則 - 不貼到 chat 視窗、群組、email 或截圖。 - 不上傳到 git；GitHub 可能掃到後自動撤銷。 - 不放雲端硬碟純文字檔；同步到其他裝置等於多一份風險。
其他 LLM 選項¶
西方 cloud（美區友善、英文場景）¶
- OpenAI：https://platform.openai.com/api-keys ChatGPT Plus 和 API key 是兩件事；訂閱 Plus 仍要另外申請 API key。
- Google AI Studio：https://aistudio.google.com/ 適合先試 Gemini API，免費額度會依地區和帳號狀態不同。
- NVIDIA NIM：https://build.nvidia.com/
托管多個開源 model（Llama / Mistral / DeepSeek-R1 + R2 lineage / Qwen / Gemma 等）、OpenAI-compatible API、新帳號送 1000 credits。適合「想試多個 open-source model 但沒 GPU」的情境。
base_url=https://integrate.api.nvidia.com/v1。
中國 / 中文場景（地區友善、價格極便宜）¶
中國大陸使用者連 Anthropic / OpenAI 有困難、或想試中文 native 模型，從這邊開始。這些 API 都 OpenAI-compatible、改
base_url跟 model name 就能跑同一份練習。
- DeepSeek：https://platform.deepseek.com/
web 版 https://chat.deepseek.com 完全免費（含 R1 推理模型）。API 價格極便宜（$0.27 input / $1.10 output per 1M token、比 haiku 便宜 4 倍）。Code / 推理都很強。
base_url=https://api.deepseek.com/v1、model=deepseek-chat或deepseek-reasoner。 - Moonshot Kimi：https://platform.moonshot.cn/ (中國)、https://platform.moonshot.ai/ (海外)
web 版 https://kimi.com 免費、1M token context 是賣點（很大檔案 / 長對話）。API 約 $5-15/1M input、按 context size 階梯計費。
base_url=https://api.moonshot.cn/v1(中國) /https://api.moonshot.ai/v1(海外)、model=kimi-k2-turbo-preview等。 - 通義千問 Qwen（Alibaba）：https://dashscope.console.aliyun.com/
web 版 https://chat.qwen.ai 免費。API 走 Alibaba Cloud DashScope、有 OpenAI-compatible endpoint（文件）。同樣的 Qwen 模型也能用 Ollama 在本機跑（
ollama pull qwen2.5:3b）——cloud 跟 local 兩條路徑都通。 - 智譜 GLM（ZhipuAI）：https://open.bigmodel.cn/ (中國) / https://z.ai/ (海外) web 版 https://chatglm.cn 免費、有 GLM-4.5、GLM-4-Plus。API 有 free tier、學生申請可額外領 credit。
本機（不付 API 費、完全 offline）¶
- Ollama 本機模型：不用 API key。走本機路線請看 Cookbook Recipe 6。
本 repo 的「Path A」預設就是 Ollama；所有 Stage 1-7 練習都能用
gemma4:e4b（Stage 1-2）或qwen2.5:3b（Stage 3+）跑通、$0/run。
💡 怎麼挑第一個： - 想學 agent / production、美區帳號OK → Anthropic Claude（curriculum canonical） - 想學 agent / production、中國地區或想試中文模型 → DeepSeek（最便宜 cloud option、OpenAI-compat、中文很強） - 想試多個 model 但沒 GPU → NVIDIA NIM（送 1000 credit、托管 10+ open model） - 隱私敏感 / 完全免費 / 中國大陸無 cloud → Ollama（本機、curriculum 全套都能跑、$0）
B — 裝本機環境（約 10 分鐘）¶
裝 Python 3.10+¶
- macOS：開 Terminal，輸入
brew install python@3.12。如果還沒有 Homebrew，先看 https://brew.sh。 - Windows：到 https://www.python.org/downloads/ 下載 installer，安裝時一定要勾 Add Python to PATH。
- Linux：Ubuntu 用
sudo apt install python3 python3-venv，Fedora 用sudo dnf install python3。 - 驗證：macOS / Linux 輸入
python3 --version；Windows 輸入py --version。看到Python 3.10以上即可。
裝 uv¶
uv 是 Python 套件管理工具。你可以把它想成「幫你臨時裝好需要套件再執行」的工具。
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex
驗證：
uv --version
建立第一個 .env 檔¶
在你要跑 script 的資料夾裡，建立一個檔名叫 .env 的檔案：
ANTHROPIC_API_KEY=sk-ant-...貼上你剛才複製的 key
.env 是專門放本機祕密資訊的檔案。程式會讀它，但你不應該把它上傳到 GitHub。
加上 .gitignore¶
同一個資料夾建立 .gitignore：
.env
__pycache__/
*.pyc
這樣 git 就不會把 .env 收進版本紀錄。
C — 跑第一個 hello-claude.py（約 5 分鐘）¶
建立 hello-claude.py：
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv()
client = Anthropic() # 自動讀取 ANTHROPIC_API_KEY
msg = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=100,
messages=[{"role": "user", "content": "Hello, who are you?"}],
)
print(msg.content[0].text)
執行：
uv run --with anthropic --with python-dotenv python hello-claude.py
看到 Claude 回覆自我介紹，就代表你的 API key、Python、套件都通了。
常見錯誤¶
| 錯誤訊息 | 常見原因 | 解法 |
|---|---|---|
401 Unauthorized |
API key 沒讀到或打錯 | 回 A 重新複製，確認 .env 檔名和內容 |
429 Rate limit |
太快送太多請求 | 等幾秒或幾分鐘再跑 |
connection refused |
連線或防火牆問題 | 確認網路、公司或學校防火牆 |
ModuleNotFoundError |
套件沒有被安裝 | 確認執行的是上面的 uv run --with ... 指令 |
D — 第一次裝 Claude Code（約 10 分鐘；Stage 5 / for-developer 會用到）¶
先裝 Node.js¶
💡 Node.js 是什麼：跑 JavaScript 的 runtime（類似 Python interpreter 但是給 JS 用）。
npm是它附帶的「套件管理器」（package manager）—— 跟 Python 的pip同角色、用來安裝別人寫好的工具（如下面的 Claude Code）。npm install -g X表示「全域裝 X、之後在任何資料夾都能用」。
- macOS / Linux：
brew install node，或從 https://nodejs.org 下載。 - Windows：從 https://nodejs.org 下載 installer。
- 驗證：輸入
node --version，看到 v18 以上即可。
裝 Claude Code¶
npm install -g @anthropic-ai/claude-code
第一次認證¶
claude
第一次啟動時通常會讓你選：
- Claude subscription：用 Claude.ai 帳號登入，對初學者最省事。
- API key：貼上 A 申請到的 key。
建立第一份 CLAUDE.md¶
在你的 project 根目錄建立 CLAUDE.md。Claude Code 啟動時會讀它，理解你希望它怎麼協助。
# 你是誰
我是 [你的名字]，[你的領域，例如：教師 / 研究者 / 寫作者]。
# Code style
- 註解用繁體中文寫，code 用英文
- 寫 function 時優先加 type hint
- 不要主動 commit；改完讓我手動 git add
# 不准做的事
- 不要連網查資料，除非我明確說可以
- 不要動 `.env` 或 `.gitignore`
- 不要刪資料夾，包括子資料夾
E — 第一個 Skill 範例（約 5 分鐘；Stage 5.3 會用到）¶
Skill 是 Claude Code 的「可重用 prompt 包」。當你的訊息符合描述，Claude Code 會自動載入那份指示。
建立 .claude/skills/hello-skill/SKILL.md：
---
name: hello-skill
description: 第一個 hello skill。當使用者說「請打招呼」或「say hi」時觸發。
---
當使用者請你打招呼時，回三件事：
1. 用繁體中文跟英文各說一次 hello
2. 提現在的日期（用 system 時間）
3. 給一個今日小提醒（隨機選健康 / 學習 / 心情建議）
跑 claude，輸入「請打招呼」。如果 Claude 回覆三件事，就代表 Skill 被載入了。
想看更完整的 Skill 設計：看 Stage 5.3 — Skills。 想看可以照做的範例：看 Cookbook。
接下來去哪¶
| 你現在的狀態 | 下一步 |
|---|---|
| 想正式理解 LLM、API、token | Stage 1 — LLM 基礎 |
| 想直接挑身分分支 | 日常使用者 / 教師 / 知識工作者 / 研究者 / 開發者 |
| 想看 Claude Code 完整生態 | Stage 5 — Claude Code 生態系 |
| 想本機 LLM、不用雲端 key | Cookbook Recipe 6 |
| 想比較 CLI agent | CLI Agents 比較指南 |
| 不懂某個用詞 | Glossary |