🚀 从零开始 — 给没有开发背景的设置指南¶
这一页不是要你把所有工具都装一遍。你只要先选一扇门，完成一个小结果。
已经会用 Python、Git 和 terminal，也知道怎么保护 API Key（API 密钥）？可以直接去 Stage 1。
📌 这份指南会带你完成什么¶
- 分清 Web Chat、Desktop、IDE、CLI Agent（命令行代理） 和 API（应用程序接口），不再把它们当成同一种工具。
- 知道 API Key（API 密钥） 为什么像密码，以及不能放在哪里。
- 用
uv准备 Python 3.12，不必先学一大堆包管理知识。 - 复制一份 Python 程序，真的收到模型回复。
- 知道什么时候该去 Stage 1，什么时候该去 Stage 5。
查看时间、设备与先决条件
- 只用 Web Chat：几分钟即可开始。
- 完成 API quick start：通常需要约 20–40 分钟；账号审核、付款设置和网络状况可能让时间变长。
- 需要：可以安装软件的 Windows、macOS 或 Linux 电脑，以及能打开供应商 Console 的账号。
- 不需要：先会写程序、先懂 Git branch、先装完整 IDE。
公司或学校电脑可能禁止安装程序或创建 API key。遇到这种情况，先问管理员，不要绕过限制。
🚪 先选一扇门¶
五扇门是并行选择，不是五个一定要依次完成的等级。
| 你想做什么 | 这扇门是什么 | 第一个动作 |
|---|---|---|
| 先和模型聊天 | Web Chat：在浏览器里对话 | 打开 Claude、ChatGPT、Gemini 或 Le Chat |
| 在电脑 App 里聊天或处理文件 | Desktop App：装在电脑上的聊天界面 | 从产品的官方下载页安装 |
| 写 code 时让 AI 在旁边协助 | IDE Assistant：住在 editor 里 | 先看开发者路线 |
| 让 Agent 在指定文件夹读文件、改文件、跑命令 | CLI Agent：在 terminal 里工作 | 先看 CLI Agents 指南 |
| 自己写程序调用模型 | API：程序和模型服务对话的入口 | 继续做下面 A → B → C |
查看 Web、Desktop、IDE 与 CLI 的完整官方入口
下表是入口清单，不是排名。推荐度表示“这份学习地图是否适合把它作为起点”。
| 类型 | 官方入口／项目 | 先知道什么 | 推荐度 |
|---|---|---|---|
| Web Chat | Claude | 云端聊天界面；方案和功能依账号、地区而异 | ⭐⭐⭐⭐⭐ |
| ChatGPT | 云端聊天界面；ChatGPT 订阅不等于 OpenAI API 额度 | ⭐⭐⭐⭐⭐ | |
| Gemini | 云端聊天界面；连接服务前先看数据权限 | ⭐⭐⭐⭐⭐ | |
| Le Chat | Mistral 的云端聊天界面 | ⭐⭐⭐⭐ | |
| Desktop | Claude Desktop | Windows、macOS 与 Linux 的当前入口以官方页面为准 | ⭐⭐⭐⭐⭐ |
| ChatGPT Desktop | 平台要求以官方下载页为准 | ⭐⭐⭐⭐⭐ | |
| Gemini for macOS | 目前是 macOS App；其他系统可使用 Web | ⭐⭐⭐⭐ | |
| LM Studio | 本地模型 runtime 和图形界面；仍要管理模型、硬件和文件权限 | ⭐⭐⭐⭐ | |
| IDE／Editor | Cursor | AI editor；确认每次修改和 terminal 操作 | ⭐⭐⭐⭐⭐ |
| Devin Desktop（原 Windsurf） | Windsurf 更名后的桌面 Coding Agent／IDE；仍要确认工具权限和方案 | ⭐⭐⭐⭐ | |
| Cline | VS Code coding agent；从低权限开始 | ⭐⭐⭐⭐ | |
| Zed AI | Zed editor 的 AI 功能 | ⭐⭐⭐⭐ | |
| GitHub Copilot | 可在 GitHub、IDE 和其他界面使用；各界面的权限不同 | ⭐⭐⭐⭐⭐ | |
| CLI Agent | Claude Code | 先保留 permission prompt；从小文件夹开始 | ⭐⭐⭐⭐⭐ |
| OpenAI Codex | coding agent；确认 sandbox、approval 和 diff | ⭐⭐⭐⭐⭐ | |
| Gemini CLI | Gemini 的开源 terminal agent | ⭐⭐⭐⭐ | |
| OpenCode | 多 Provider coding agent／harness，不是模型 Router | ⭐⭐⭐⭐⭐ | |
| goose | 可连接 Provider 和 extensions；先缩小工具权限 | ⭐⭐⭐⭐ | |
| Aider | Git-first pair programmer；auto-commit 不代表可以跳过 review | ⭐⭐⭐⭐⭐ | |
| Hermes Agent | 通用 agent；先在隔离环境试小任务 | ⭐⭐⭐⭐ |
🧩 先分清七个核心词¶
- Chat Surface（聊天界面）：你打字、贴文件、看回复的画面，例如 Claude.ai。它不是模型 API。
- API（应用程序接口）：程序发送请求、拿回结果的入口。人通常不直接在 API 画面聊天。
- API Key（API 密钥）：让服务知道“这个程序可以使用哪个账号”的秘密字符串。拿到它的人可能花掉你的额度。
- Environment Variable（环境变量）：把设置交给程序读取的小抽屉。程序可以读它，不必把秘密写进 source code。
- Runtime（运行环境）：真正把程序跑起来的东西；Python 是一种 runtime，Ollama 是本地模型 runtime。
- Package Manager（包管理器）：帮你安装和运行别人写好的包。这份指南使用
uv。 - CLI Agent（命令行代理）：在 terminal 里读文件、改文件、执行工具的 Agent。它不是 API Provider，也不是单一模型。
📚 必读与官方起点¶
这五个入口直接保持可见；遇到版本差异时，以官方页面为准。
| 类别 | 官方资源 | 用它解决什么 | 推荐度 |
|---|---|---|---|
| Claude API | Claude API Quickstart | 创建 key、发送第一个请求 | ⭐⭐⭐⭐⭐ |
| Anthropic Python SDK | 确认 Python 要求、环境变量与当前程序形态 | ⭐⭐⭐⭐⭐ | |
| Python 工具 | uv Installation | 按操作系统安装或更新 uv | ⭐⭐⭐⭐⭐ |
| CLI 入门 | Claude Code Terminal Guide | 第一次打开 terminal、切换文件夹和执行命令 | ⭐⭐⭐⭐⭐ |
| 秘密安全 | GitHub Secret Scanning | 了解为什么 secret 不能进入 Git 历史 | ⭐⭐⭐⭐ |
🛠 A — 拿到第一把 API Key¶
这条 quick start 使用 Anthropic Claude，因为 Stage 1 的 canonical API 路径也使用它。Claude.ai 订阅和 Claude API 账单是两回事。
- 打开 Claude Console。
- 进入 API Keys，创建一把只给这个练习使用的 key。
- 如果页面可以选择 owner、workspace 或期限，使用最小范围与最短合理期限。
- 复制 key，先放进密码管理器；不要贴到聊天窗口。
- 先在 Console 查看 billing／usage；如果账号提供 spend limit 或提醒，把它设在你能接受的小额范围，再开始调用 API。
API Key 三不规则：
- 不粘贴到 chat、群组、email、issue 或截图。
- 不写入 Python source code，也不进 Git 历史。
- 不共享同一把 key 给很多项目；不用时撤销。
查看其他 Cloud API 与本地 Runtime
下表只写当前官方入口。价格、免费额度和可用模型请点击官方页面查看，这份入门指南不冻结这些信息。
| 类型 | 官方入口 | Compatibility／限制 | 推荐度 |
|---|---|---|---|
| Cloud API | OpenAI API | 官方 SDK 与 API；ChatGPT 订阅不等于 API billing | ⭐⭐⭐⭐⭐ |
| Gemini API | Google 官方提供 OpenAI libraries compatibility 说明 | ⭐⭐⭐⭐⭐ | |
| NVIDIA NIM | 按 endpoint 查看支持的 API shape 与模型 | ⭐⭐⭐⭐ | |
| DeepSeek API | 官方文档提供 OpenAI-compatible 使用方式 | ⭐⭐⭐⭐ | |
| Kimi API | 地区、endpoint 与模型以官方 Console 为准 | ⭐⭐⭐⭐ | |
| Alibaba Model Studio／Qwen | 按区域使用对应 base URL；官方提供 OpenAI-compatible endpoint | ⭐⭐⭐⭐ | |
| Z.ai／GLM API | 按官方 reference 使用当前 endpoint | ⭐⭐⭐⭐ | |
| 本地 Runtime | Ollama | 只兼容 OpenAI API 的一部分；需要另外下载本地模型 | ⭐⭐⭐⭐⭐ |
本地推理没有供应商模型 API 账单，但硬件、电力、下载时间、设备安全、文件和 log 仍由你负责。完整路径请看 Cookbook 的本地 LLM walkthrough。
这个 repo 当前的练习标签是：Stage 1–2 用 gemma4:e4b，Stage 3–6 的 Tool Use／ReAct 用 qwen2.5:3b，Stage 7 的 Eval／Observability／Streaming／Deploy 用 qwen3.5:4b。这是教材默认值，不是通用模型排名。
🛠 B — 装好 Python 运行环境¶
这里用 uv 同时管理 Python 和包。先安装 uv：
macOS、Linux 或 WSL：
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows PowerShell：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
关闭并重新打开 terminal，再依次复制：
uv --version
uv python install 3.12
uv run --python 3.12 python --version
最后一行看到 Python 3.12，就完成 B。uv 也支持其他 Python 版本；这份教程固定 3.12，减少初学时的包兼容问题。
安装失败时，查看各操作系统替代方式
- Windows 可以使用
winget install --id=astral-sh.uv -e。 - macOS 可以使用
brew install uv。 - 也可以从 uv 官方安装页 下载 release binary。
- 如果公司封锁安装 script，停止并请管理员提供批准方式，不要关闭安全软件硬闯。
已经有 Python 3.10–3.14 也没关系，uv 会寻找可用的 Python；上面的命令只是替这份教程准备一致的 3.12。
🛠 C — 跑第一个 hello-claude.py¶
1. 建立练习文件夹¶
PowerShell、macOS 和 Linux terminal 都可以使用：
mkdir my-first-llm
cd my-first-llm
2. 先建立 .gitignore¶
建立名为 .gitignore 的文件，贴上：
.env
__pycache__/
*.pyc
先排除 .env，再建立 secret 文件，可以降低误加进 Git 的机会。
3. 再建立 .env¶
建立名为 .env 的文件。把 placeholder 换成你自己的 key；不要把真 key 贴到这份文档或 commit：
ANTHROPIC_API_KEY=PASTE_YOUR_KEY_HERE
4. 复制 Python 程序¶
建立 hello-claude.py：
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv()
client = Anthropic() # 从 ANTHROPIC_API_KEY 读取 key
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "请用一句话介绍你自己。"}],
)
for block in message.content:
if block.type == "text":
print(block.text)
5. 直接执行¶
uv run --python 3.12 --with anthropic --with python-dotenv python hello-claude.py
看到模型打印一句介绍，就代表 Python、包、API key 和网络都接通了。
查看常见错误与安全恢复
| 你看到什么 | 通常代表什么 | 先做什么 |
|---|---|---|
401／authentication_error |
key 没读到、失效或贴错 | 撤销有疑虑的 key；确认文件名是 .env，再创建新 key |
429／rate_limit_error |
用量、速率或账号额度限制 | 停止重试，回 Console 看 usage／billing，再按错误信息等待 |
ModuleNotFoundError |
没用到这次 uv run --with ... 的环境 |
完整复制执行命令，不要只跑 python hello-claude.py |
uv 找不到 |
安装后的 terminal 还没读到新 PATH | 关闭并重新打开 terminal；再看 uv 官方安装页 |
| 连接错误 | 网络、proxy、防火墙或服务状态 | 先看供应商 status page；公司／学校网络请问管理员 |
如果 key 曾出现在 Git、聊天、截图或公开 log，不能只把文字删掉；请立刻在 Console 撤销它并创建新 key。
🛠 D — 第一次打开 Claude Code¶
这是 Stage 5 的入口，不是完成 API quick start 的必修。Claude Code 现在优先使用 native installer，不必先安装 Node.js。
macOS、Linux 或 WSL：
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell：
irm https://claude.ai/install.ps1 | iex
安装后先运行 claude --version，再到一个小型练习文件夹运行 claude。完整条件和其他安装方式请看 Claude Code Installation。
查看登录、系统要求与第一份 CLAUDE.md
Claude Code 目前需要符合官方列出的 Claude plan、Console account 或支持的 cloud provider；免费的 Claude.ai plan 不包含 Claude Code。运行 claude 后按浏览器提示登录，详细身份差异请看 Authentication。
官方当前基本要求包括受支持的 Windows、macOS 或 Linux、至少 4 GB RAM、网络连接和可用 shell。Windows 可以原生使用 PowerShell；需要 Linux toolchain 或 sandbox 时再考虑 WSL 2。
你可以在 project root 建立 CLAUDE.md：
# 这个 project 要做什么
这是一个学习用的小项目。
# 工作规则
- 先说明要改哪些文件，再开始修改。
- 不要读取或改写 `.env`。
- 不要自动 commit；完成后让我先看 diff。
- 删除文件、安装包或联网前先问我。
# 完成条件
- 执行最小相关测试。
- 说明改了什么、测试了什么、还有什么风险。
CLAUDE.md 是 project instructions，不是安全 sandbox。工具权限、approval、版本控制和人工 review 仍要保留。
🛠 E — 建立第一个 Skill¶
这是 Stage 5.3 的延伸。Skill（技能包） 是有名称、描述和操作指示的可复用文件夹；它不会自动变成安全权限。
第一个动作：建立 .claude/skills/hello-skill/SKILL.md。
查看可以直接复制的 SKILL.md
---
name: hello-skill
description: 当使用者明确请你打招呼时，用两种语言回复。
---
当使用者请你打招呼时：
1. 用繁体中文说一次 hello。
2. 用英文说一次 hello。
3. 不读文件、不联网、不执行其他工具。
在该 project 打开 claude，输入“请打招呼”。看到两种语言，而且没有多做其他动作，就完成了。
更完整的责任边界请看 Stage 5.3 — Skills，更多示例请看 Cookbook。
✅ 完成检查¶
做到下面任一条，就可以离开这份指南，不必把所有入口都装完：
- 我已经能在 Web Chat 完成一次对话，而且知道它不是 API。
- 我完成 A → B → C，看到
hello-claude.py打印模型回复。 - 我选择 CLI 路径，能说出 CLI Agent 的工作文件夹与权限范围。
还要确认：
- 真正的 API key 没有出现在 source code、Git、聊天、截图或 log 中。
- 我知道如何撤销 key，也知道 API billing 和聊天订阅分开。
- 我没有因为工具能自动执行，就跳过 diff、测试或人工确认。
接下来去哪¶
| 你现在想做什么 | 下一站 |
|---|---|
| 理解模型、Token、Context Window 与 API | Stage 1 — LLM 基础 |
| 直接学 Prompt | Stage 2 — Prompt Engineering |
| 使用 CLI Agent 工作 | Track A1 — CLI 入门 |
| 理解 Claude Code、MCP、Skills、Plugins 与 Subagents | Stage 5 — Claude Code 生态 |
| 使用本地模型 | Cookbook：本地 LLM walkthrough |
| 还分不清 OpenRouter、Ollama、OpenCode 或 Pi | Glossary：先分清五种工具身份 |