环境准备(一):机器、账户与终端
本合集目录
本章目录
单册说明:本文件是「AI Agent 完整教程」卷 0 的第 3 章,可独立阅读。 前置:无(但建议先读第 2 章的七层模型,理解"为什么要装这些东西")。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 0 · 学习地图(第 3 / 6 章) |
| 前置章节 | 无(建议先读第 2 章) |
| 本章产出 | 一个干净的实验目录 ai-agent-lab + 三个配好的环境变量 |
| 对应代码 | code/check_env.py(本章末用它验证) |
| 配图 | 图 0-6(三条路线)、图 0-7(实验目录与权限) |
| 读完的判定 | 能打开终端、进入实验目录、说出三个环境变量各管什么 |
3.1 先确定路线,再决定要准备什么
同样是"学 Agent",不同路线的环境要求差别很大。先选路线,别盲目装东西。

| 路线 | 模型跑在哪 | 设备要求 | 数据是否出本机 | 适合谁 |
|---|---|---|---|---|
| 云端 API | 服务商的服务器 | 只要能上网,8GB 内存够 | 会发到服务商 | 绝大多数人,建议从这里开始 |
| 客户端 | 云端为主 | 同上,另需装一个软件 | 取决于客户端 | 想尽快用起来的人 |
| 本地模型 | 你自己的显卡 | 16GB 内存 + 8GB 以上显存 | 不出机器 | 数据敏感、断网环境、想省钱 |
建议:先走云端 API,把整条链路跑通。 本地模型是"当你明确知道自己需要它"时的选择,不是入门的第一步——它会让你在第一周就卡在显存和环境依赖上。
判断标准很实在:如果你现在连一次 API 调用都没跑通过,本地模型一定不是你的下一步。 先把云端跑通,你才知道"模型服务"这件事长什么样,后面换本地时才有对照物。
3.2 系统与硬件底线
| 项 | 最低 | 舒适 | 说明 |
|---|---|---|---|
| 系统 | Windows 10 / macOS 12 / 主流 Linux | Windows 11 / macOS 14+ | 太老的系统会遇到 TLS 与编码问题 |
| 内存 | 8 GB | 16 GB | 本地跑模型要 32 GB 起 |
| 硬盘 | 5 GB 空闲 | 50 GB | 模型文件很大,动辄 4–8 GB |
| 显卡 | 不需要 | 8 GB 显存以上 | 只有本地模型路线需要 |
| 网络 | 能访问你的模型服务 | 稳定、低延迟 | 见 3.8 代理部分 |
3.3 账户清单
必需一个:模型服务账号。选择标准只有三条——能不能连上、额度够不够、模型名是什么。
| 类型 | 特点 | 注意 |
|---|---|---|
| 海外官方服务 | 模型最全、更新最快 | 需要网络条件;按量计费,注意额度 |
| 国内官方服务 | 直连稳定、有发票、合规 | 模型名与海外不同,代码里要改 AI_MODEL |
| 聚合/中转服务 | 一个 Key 调多家模型 | 稳定性参差;不要把重要数据交给不明来源的中转 |
可选:GitHub 账号(存代码、找开源项目);客户端账号(部分客户端需要登录)。
关于密钥的一条硬规则:不要用别人的 Key,也不要把自己的 Key 发给任何人,包括发给我。 任何要求你"把 Key 贴进来测试"的场景都是风险场景。
选账号时最容易忽略的一件事:确认你拿到的模型名到底是什么。三家服务商的命名规则完全不同,同一个模型在不同平台可能叫 gpt-4o-mini、gpt-4o-mini-2024-07-18 或别的名字。这个名字就是你后面要填进 AI_MODEL 的值——填错的典型症状是 404(见 4.6 节)。
3.4 终端最小知识
后面所有命令都在终端里敲。不需要学 shell 编程,会这五个就够:
| 目的 | Windows (PowerShell) | macOS / Linux (bash/zsh) |
|---|---|---|
| 我在哪 | pwd |
pwd |
| 看目录里有什么 | ls 或 dir |
ls |
| 进目录 | cd 路径 |
cd 路径 |
| 回上一级 | cd .. |
cd .. |
| 运行 Python 脚本 | python 脚本名.py |
python3 脚本名.py |
怎么打开终端:
- Windows:开始菜单搜
PowerShell(或Windows Terminal),右键"以普通用户身份运行"即可,不需要管理员权限; - macOS:
Command + 空格搜终端,或在 VS Code 里按Ctrl + `打开集成终端。
一个必须理解的概念:路径分绝对和相对。
- 绝对路径:从根开始写全,如
C:\Users\你\ai-agent-lab(Windows)或/Users/你/ai-agent-lab(macOS); - 相对路径:相对"我现在在哪",如
inbox/notes.md、../output。
第 5 章的 Agent 会被限制只能使用相对路径,而且必须落在实验目录内——这不是多此一举,是防止它把文件写到你的系统目录里(5.3 节有实测)。
3.5 四个路径坑(都真实踩过)
| 坑 | 现象 | 处理 |
|---|---|---|
| 中文路径 | 某些工具打开项目报错、乱码、找不到文件 | 实验目录用纯英文,如 ai-agent-lab;中文只放在文件名和内容里 |
| 空格路径 | 命令被截断,报"找不到 xxx" | 路径带空格时用引号包住:cd "D:/my project" |
| CRLF 换行 | 用 Windows 写的脚本在 Linux/远端跑,报 bad interpreter 或奇怪的 \r 错误 |
编辑器里把换行设为 LF;或用 .editorconfig 统一 |
| PowerShell 执行策略 | 运行 .ps1 脚本提示"禁止运行脚本" |
不要改系统策略,改用 python xxx.py 或 .cmd/.bat 绕开 |
这四个坑的共同点是:它们在报错信息里从不直接说"是路径问题"。所以遇到"明明文件在那儿却找不到",先看路径有没有中文、空格、换行符。
3.6 密钥怎么放
密钥(API Key)本质是钱。放错地方的代价很直接:被别人拿走刷额度。
三种放法,从差到好:
| 放法 | 安全性 | 说明 |
|---|---|---|
| 直接写死在代码里 | ❌ 最差 | 一旦分享代码或传到 GitHub,等于公开 |
| 写在配置文件里并入版本管理 | ❌ 差 | 同上,历史记录里还会有 |
| 放在环境变量里 | ✅ 推荐 | 代码里只读变量名,不出现值 |
设置环境变量:
# Windows PowerShell(setx 写入用户级,永久生效,但要重开终端)
setx AI_API_KEY "sk-你的密钥"
setx AI_BASE_URL "https://api.openai.com/v1"
setx AI_MODEL "gpt-4o-mini"
# macOS / Linux(写入当前 shell 会话;要永久生效需追加到 ~/.zshrc 或 ~/.bashrc)
export AI_API_KEY="sk-你的密钥"
export AI_BASE_URL="https://api.openai.com/v1"
export AI_MODEL="gpt-4o-mini"
三个细节,错了会查很久:
setx之后必须重开终端,当前窗口读不到新值;- Windows 下不要在值里加引号后再带空格,
setx AI_API_KEY "sk-x "会把尾部空格也存进去,导致 401; - 如果你用
export但每次新开终端都失效,说明你写入的是当前会话,需要写进 shell 的启动文件。
验证是否生效:
# Windows
echo $env:AI_API_KEY
# macOS / Linux
echo $AI_API_KEY
三个变量各管什么(这张表在第 4 章会再用到):
| 变量 | 含义 | 配错的典型症状 |
|---|---|---|
AI_BASE_URL |
去哪找服务(地址) | 404 / 连不上 |
AI_API_KEY |
你是谁(凭据) | 401 / 403 |
AI_MODEL |
用哪个模型(型号) | 404 / 400 |
3.7 目录约定
本教程统一使用一个实验目录,好处是:所有代码、数据、产物都在一处,删掉就等于清零,不会污染你的电脑。

ai-agent-lab/ ← 实验根目录(LAB)
├── inbox/ ← 放待处理的东西:待整理的文件、待读的文档
│ ├── notes.md
│ └── data.csv
├── output/ ← Agent 只能往这里写
│ └── (Agent 的产物)
└── code/ ← 本教程的脚本
├── check_env.py
├── hello_model.py
└── first_agent.py
默认位置:~/ai-agent-lab(即 Windows 的 C:\Users\你的用户名\ai-agent-lab,macOS 的 /Users/你的用户名/ai-agent-lab)。想换位置,设一个环境变量 AI_LAB 即可,三个脚本都读它。
为什么把
inbox和output分开:这是权限设计,不是整理癖。第 5 章的 Agent 对inbox只有读权限,对output才有写权限。这样即使它判断错了,最坏结果也只是在 output 里多一个文件。
建目录的命令(两条选一条,任选平台):
# 方式一:让脚本帮你建(推荐,连演示数据一起准备)
python first_agent.py --setup
# 方式二:手工建
mkdir -p ~/ai-agent-lab/inbox ~/ai-agent-lab/output ~/ai-agent-lab/code
3.8 代理与网络
能直连就不走代理。只有在确认直连不通时,才配代理,否则会引入新的变量(很多"连不上"其实是代理配错)。
# Windows PowerShell
setx HTTPS_PROXY "http://127.0.0.1:7890"
setx HTTP_PROXY "http://127.0.0.1:7890"
setx NO_PROXY "localhost,127.0.0.1,api.weixin.qq.com"
# macOS / Linux
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"
两个坑:
- 端口写错:7890、7897、1080、10809 是不同软件的不同默认端口,别照抄。看你代理软件里写的"混合端口/HTTP 端口"是多少;
NO_PROXY没设:本地服务和某些国内接口被强行绕进代理,表现为"明明没墙却连不上"。本地地址一律加进NO_PROXY。
验证方法(比 ping 有用):
curl -I https://api.openai.com/v1/models
- 返回
401→ 网络是通的(只是没带密钥),这是好消息; - 返回
000/ 超时 / 证书错误 → 网络层有问题,先解决网络,别改代码。
为什么
401是好消息:它证明你已经和服务端握上手了,只是没出示凭据。而000说明连话都没说上。这两种情况的排查路径完全不同——这个判断法在第 4 章会展开成一张四步定位图。
3.9 本章验收 + 排错表
验收(应当会):
- 应当会打开终端,用
cd进入你的实验目录,并说出当前路径; - 应当会设置并验证三个环境变量(
AI_API_KEY/AI_BASE_URL/AI_MODEL); - 应当会解释为什么密钥不能写进代码,以及为什么 inbox 和 output 要分开。
排错表:
| 症状 | 最可能原因 | 修法 |
|---|---|---|
python 不是内部或外部命令 |
未安装或未加入 PATH | 装 Python 3.9+,安装时勾选 "Add to PATH" |
setx 后读不到变量 |
没重开终端 | 关掉窗口重开 |
echo $AI_API_KEY 有值但脚本报 401 |
值里带空格/引号/换行 | 重新 setx,值不要带引号,别多敲空格 |
| 中文目录下脚本报编码错误 | 路径含中文 | 换纯英文目录 |
curl 返回 000 |
网络/代理/DNS | 先直连试,再配代理;用 --noproxy "*" 排除代理干扰 |
证书错误 CERTIFICATE_VERIFY_FAILED |
代理做了证书拦截、系统时间不对 | 系统时间校准;代理放行该域名;必要时换直连 |
3.10 下一步
环境打底完成,接着打通三条链路 → 第 4 章 环境准备(二):三条链路打通
回看:第 2 章 七层模型 · 返回导读