发布时间：2026-07-14
标签：AI Agent｜实战｜Claude Code｜操作指南

---

目标

一次装完，后续全系列都能用：把 Python 3.13 + Node 22 + Docker + Git 基础环境装好，并在此之上装好 Claude Code，跑通一次启动登录。

读完本文，你输入 claude 就能在终端里启动一个能读代码、改文件、跑命令的 AI 工程师。模型接入（DeepSeek / OpenRouter）留到第 02、03 篇。

---

环境准备

软件	版本要求	用途
Python	≥ 3.11（推荐 3.13）	Agent 逻辑、LangGraph、MCP Server
Node.js	≥ 20（推荐 22）	Claude Code、部分 MCP 工具
Docker	最新稳定版	容器化部署 Agent（后续篇）
Git	任意新版	代码管理、GitHub 开源
Claude 账号	—	登录 Claude Code（claude.ai 免费注册）

先建一个统一工作目录，避免文件散落：

mkdir -p ~/ai-agent-lab
cd ~/ai-agent-lab

（Windows 用 mkdir ai-agent-lab 然后 cd ai-agent-lab）

---

步骤

第一部分：基础环境

1. 安装 Python 3.13

去 python.org 下载 3.13。Windows 安装时务必勾选 Add python.exe to PATH。Mac 用 brew install python@3.13。

验证 + 建虚拟环境（后续每篇复用，避免包污染）：

python --version          # 预期：Python 3.13.x
python -m venv .venv
# Windows 激活：.venv\Scripts\activate
# Mac/Linux 激活：source .venv/bin/activate

激活后命令行前面出现 (.venv) 即成功。

2. 安装 Node.js 22

去 nodejs.org 下载 LTS 22（不要选 Current）。Mac 用 brew install node@22。

node --version            # 预期：v22.x.x
npm --version

3. 安装 Docker

去 docker.com 下载 Docker Desktop，安装启动，任务栏出现小鲸鱼且状态 running。

docker --version          # 预期：Docker version 27.x.x
docker run hello-world    # 预期：输出 "Hello from Docker!"

4. 安装 Git

Windows 去 git-scm.com 默认选项安装；Mac 一般自带。

git --version             # 预期：git version 2.x.x

5. 配置国内镜像（推荐）

pip 换清华源：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Docker 换源：Docker Desktop → Settings → Docker Engine，加入后 Apply & Restart：

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

---

第二部分：安装 Claude Code

注：这里安装的为claude coded命令行版本

6. 全局安装

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

Windows 若报权限红字，用管理员身份 PowerShell 重跑。验证：

claude --version          # 预期：输出版本号，如 1.0.28

7. 启动并登录

cd ~/ai-agent-lab
claude

第一次运行会自动打开浏览器：用 Claude 账号登录授权 → 授权成功后终端出现 > 输入提示符。

不想走浏览器 OAuth，也可以用 API Key（console.anthropic.com 创建）：

# Windows：$env:ANTHROPIC_API_KEY = "sk-ant-xxxx"
# Mac/Linux：export ANTHROPIC_API_KEY="sk-ant-xxxx"

8. 最小冒烟测试

在 > 后输入：

> 列出当前目录下的文件

它会调用命令把目录内容打出来。能正常回应 = 安装 + 登录 + 运行全通。退出用 /exit。

---

验证

全部跑通 = 环境就绪：

python --version && node --version && docker --version && git --version
claude --version

再进 Claude Code 对话一句：

> 你是谁

能正常回应即达标。最终目录结构：

ai-agent-lab/
├── .venv/            # Python 虚拟环境
└── .claude/          # Claude Code 项目配置（自动生成）

---

踩坑记录

1. Windows 输入 python / claude 提示"不是内部或外部命令"
PATH 没生效。Python 重跑安装包勾 Add to PATH；claude 则跑 npm bin -g 把全局目录加进 PATH，重开终端。

2. docker run hello-world 超时拉不下来
没配镜像源或网络拦截。配上第 5 步 DaoCloud 镜像再试，仍不行切热点验证。

3. 虚拟环境激活后 pip install 装到了系统 Python
命令行前面没 (.venv)——激活没成功。重新激活，where pip（Win）/which pip（Mac）路径里应含 .venv。

4. Node 装了 Current 版，后续 MCP 工具报 EBADENGINE
严格用 LTS 22，装错就卸掉重装。

5. Claude Code 登录成功但一对话报 region / 地区不可用
Anthropic 对部分区域限制。这正是第 02、03 篇要解决的——用 DeepSeek / OpenRouter 接入，绕开官方区域。本篇先保证"能装能登"。

6. 终端中文乱码
用 Windows Terminal 替代老 cmd，或执行 chcp 65001 切 UTF-8。

---

下一步

装好了但还跑不了国产模型。下一篇接上你最需要的：

→ AI Agent 开发实战（02）：Claude Code 接入 DeepSeek

用 DeepSeek 当大脑、Claude Code 当双手，成本直接砍到官方模型的几十分之一。