## 概述
本教程面向从未接触过命令行 AI 编程的零基础读者，目标只有一个：从零把 Claude Code 装好、配好，并和它一起造出第一个真正能用的命令行工具——一个调用免费天气接口、无需任何 API 密钥的「天气查询 CLI」。学完后你将掌握 Claude Code 的安装、登录、基础配置、项目初始化，以及如何用自然语言指挥它完成从写代码到调试运行的完整闭环。
## 前置条件
- 一台 macOS、Windows 或 Linux 电脑，能联网
- 会基本的命令行操作（`cd`、`ls` 进入目录即可），不会也能跟着抄
- Python 3.8 及以上（macOS/Linux 多数自带；Windows 去 python.org 下载，安装时勾选 *Add to PATH*）
- 一个 Anthropic 账号（用 Claude 官网账号即可登录，无需自己申请 API Key）
---
## 一、Claude Code 是什么
Claude Code 是 Anthropic 官方推出的**命令行智能体（agentic CLI）**。和网页版聊天的最大区别是：它不只在对话框里给你贴代码，而是**真的会动手**——能在你的项目目录里读文件、写文件、跑命令、看报错、再修改，循环往复直到把任务做完。
换句话说，传统编程是「人写、机器执行」；用 Claude Code 是「人描述目标，AI 在你的电脑上自主干活」。对零基础读者来说，这意味着你不必先背熟语法，只要把「我要一个什么样的程序」讲清楚，它就能帮你落地，你在这个过程中顺便学会代码长什么样、为什么这么写。
它的能力边界主要在三件事：①读懂你的项目上下文；②执行你允许的命令；③生成并迭代代码。本教程就围绕这三点展开。
---
## 二、安装：三平台通用，两分钟搞定
2026 年 Anthropic 推出了**原生安装器（native installer）**，不再强制依赖 Node.js，安装更轻。下面给出两种方式，任选其一。
### 方式 A：原生安装器（推荐）
**macOS / Linux**，打开终端粘贴一行：
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
**Windows**，打开 PowerShell（管理员），粘贴一行：
```powershell
irm https://claude.ai/install.ps1 | iex
```
安装器会自动下载二进制、配置好环境变量，并把 `claude` 命令放到你的 PATH 里。
### 方式 B：用 npm 安装
如果电脑里已经装了 Node.js（建议 18 以上），也可以走 npm：
```bash
npm install -g @anthropic-ai/claude-code
```
国内网络环境如果拉取慢，可先切换 npm 镜像：`npm config set registry https://registry.npmmirror.com`，再执行上面的安装命令。
### 验证安装
新开一个终端窗口（让 PATH 生效），输入：
```bash
claude --version
```
能打印出版本号，就说明 `claude` 命令已就绪。如果提示 `command not found`，多半是 PATH 没刷新——重启终端，或在 Windows 上确认是用「PowerShell」而非旧版 cmd。
> **常见坑①**：Windows 下提示找不到命令 → 关掉终端重开；仍不行，检查安装目录是否在系统 PATH 里。
> **常见坑②**：macOS 用 curl 安装时被 Gatekeeper 拦 → 在「系统设置 → 隐私与安全性」里点「仍要打开」。
---
## 三、首次启动与登录
在终端任意位置输入：
```bash
claude
```
首次启动会进入交互式登录。屏幕会出现一个网址和一段验证码，你按提示用浏览器打开，登录你的 Anthropic 账号（就是登录 claude.ai 用的那个），把验证码粘进去即可完成绑定。整个流程类似 GitHub CLI 的设备授权，不需要你手动复制 API Key。
登录成功后，你会进入一个带输入框的交互界面，左下角通常显示当前模型与所在目录。此时你其实已经可以开始用了——但为了体验更好，先花两分钟做点基础配置。
> **常见坑③**：登录卡住或一直转圈 → 多半是网络问题，确保能访问 `claude.ai`；公司代理环境下需配置 `HTTPS_PROXY` 环境变量。
---
## 四、基础配置：让它更顺手
Claude Code 的配置分两层：**项目级**（`.claude/settings.json`，跟项目走）和**用户级**（`~/.claude/settings.json`，全局生效）。零基础阶段，我们先用 `/config` 交互命令做最关键的几项。
进入 `claude` 交互界面后，输入：
```
/config
```
会弹出一个可视化菜单，可调整：
- **主题（theme）**：深色 / 浅色，跟着喜好选。
- **通知（notifications）**：长任务跑完是否响铃提示，建议开启，免得干等。
- **默认权限（permissions）**：控制它执行命令前要不要问你。新手建议保持「谨慎模式」——涉及删除、安装、推送等敏感操作时弹窗确认，避免误操作。
更进阶的配置（如换模型、加环境变量、配 hooks 自动化）写在 `settings.json` 里，但本入门篇先不动它，等熟悉了再回来玩。一个通用原则：**先用默认值跑起来，遇到具体痛点再针对性配置**，不要一上来就把所有选项调一遍。
另一个值得现在就立的小规矩是 **CLAUDE.md**——在项目根目录放一个说明文件，告诉 Claude 这个项目用什么语言、有什么约定。本篇我们让 Claude 自己生成它，详见下一节。
---
## 五、第一个项目：和 Claude Code 一起造天气 CLI
### 5.1 设计目标
我们要造的 `weather.py` 满足：
- 输入城市名，输出当前温度、体感温度、湿度、风速、天气状况；
- 数据来自 **Open-Meteo**——一个开源、免费、**无需 API 密钥**的天气接口，对零基础读者最友好；
- 只用 Python 标准库（`urllib`、`json`、`argparse`），**零额外依赖**，复制即跑；
- 内置常用城市经纬度，也支持用 `--coords` 查任意地点。
### 5.2 初始化项目目录
在终端执行（路径自选）：
```bash
mkdir weather-cli && cd weather-cli
```
然后在这个目录里启动 Claude Code：
```bash
claude
```
注意：`claude` 会以**当前目录**作为工作区，它能读写这个目录里的文件。所以养成习惯——**先 `cd` 进项目目录，再启动 `claude`**。
### 5.3 用自然语言下任务
进入交互界面后，把下面这段「需求描述」原样发给它（中文即可，它会理解）：
> 在当前目录创建一个 Python 命令行天气查询工具 `weather.py`，要求：
> 1. 数据来源用免费、无需密钥的 Open-Meteo API；
> 2. 只用标准库，零额外依赖；
> 3. 内置一份常用城市经纬度字典（北京、上海、广州、深圳、成都、东京、纽约、伦敦等），输入城市名即可查询；
> 4. 同时支持 `--coords 纬度 经度` 查任意地点；
> 5. 用 WMO weather code 把天气代码翻译成中文（晴、多云、小雨…）；
> 6. 输出当前温度、体感温度、相对湿度、风速、天气描述，带 emoji，排版美观；
> 7. 处理网络错误和未知城市，给出友好提示；
> 8. 顺手生成一个 CLAUDE.md 说明本项目，再用注释解释关键代码。
按下回车，你会看到它开始「思考 + 动手」：先解释方案，然后逐个创建文件，过程中可能请求你允许执行某些命令（如 `python weather.py 北京` 来验证）——你确认即可。
### 5.4 预期产物
它会生成 `weather.py`，核心代码大致长这样（你可以对照检查它写的是否一致）：
```python
#!/usr/bin/env python3
"""weather.py — 极简天气查询 CLI，数据来自 Open-Meteo（免费、无需密钥）。"""
import argparse
import json
import sys
import urllib.parse
import urllib.request
# 常用城市经纬度（无需联网查坐标）
CITIES = {
"北京": (39.90, 116.40), "上海": (31.23, 121.47),
"广州": (23.13, 113.26), "深圳": (22.54, 114.06),
"成都": (30.57, 104.07), "杭州": (30.27, 120.15),
"武汉": (30.59, 114.31), "西安": (34.27, 108.95),
"香港": (22.32, 114.17), "台北": (25.03, 121.57),
"东京": (35.68, 139.69), "纽约": (40.71, -74.01),
"伦敦": (51.51, -0.13), "巴黎": (48.85, 2.35),
}
# WMO 天气代码 → 中文描述
WMO = {
0: "晴", 1: "大致晴朗", 2: "局部多云", 3: "阴",
45: "雾", 48: "雾凇", 51: "毛毛雨", 53: "毛毛雨", 55: "密集毛毛雨",
61: "小雨", 63: "中雨", 65: "大雨",
71: "小雪", 73: "中雪", 75: "大雪", 77: "冰粒",
80: "阵雨", 81: "中阵雨", 82: "强阵雨",
85: "阵雪", 86: "强阵雪", 95: "雷暴", 96: "雷暴伴冰雹", 99: "强雷暴伴冰雹",
}
def fetch_weather(lat, lon):
"""调用 Open-Meteo 取当前天气，返回 JSON。"""
params = {
"latitude": lat, "longitude": lon, "timezone": "auto",
"current": "temperature_2m,relative_humidity_2m,"
"apparent_temperature,weather_code,wind_speed_10m",
}
url = ("https://api.open-meteo.com/v1/forecast?"
+ urllib.parse.urlencode(params))
with urllib.request.urlopen(url, timeout=10) as resp:
return json.loads(resp.read().decode("utf-8"))
def render(place, data):
"""把接口返回的数据格式化成好看的终端输出。"""
c = data["current"]
desc = WMO.get(c["weather_code"], f"未知代码 {c['weather_code']}")
print(f"\n 📍 {place}")
print(f" 🌡 当前 {c['temperature_2m']}°C · 体感 {c['apparent_temperature']}°C")
print(f" 💧 湿度 {c['relative_humidity_2m']}%")
print(f" 🌬 风速 {c['wind_speed_10m']} km/h")
print(f" 🌤 天气 {desc}\n")
def main():
p = argparse.ArgumentParser(description="极简天气查询（Open-Meteo 数据）")
p.add_argument("city", nargs="?", help="城市名，如：北京、东京；省略则查北京")
p.add_argument("--coords", nargs=2, metavar=("纬度", "经度"),
help="用经纬度查任意地点")
args = p.parse_args()
if args.coords: # 任意坐标
lat, lon = float(args.coords[0]), float(args.coords[1])
place = f"({lat}, {lon})"
else:
place = args.city or "北京"
if place not in CITIES:
print(f"暂未收录「{place}」，目前支持：{'、'.join(CITIES)}")
print("提示：用 --coords 纬度 经度 可查任意地点")
sys.exit(1)
lat, lon = CITIES[place]
try:
data = fetch_weather(lat, lon)
except Exception as e:
print(f"获取天气失败：{e}")
sys.exit(2)
render(place, data)
if __name__ == "__main__":
main()
```
### 5.5 运行验证
退出 `claude` 交互界面（输入 `/exit` 或按 `Ctrl+C` 两次），在普通终端里跑：
```bash
python weather.py 北京
```
**预期输出**：
```
📍 北京
🌡 当前 28.4°C · 体感 30.1°C
💧 湿度 56%
🌬 风速 12.3 km/h
🌤 天气 大致晴朗
```
再试几个：
```bash
python weather.py 东京 # 查内置城市
python weather.py --coords 48.85 2.35 # 查巴黎坐标
python weather.py 火星 # 触发未知城市友好提示
```
只要第一条能联网返回真实数据，你的第一个 AI 协作项目就成功了。
### 5.6 常见问题与解决
| 现象 | 原因 | 解决 |
|---|---|---|
| `python: command not found` | Windows 未把 Python 加入 PATH | 重装 Python 勾选 *Add to PATH*，或用 `py weather.py 北京` |
| `获取天气失败：URLError` | 网络不通 / 公司代理 | 配置 `HTTPS_PROXY`，或换个网络 |
| 输出乱码（Windows） | 终端编码不是 UTF-8 | PowerShell 里先执行 `chcp 65001` |
| 城市坐标不准 | 经纬度精度不够 | 用更精确坐标，或走 `--coords` |
---
## 六、把工具交给 Claude 持续打磨
跑通之后别停下，这是体会 Claude Code 价值的关键环节——**用自然语言让它迭代**。回到项目目录，再次 `claude` 启动，依次给它下这些任务，观察它如何读旧代码、改代码、再验证：
1. **加功能**：「给 weather.py 增加未来 3 天的每日预报，分三行简洁输出。」
2. **美化**：「改用 `rich` 库让输出带颜色和表格；同时保留纯标准库版本为 `weather_simple.py`。」
3. **健壮性**：「加缓存——同一城市 10 分钟内重复查询不重复请求接口。」
4. **国际化**：「加 `--lang en` 选项，天气描述切英文。」
每一条它都会自主完成「改文件 → 跑测试 → 报结果」的闭环。你会真切感受到：**你从「敲代码的人」变成了「提需求 + 验收的人」**。这正是 Claude Code 改变工作方式的核心。
> **新手心法**：给任务要具体（说清数据源、依赖、输出格式、错误处理），它就少跑偏；发现它理解错了，直接说「不对，我的意思是……」纠正即可，它会基于上一版继续改，不用从头来。
---
## 整体工作流程图
下面这张图概括了从安装到产出可运行工具的完整闭环：
```mermaid
flowchart TD
A[安装 claude
原生安装器 / npm] --> B[首次启动 claude
浏览器登录账号]
B --> C[基础配置
/config 主题·权限·通知]
C --> D[cd 进入项目目录
再次启动 claude]
D --> E[用自然语言下需求
数据源·依赖·输出·错误处理]
E --> F[Claude 读项目→写代码→跑命令→看报错]
F --> G{验证通过?}
G -->|否| E
G -->|是| H[运行 python weather.py 北京]
H --> I[继续用自然语言迭代
加预报·美化·缓存·多语言]
I --> J[得到可用的天气 CLI ✅]
style A fill:#e1f5ff
style J fill:#e6ffe1
style F fill:#fff4e1
```
而工具本身的数据流也很清晰，方便你日后理解任何「调用接口的 CLI」：
```mermaid
flowchart LR
U[命令行参数
城市名 / --coords] --> P[weather.py]
P -->|urllib 拼请求| API[(Open-Meteo API
免费·无需密钥)]
API -->|JSON| P
P -->|WMO 转中文·emoji 排版| OUT[终端天气卡片]
style API fill:#fff4e1
style OUT fill:#e6ffe1
```
---
## 延伸阅读
- **官方安装与入门文档**：`docs.claude.com/en/docs/claude-code` —— 涵盖所有平台的最新安装命令与登录方式。
- **`/config` 与 settings.json**：官方「Settings」页讲透了项目级与用户级配置的每一项。
- **Open-Meteo 接口文档**：`open-meteo.com/en/docs` —— 查所有可用字段（降水、紫外线、能见度等），想加功能就翻它。
- **进阶主题（后续教程）**：学会本篇后，可继续探索 Skills（把高频操作封装成可复用技能）、MCP（接外部工具/数据源）、Hooks（让它在固定时机自动执行动作）。
---
## 训练营适用性评估
- **适合的训练营类型**：AI 编程通识训练营、企业「降本增效」数字化入门营、大学生 AI 启蒙营、零基础转码就业预科营。本篇门槛极低，作为**第 1 天的破冰课**最合适。
- **预计教学时长**：讲授 + 跟做约 **60–75 分钟**。其中安装登录 15 分钟、配置与项目初始化 10 分钟、造天气 CLI 与运行验证 25 分钟、迭代演示 15 分钟。
- **学员产出**：每人一个能跑的本地 `weather.py`，并完成至少一次「自然语言迭代」体验，形成「我能让 AI 帮我干活」的正反馈。
- **可拓展练习**：让学员把天气 CLI 改造成自己感兴趣的领域（如汇率查询、图书检索、A 股行情），用同一套「描述需求→AI 落地→验收迭代」方法论，强化迁移能力。
- **不适用场景**：纯算法 / 数据结构硬核营、需要深度工程化的高级开发营——本篇定位是「上手与建立信心」，不是工程深度。
---
## 参考来源
1. [Free Open-Source Weather API | Open-Meteo](https://open-meteo.com/) — 本教程天气数据的免费来源，无需 API 密钥，非商用完全免费。
2. [Open-Meteo API 文档](https://open-meteo.com/en/docs) — 接口字段、参数与 WMO weather code 对照表的官方说明。
3. [2026 最新｜Claude Code 安装配置教程（知乎）](https://zhuanlan.zhihu.com/p/2041851369708065290) — 涵盖 PATH、settings.json、API 接入与桌面版的中文全流程实战。
4. [Claude Code 安装与配置详细教程（CSDN）](https://blog.csdn.net/xhmico/article/details/159132449) — 高赞中文教程，覆盖 CLI 安装、登录与首次启动避坑。
5. [Claude Code 完整指南：下载→安装→配置（腾讯云开发者社区）](https://cloud.tencent.com.cn/developer/article/2699162) — 三平台安装与 Skills 加载机制，2026 最新指南。
> 本文为「Claude Code 深度使用」系列第 1 轮·入门篇，专注零基础装通并跑通首个真实项目。后续轮次将依次展开 Skills 开发、MCP 服务器、Agent 自动化与高级技巧，欢迎持续关注。
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
