在服务器上跑 Claude Code / Codex 这类 CLI Agent，最烦的两件事：

1. SSH 一断，会话就没了。 用 nohup / screen / tmux 能挂后台，但下次回来还得找半天哪个 pane 在跑什么。
2. 手机上没法操作。 出门在外想继续给 Agent 派活、批权限、看结果，纯 SSH 客户端体验很差。

之前的方案是 tmux + Claude Code，能恢复会话，但手机上仍只能敲命令行。这次试了 Herdr + Happy 的组合，把「终端会话保持」和「手机端 Agent 控制」分开解决：

• Herdr：Rust 写的终端多路复用器，专注管理 Agent 会话，自带左侧 Agent 状态栏、分屏、跨 SSH 断开恢复。
• Happy：给 Claude Code / Codex 套一层 wrapper，把会话同步到手机 App，可以远程发消息、批权限、看 diff。

架构大致是：

Herdr Pane
   └── happy claude
          └── Claude Code
                ↕
           Happy 手机 App

下图是 Herdr 的界面，左侧是多个 Agent 区域，中间是 Agent 的展示区域：

这是 Happy 的 App 页面，可以看到同一个 Claude Code 会话已经同步到手机，底部能直接发消息：

安装

一、安装 Herdr

在 Ubuntu 服务器上（先 SSH 登录）：

curl -fsSL https://herdr.dev/install.sh | sh

重新登录，或者：

source ~/.profile

验证：

herdr --version
which herdr

如果提示找不到命令，直接把 ~/.local/bin 加进 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
source ~/.profile

Herdr 是单个 Rust 二进制，支持 Ubuntu x86_64 和 ARM64，不需要 Docker，也不用单独装数据库。

二、确认 Claude Code 已安装

Herdr 不自带 Claude Code，只是管理终端和 Agent。

claude --version

还没登录的话直接运行 claude 按提示授权。你自己原来的 API / 模型配置不受影响，Herdr 不会改变模型或 API 地址。

Codex 同理：codex --version。

三、安装 Agent 集成

Claude Code 跑过、生成了 ~/.claude 目录之后：

herdr integration install claude
# 用 Codex 的话
herdr integration install codex

herdr integration status

集成主要用于保存 Claude/Codex 的 Session ID，服务器或 Herdr 重启后可以恢复原对话。

四、安装 Happy

Happy 要求 Node.js 20+：

node --version
npm install -g happy

happy --version
happy doctor

npm 包现在叫 happy，旧教程里的 happy-coder 已迁移。

登录并绑定手机：

happy auth login

然后在手机装 Happy App（iOS / Android 都有），按终端里的二维码或登录提示完成绑定。

使用

启动 Herdr

进入项目目录：

cd /你的项目目录
herdr

Herdr 会自动拉起后台 Server、创建默认 Workspace、打开终端界面。

在 Herdr 里启动 Happy 包装的 Claude

关键步骤：不要直接运行 claude，而是用 HERDR_AGENT 环境变量 + happy 启动：

HERDR_AGENT=claude happy claude

Codex 用：

HERDR_AGENT=codex happy codex

HERDR_AGENT 是 Herdr 官方给 Wrapper / 沙箱程序准备的识别提示——告诉 Herdr「虽然前台进程叫 happy，但请按 claude 识别」。少了这个变量，左侧 Agents 栏会是空的（Herdr 看到的前台程序是 happy，不在它的 Agent 列表里）。

为了方便，在 ~/.bashrc 里加两个别名：

alias hclaude='HERDR_AGENT=claude happy claude'
alias hcodex='HERDR_AGENT=codex happy codex'

之后直接 hclaude 就行。

恢复之前的 Happy 会话：

happy daemon list
HERDR_AGENT=claude happy resume <Happy会话ID>

常用快捷键

断开 SSH 但保持运行

不要用 exit 结束 Claude，直接按 Ctrl+B 然后 Q。退出 Herdr 界面后关掉 PuTTY/SSH 窗口即可——

• PuTTY 关了
• Herdr Server 继续在跑
• Happy / Claude Code 继续在跑
• npm run dev 之类的开发服务也继续在跑

下次重新 SSH 上去（必须用启动 Herdr 时的同一个 Ubuntu 用户），执行 herdr，就回到原来的界面。

手机访问

手机装 Happy App，登录同一账号，就能看到所有通过 happy claude 启动的会话，可以：

• 继续给 Claude 发任务
• 同意 / 拒绝权限请求
• 查看代码变更
• 接收「完成 / 等待确认」通知
• 在手机和终端之间切换控制权

Happy 默认走官方中继服务器同步，手机不需要连家里内网；官方称会话端到端加密。不想让流量经过第三方的话，可以后续自建 Happy Server。

踩过的坑

1. Herdr 左侧 Agents 栏看不到 Happy 里的 Claude

现象：在 Herdr 里跑 happy claude，左侧 Agents 是空的。

原因：Herdr 原生只识别 claude、codex 这些命令本身，运行 happy claude 时它看到的前台进程是 happy，不在支持列表里。

排查：

pgrep -af 'happy|claude|codex'
herdr agent list

能看到 happy/claude 进程、但 herdr agent list 为空，就确认是包装进程遮挡。

解决：用前面提到的 HERDR_AGENT=claude happy claude 启动。

需要注意：即便这样，手机端把会话切到远程模式后，Herdr 状态栏里的 working/blocked 状态可能偶尔不准——Herdr 和 Happy 没有官方直接集成，只能根据终端内容推断。手机控制本身不受影响。

2. Happy 不能接管已经在跑的 claude 进程

如果你先在 Herdr 里直接运行了 claude，事后是没法让 Happy 无缝接管这个进程的——它没经过 Happy wrapper。必须从一开始就用 happy claude 启动。

3. 家用服务器别把 SSH 22 端口直接暴露公网

如果服务器在家里，外出时先连 WireGuard，再访问内网 IP。SSH 直接暴露公网被扫是家常便饭。

常用管理命令

herdr status              # Herdr 状态
herdr agent list          # Agent 列表
herdr integration status  # 集成状态
herdr update              # 更新 Herdr
herdr server stop         # 真正停掉所有窗口和 Agent（慎用）

最后一条会结束 Pane 里正在运行的 Claude / Codex / 开发服务器，正常使用别执行。

总结

这套组合下来，我的分工是：

• Herdr：多项目状态总览、终端分屏、跨 SSH 断开的会话保持
• Happy：手机端操作 Claude、收通知、批权限
• 测试、日志、开发服务器：跑在 Herdr 的其他 Pane 里

相比之前的 tmux 方案，最大提升是手机上能真正「用」Agent 了，不只是「看」Agent。代价是多了一层 Happy 中继，介意的可以自建 Happy Server。

上礼拜一个做技术的朋友问我："你们搞的这个 Claude Code 多 agent，到底是个啥？我看网上又是 agent teams 又是 workflows 的，还有人说必须上 Claude Opus 才能跑，Kimi K3 行不行？"

我想了想，这事一句话说不清楚，干脆写篇文章统一回复。

先说结论：学会多 agent 的最好方式，是亲手做一个真项目。你看十篇教程，不如跟着我把一个真实项目搭一遍。这篇文章我拿一个已经跑通了的真实案例来讲——一套"四 agent + wiki 协作"的项目初始化体系，你跟着做一遍，agent teams、workflows、ultracode 这些概念自然就明白了。

1 三个概念，一句话说清

先把术语掰扯清楚，不然后面全是糊涂账。

1.1 Agent Teams：一群 AI 分工干活

一个人干项目，需求、设计、开发、测试、上线全包，累不说，还容易顾此失彼。Agent Teams 就是把这个"一个人"拆成"一队人"：

我实际项目里的配置：

• pm agent：管需求，写需求文档，评审设计是否符合需求
• developer agent：管设计和写码，写设计文档，过评审后写生产代码
• tester agent：管测试，写用例，跑测试，打回不合格代码
• releaser agent：管上线，走安全审核清单，写上线记录

这四个 agent 不是随口说说，是真的在 .claude/agents/ 下各建一个 .md 文件，写清楚职责边界。比如 tester 的边界就是"不改生产代码，测试失败只能写证据打回，不能顺手修"。

1.2 Workflows：给 AI 排好 SOP

光有分工还不够，还得有流程。Workflows 就是规定"谁先干、谁后干、怎么交接"的 SOP。

我项目里的核心流程是一条状态机：

讨论中 → 待评审 → 已批准 → 设计中 → 设计评审中 → 开发中 → 测试中 → 待上线 → 已上线

每个状态对应"下一步谁干什么"：

这个流程写在 wiki/workflow.md 里，是主会话和 4 个 agent 的共同契约。

1.3 Ultracode：多模型混编作战

很多人以为跑 agent teams 必须全上 Claude Opus，其实不用。Ultracode 的思路是"谁的活儿给谁"——主会话（编排器）用 Claude，子 agent 按任务类型选模型。

我实际项目里 UI 测试就指定了 Kimi K3：

tester agent 定义里写死：主会话派 UI 测试单时指定 model: claude-sonnet-kimik3，因为 Kimi K3 是多模态模型，能直读截图复核视觉细节；纯后端测试就不限定模型。

这就是 ultracode 的核心逻辑：主模型负责编排和判断，子模型按能力混编。

2 什么时候该用，什么时候别瞎折腾

不是所有人都需要上多 agent，我见过有人把"写一个 Hello World"都拆成三个 agent，纯属脱裤子放屁。

2.1 三种该用的场景

1）任务可拆解，且质量要求高

比如开发一个新功能，需求、设计、编码、测试、上线每个环节都有明确产出物，且产出物质量直接影响下游。我项目里一个 REQ 从讨论到上线，要走完 8 个状态，每个状态都有产出物：需求文档、设计文档、测试用例、结果报告、上线记录。

2）需要多角色评审，防单一视角盲区

设计文档为什么要 pm+tester 双评审？因为 pm 只看"是否符合需求意图"，tester 只看"可测性+边界覆盖"。一个人看容易漏，两个人交叉看才能兜住。

3）有标准流程，且需要留痕追溯

上线这事不能马虎。我项目里 releaser 必须走 deploy skill 的安全审核清单：密钥、日志泄密、注入、存储写路径、依赖、文档同步，六项逐项过，缺一项就打回。这个流程不标准化，早晚出事故。

2.2 三种不该用的误区

1）任务太简单

改个错别字、调个样式，直接干就完了，走全流程纯属浪费。所以我项目里有"简轨"机制：单模块小改、bug 修复、配置文档类改动，跳过设计文档和设计评审，直接进开发。简轨只豁免设计环节，测试和上线审核永不豁免。

2）上下文太短，信息密度低

一个 50 行脚本能解决的事，拆成 agent 反而增加沟通成本。agent 之间靠 wiki 文件交接，每个交接都有读写开销。

3）成本敏感且非关键路径

多 agent 意味着多轮 LLM 调用。我项目里一个全轨 REQ 走完，pm、dev、tester、releaser 加起来十几轮调用。如果是非核心功能，或者预算紧张，直接单 agent 干就完了。

3 实战项目：四 agent + wiki 协作体系

下面讲真东西。这是我一个真实项目里跑通的体系，你跟着做一遍就明白多 agent 怎么玩了。

3.1 项目背景与需求拆解

这个项目要解决什么问题？一句话：让 Claude Code 在任何新项目里，按手册一步步搭出"主会话编排 + 四 agent + wiki 驱动"的协作体系。

需求拆解成 8 步：

1）建目录骨架：wiki/、logs/、.claude/agents/、.claude/skills/
2）写 4 个 agent 定义：pm、developer、tester、releaser
3）写协作 SOP：wiki/workflow.md
4）写文档骨架 + 模板：readme、四份模板、看板、经验汇总
5）写 skills + 脚本 + settings 改造
6）写项目级 CLAUDE.md
7）按项目扩展（全新项目 vs 已有项目两条路径）
8）验收：跑脚本 + 模拟一个 REQ 走通全流程

前 6 步是机械搭建，第 7 步才需要动脑子——读新项目实际代码，把现状逆写进 wiki。

3.2 怎么设计 agent 分工

四个 agent 的定义文件，每份都有 frontmatter 和职责边界。以 developer 为例，关键设计：

---
name: developer
description: 开发 agent。根据已批准需求先写设计文档并接受评审，评审通过后写生产代码。不跳过设计评审直接写代码——除非派单注明「简轨」。
tools: Read, Write, Edit, Glob, Grep, Bash
---

注意两个设计点：

• description 里写明例外："除非派单注明简轨"。这是给主会话看的，告诉它什么时候可以跳设计。
• tools 明确限制：developer 有 Bash 能跑测试，但没有 WebFetch，防止它跑偏去查外部资料。

职责按严格顺序写死：

1. 设计（全轨）：读需求 → 写设计文档 → 看板翻「设计评审中」→ 停下来等评审
2. 修订：评审打回 → 按意见修订 → 等复审
3. 开发：评审通过 → 写生产代码 → 自测 → 看板翻「测试中」
4. 经验沉淀：上线后回填设计文档 §8 + experience.md

边界条款是防越权的第一道闸：

- 评审通过前不写生产代码（唯一例外是简轨）
- 不改 wiki/pm/ 的需求内容、不写 wiki/tests/、不写 wiki/release/
- 发现需求本身有问题 → 打回给主会话，不擅自扩大或缩小范围

3.3 workflow 怎么排

workflow 的核心是状态机，但有两个关键设计值得单独说。

第一，简轨与全轨的分叉。

不是所有需求都值得走全流程。主会话在「已批准」时先判轨道：

这个设计解决了"流程太重"的痛点。我项目里 60% 的 REQ 走简轨，省掉了设计文档和两轮评审，但测试和上线审核一个不少。

第二，讨论区与经验沉淀。

需求讨论期的草稿放 wiki/discuss/，结论一出即流向正式文档或删除，执行完不留痕。这是防止"草稿堆积"的机制。

经验沉淀分两级：

• 每个 REQ 上线后，developer 回填设计文档第 8 节「经验与教训」
• 可复用的一行经验追加到 wiki/dev/experience.md，供改代码前快速检索

这个设计让团队知识不随项目结束而流失。

说到经验沉淀，我想起 2018 年做摄像机项目时，团队里有个老工程师离职，带走了红外遥控协议的所有踩坑记录，新接手的兄弟又重新踩了一遍，光 38kHz 载波频率就调了三天。从那以后我就明白：经验不沉淀，等于团队在白干。这套 wiki + experience.md 的机制，就是给 AI 团队也装上"经验不落地"的保险。

3.4 跑出来的效果与踩过的坑

这套体系在我项目里跑了 20+ 个 REQ，效果：

• 需求平均交付周期从 3 天降到 1.5 天（简轨的功劳）
• 上线事故率降为 0（releaser 安全审核清单的功劳）
• 文档与代码漂移率大幅降低（my-check skill + freshness 脚本的功劳）

踩过的坑也不少：

1）agent 越权改文件

边界条款靠指令约束，无法强制封锁。有一次 developer 顺手改了 tester 的用例文件，被 code review 抓到。后来加了条款：发现越权行为应纠正并回报用户，严重时在 agent 定义里补针对性条款。

2）UI 测试截图存证难

脚本测试能验证接口契约，但页面渲染对不对，脚本说了不算。后来给 tester 加了 browser-test skill，用 headless Chrome 实测并截图。Chrome 二进制固定在 tests/third_party/chrome/，版本与 chromedriver 配套。

3）多模型混编的上下文一致性

Kimi K3 和 Claude 混编时，发现 Kimi 对某些 prompt 结构的理解有偏差。解决办法：主会话派单时，给 Kimi 的 prompt 更结构化，关键信息用列表而非段落。

4 模型选择：Kimi K3、GLM 5.3 能不能用？

这是最多人问的问题。我特意去查了最新官方文档（2026-09-06 时点），给你列个明白账。

4.1 当前可用模型状态

数据来源
Kimi 平台文档：platform.kimi.ai/docs（2026-09-06 时点）
Z.ai 文档：docs.z.ai/guides/llm/（2026-09-06 时点）
GLM 5.3 在 Z.ai Code Bench 达 34.5%，超过 Claude Opus 4.8，低于 Claude Fable 5

4.2 怎么混编：主 agent 用 Claude，子 agent 按能力选

我的配置原则：

1）主会话（编排器）用 Claude Opus

编排器要判断状态机流转、拆解任务、裁决评审分歧，这些都需要强推理能力。Claude 在这方面最稳。

2）子 agent 按任务类型选

• developer：编码任务可用 GLM 5.3 或 Kimi K2.7 Code，实测 GLM 5.3 在 Terminal-Bench 3.0 达 28.3，比 GLM 5.2 的 4.6 提升 6 倍
• tester：UI 测试指定 Kimi K3（多模态，能看截图）；纯后端测试不限定
• pm/releaser：文档和审核任务，Claude Sonnet 即可

3）混编注意事项

• 不同模型对 prompt 结构的理解有差异，派单 prompt 要结构化
• 上下文窗口要匹配任务长度，1M 窗口的模型适合长文档分析
• 价格差异大，高频调用的子 agent 可用性价比更高的模型

4.3 一个实际配置示例

我项目里 .claude/settings.json 的权限白名单按技术栈配，Python 项目加 Bash(python3:*)、Bash(pytest:*)，Node 项目加 Bash(npm:*)。这是减少权限询问打断的关键。

PostToolUse 钩子注册 remind-doc-sync.sh，代码文件被编辑后自动提醒同步 wiki。这是防文档漂移的兜底机制。

==多 agent 不挑模型，挑的是分工==

5 保姆级上手步骤

废话不多说，跟着做。

5.1 准备工作

1）安装 Claude Code（略）
2）准备一个 git 仓库（新项目 git init，已有项目直接进）
3）在项目根目录启动 Claude Code

5.2 初始化四 agent 体系

把整个初始化手册交给 Claude Code，说"按这份手册初始化项目协作体系"。手册里包含每一步要创建的文件的完整内容，全部去业务化。

这份手册我沉淀成了模板，放在项目 wiki 的 design 目录下，已去业务化。你拿去就能用，占位符用 <尖括号> 标注，替换成你项目的真实信息即可。手册核心内容我在第 3 节已经拆解过了，跟着做就行。

如果你只要最小可用版本，手动建这几个文件：

mkdir -p wiki/{discuss,pm,dev,tests,release,templates} \
         .claude/agents .claude/skills

然后逐个创建：

• .claude/agents/pm.md
• .claude/agents/developer.md
• .claude/agents/tester.md
• .claude/agents/releaser.md
• wiki/workflow.md
• wiki/pm/to-do.md

每个文件的内容按我第 3 节讲的思路写，关键是职责边界和状态机。

5.3 跑通第一个 REQ

模拟一个需求走全流程：

1）在 wiki/discuss/ 建草稿，跟主会话讨论
2）派 pm 升格为正式需求文档
3）主会话判轨道（简单需求走简轨）
4）派 developer 开发
5）派 tester 测试
6）派 releaser 上线
7）developer 回填经验

跑通后删掉模拟文件，看板清零。

5.4 常见问题排查

最后

回到开头那句话：学会多 agent 的最好方式，是亲手做一个真项目。

这篇文章给你的不是理论，是一套我跑通了的完整方案。你拿去初始化一个新项目，或者改造一个已有项目，跟着状态机走一遍，agent teams、workflows、ultracode 这些概念就全活了。

别光看，动手做。做完一个 REQ，你就明白我在说什么了。

如果你在做过程中卡住了，或者跑出了更好的经验，欢迎回来交流。这套体系不是终点，是起点——你完全可以根据项目特点加 agent、改状态机、换模型组合。工具是死的，用法是活的。

这两天随便打开一个技术群、X、小红书，满屏都是 Qwen3.8-27B。我手边没有单卡 80G 的机器，没法立刻拉下来跑一轮自己的 benchmark，但这不妨碍把它从架构、科普、部署、实测到趋势一次性捋清楚。毕竟评测不是只有"我亲自跑了"这一种写法，把别人跑出来的数和官方卡摆在一起，照样能看明白。

这周圈子里被 Qwen3.8-27B 刷屏刷到反胃。同期智谱在 6 月放的 GLM-5.2（753B 的后训练对话版）几乎没溅起水花。并不是它不行，是 753B 只能挂云端，普通人摸不着。大家兴奋的点出奇一致：不是"又出了一个更大的"，而是"这个我能搬回家自己跑"。

这里有个反常识的细节值得先点出来：Qwen 这一代其实同时发了更大的 Qwen3.8-2.4T-A95B——总参数 2.4 万亿、激活 95B 的 MoE 巨兽。但刷屏的不是它，是 27B。原因可以归纳成一句话：

大模型真正的分水岭不在参数天花板，而在能不能搬回家。

2.4T 那个只能挂云端，普通玩家摸不着；27B 这个量化一下能塞进一张消费级显卡。所以本文就围绕这个"能搬回家"的 27B 展开。

2 Qwen3.8-27B 到底是个什么模型

2.1 关键参数一表看清

几个注意点：

• Gated DeltaNet + Gated Attention 混合架构。这不是纯 Transformer，而是把线性注意力（DeltaNet）和标准注意力按 16:1 的比例混着用。好处是长上下文省显存，256K 原生上下文能落地，架构本身功不可没。
• 原生多模态。支持图文、视频，这点对本地玩家很关键：一个模型顶过去"语言模型 + 视觉模型"两套，比如DeepSeek和GLM因为都只支持文本模型，在问答、Agent支持上还需要单独对接一个视觉模型，兼容性不好。
• 思考模式可关。默认开思考，按请求关；还能用 reasoning_effort 调推理深度。等于一个模型既能当快思考的对话助手，也能当慢思考的推理机。

2.2 为什么这次火的是 27B，不是 2.4T

把同代两个型号摆一起，逻辑就清楚了：

MoE 的坑就在这：总参 2.4T 听着吓人，激活 95B 看着也还行，但所有专家的权重都得载进显存，如果不量化的话，大概需要 4800G显存（大概需要60 个 H100 显卡，每张 80G 显存），就算是量化到INT4，也需要1200GB显存（大概15 个 H100）。激活省的是算力不是显存。结果就是算得动，但装不下。普通人根本没机会本地部署，自然没"火花"。

27B Dense 反过来：参数不大，全激活，量化到 INT4 权重只要约 14GB，一张 RTX 4090/5090 就能塞下。能被普通人亲手跑起来的模型，才有刷屏的资格。

3 科普扫盲：跑一个大模型到底在烧什么

有很多同学可能还不太清楚大模型的一些基本词汇，这里给没怎么碰过本地部署的同学补底子。很多人看到"27B、FP8、MoE、vLLM"就头大，其实拆开就四件事：精度、架构、引擎、显存。

3.1 模型精度：BF16 / FP8 / INT4 差在哪

精度就是"每个参数用多少 bit 存"。bit 越少，显存越省，但精度损失越大。

经验法则：BF16 是原汁原味，FP8 是性价比之王，INT4 是消费级的救命稻草。Qwen3.8-27B 官方直接给了 FP8 版，且声明性能与原版几乎一致——对本地玩家来说，FP8 就是首选，不用自己再量化。

那是不是越省越好？

不是。显存省的是空间，质量亏的是脑子。可以想象一下，一个参数，如果是BF16，则是用65535的长度表示，如果是INT4，那只有128来表示，量化以后，以小模型检测为例，人形位置可能会波动，精度损失在闲聊里看不出，在硬任务上肉眼可见：

总结：
1）简单任务看不出，硬任务见真章。闲聊 INT4 和 BF16 没区别，但跑 SWE-bench 那种真实改代码，分数会掉几个点。
2）量化方法决定损失下限。AWQ/GPTQ 是"聪明量化"，护住关键权重；暴力 RTN 四舍五入损失最大。GGUF Q4_K_M 是混合精度（重要层多给 bit），所以比纯 INT4 稳——这也是它平均 ~4.5bit 而非纯 4bit 的原因。
3）官方量化 > 社区量化。Qwen3.8-27B 的 FP8 是官方调过的，敏感层（attention 等）保高精度，所以敢说"几乎无损"；INT4 多半是社区后做的，没官方背书，质量看具体仓库。

所以选型是道匹配题：闲聊翻译省事用 INT4，代码数学跑 Agent 用 FP8，做基准评测要原汁原味用 BF16。Qwen3.8-27B 官方把 FP8 这道甜点做好了，本地玩家没理由不先用，INT4 是 24G 消费卡装不下 FP8 时的退路，不是首选。

3.2 Dense 还是 MoE，凭什么 Dense 这次赢麻了

先把两个词说人话：内存 vs 显存

很多人混着用"内存"和"显存"，本地部署里这俩天差地别。

1）内存（RAM）：电脑主板上那根内存条，容量大、便宜、但慢。常见 16/32/64GB，CPU 使用，一般通过PCIE连接。
2）显存（VRAM）：焊在显卡上的专用存储，容量小、贵、但极快。游戏卡 8–24GB，专业卡 48/80GB；一张 RTX 4090 的 24GB 显存就要一万多，H100 的 80GB 显存十万级。GPU 用它。

大模型推理主要靠 GPU 现炒现卖，所以模型权重必须放进显存里，不是内存。你内存插到 256GB 也没用，因为GPU 从内存取数据要绕 PCIe 走，慢几十倍，等于让大厨跑仓库拿料，菜早凉了。

一句话
内存是大仓库，显存是灶台。模型推理要现炒现卖，料必须在灶台上，放仓库里现搬来不及。

这就是为什么本地玩家盯着显存看、不看内存——显存比内存金贵十倍，也小十倍，这才是真正的瓶颈。

Dense 和 MoE 到底差在哪

• Dense：一个全才医生，所有本事都在脑子里。看任何一个病人，全部知识一起上。27B 参数全在显存里，用多少占多少，简单粗暴。
• MoE：一座医院，养着上百个专科专家。每次看病只请其中几个出诊，所以"激活"小、算得快。但问题是：所有专家都得在医院里候着，因为来什么病人事先不知道，专科医生不能临时叫。结果就是激活省了、驻留没省。

一句话记住：MoE 省的是算力（出诊的人少），不省显存（候诊的人一个没少）。

为什么 MoE 在本地放不下

拿这次同代的两个型号算笔账（BF16，每参数 2 字节）：

2.4T 的坑就在这：就算每次只激活 95B（出诊的医生少），2.4T 全部权重（所有医生）都得驻留显存，2.4万亿 × 2 字节 ≈ 4800GB。单张卡 80GB，要 60 张才装得下，这不是个人玩家的事，是数据中心的事。激活小只让它算得动，没让它装得下。

算力 vs 显存，哪个是生死线

本地部署有两条约束，分量完全不同：
1）算力不够：推理慢，每秒吐 5 个字。能忍，等就是了。
2）显存不够：直接 OOM（out of memory），模型压根加载不进来，一个字都吐不出来。直接出局。

所以本地化第一关是"装得下"，不是"跑得快"。本地化的天敌不是算力不够，是显存装不下。这就是 27B Dense 能火、2.4T MoE 火不起来的根因——27B 量化后塞进一张消费卡，2.4T 量化十倍也还是数据中心专属。

但"Dense 赢 MoE"只在独显场景成立
上面说的是独显（显存=小容量 VRAM）的情况。换到统一内存一体机（DGX Spark / Mac Studio / AMD Ryzen AI Max+395，显存=内存、容量上百 GB），结论反过来：中等 MoE（如激活 5.1B 的 Ling-3.0-flash）激活小、读得少，反而比 Dense 快得多——实测单机 35 tok/s vs 27B Dense 的 4.37 tok/s（详见 5.2）。一句话：独显小显存选 Dense，大统一内存选 MoE。

3.3 推理引擎：vLLM / SGLang / llama.cpp 怎么选

一句话选型：要对外服务选 vLLM，要跑 Agent 选 SGLang，只有一张游戏卡选 llama.cpp，要改模型本身才上 Transformers。

3.4 显存占用：27B 到底要吃多少卡

下面这张表是我按"权重显存 = 参数量 × 每参数字节"算的理论值，再加 KV cache 余量估的（实际还看上下文长度和并发）：

注意 FP8 的尴尬：27GB 权重对大多数消费卡偏大。但有个特例——RTX 5090 是 32GB GDDR7，是消费级里唯一能装下官方 FP8（27GB）、跑近乎无损精度的卡。4090（24GB）装不下 FP8，得退到 INT4 或 GGUF。这个细节很多刷屏帖没讲清，容易让人按老经验以为消费卡都只能 INT4。

4 怎么部署：HuggingFace 和魔塔社区两条路

4.1 拉模型

国内推荐走魔塔社区（ModelScope），速度快不用梯子；海外或要最新版走 HuggingFace。

HuggingFace：

pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3.8-27B-FP8 --local-dir ./Qwen3.8-27B-FP8

魔塔社区（ModelScope）：

pip install modelscope
modelscope download --model qwen/Qwen3.8-27B-FP8 --local_dir ./Qwen3.8-27B-FP8

先下 FP8 还是 BF16？
本地玩家直接下 Qwen3.8-27B-FP8。BF16 原版 54GB 起步，没专业卡别折腾；FP8 官方量化、近乎无损、还自带各引擎示例，性价比最高。

4.2 起服务

vLLM（最常用，OpenAI 兼容 API）：

pip install vllm
vllm serve "Qwen/Qwen3.8-27B-FP8"

调用：

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  --data '{"model": "Qwen/Qwen3.8-27B-FP8", "messages": [{"role": "user", "content": "用一句话介绍你自己"}]}'

SGLang（跑 Agent / 复杂调度）：

pip install sglang
python3 -m sglang.launch_server --model-path "Qwen/Qwen3.8-27B-FP8" --host 0.0.0.0 --port 30000

Transformers（调试 / 研究）：

from transformers import pipeline
pipe = pipeline("image-text-to-text", model="Qwen/Qwen3.8-27B-FP8")
messages = [
    {"role": "user", "content": [
        {"type": "image", "url": "https://example.com/photo.jpg"},
        {"type": "text", "text": "这张图里是什么？"}
    ]}
]
print(pipe(text=messages))

推理参数官方也给了建议，直接抄：

• 思考模式：temperature=1.0, top_p=0.95, top_k=20
• 非思考模式：temperature=0.7, top_p=0.80, presence_penalty=1.5

4.3 消费级硬件的退路：GGUF 量化

只有一张消费卡（4090 24G / 5090 32G）或干脆纯 CPU 跑，就走 llama.cpp + GGUF。GGUF 版通常由社区（如 bartowski、unsloth）出，命令：

# 拉社区 GGUF（具体仓库名以 ModelScope/HF 搜索为准）
huggingface-cli download bartowski/Qwen3.8-27B-GGUF --include "*Q4_K_M*" --local-dir ./gguf

# 起服务
./llama-server -m Qwen3.8-27B-Q4_K_M.gguf -ngl 99 -c 32768 --port 8080

-ngl 99 把层全卸到 GPU，-c 32768 给上下文。纯 CPU 就把 -ngl 调小甚至 0，靠内存扛，慢，但能跑。

5 实际测试：能力与速度的数据

5.1 官方基准（有出处，含横向对比）

数据来源：HuggingFace Qwen/Qwen3.8-27B 官方模型卡。

几个直观解读：
1）SWE-bench Pro 61.7 不只是真能改代码——它把闭源的 Opus4.6 Max（53.4）按在地上摩擦。27B 开源反超闭源旗舰，放两年前不敢想。
2）OSWorld-Verified 84.3 和 AndroidWorld 81.9 说明它能当 Agent 操作电脑和手机，这是官方强调"长期代理任务"的底气，且远超上一代 27B（63.9 / 70.3）。
3）MathVision 94.6 印证多模态不是噱头，看图做数学题接近满分。
4）唯一没拿第一的是 GPQA Diamond（89.2 vs Opus 91.3），科学推理还差闭源一点——但差距已经很小。

5.2 实测数据：真实 DGX Spark 基准

数据来源
本节数据引自 Lonely__MH《大模型本地部署完整指南》（2026-08-17）。原文主角是蚂蚁百灵 Ling-3.0-flash，Qwen3.8-27B 作为参照模型进行单机压测。我提取了 Qwen3.8-27B 的关键数字，并结合我的带宽分析加以解读。

硬件与模型配置

实测吞吐与延迟

为什么只有 4 tok/s？带宽是罪魁祸首

原文原文一句话点破天机：

55.6GB 权重访存瓶颈——由于 Qwen3.8-27B 为 27.8B 全激活全精度模型，每步解码需搬运全部 55.6 GB 权重，受限于单机内存带宽，其吞吐构成了衡量 MoE 稀疏能效比的黄金基线。

这个 4.37 tok/s 和我前面的带宽公式完全对上：

• 55.6 ÷ 4.37 ≈ 12.7 TB/s（并发后有效带宽）
• 但单并发时，DGX Spark 的统一内存带宽（~几百 GB/s）远低独显，被 BF16 全量压垮，所以只有 4 tok/s。

这印证了我的判断：低带宽 + BF16 = 极慢，MoE 激活小是优势（Ling-3.0-flash 单并发 35 tok/s，是 Qwen3.8-27B 的 8 倍）。

给本地玩家的启示

1）DGX Spark 是"能装下"但"不算快"。121.6GB 统一内存能塞下 BF16，但带宽被统一内存拖垮，decode 慢。适合"能跑、不用等"的离线任务，不适合实时对话。

2）MoE 在统一内存上反而赢麻了。Ling-3.0-flash（124B 总参，5.1B 激活）单机 35 tok/s，是 Qwen3.8-27B 的 8 倍，这验证了我第 3.2 节的判断：MoE 省算力不省显存，但在"显存就是内存"的统一内存机器上，激活小直接转化为快。

3）消费级玩家别指望 BF16。想快要么上高带宽独显（5090 的 FP8，~85 tok/s 理论值），要么走 MoE 路线。

6 趋势预判：大模型本地化这件事，已经不可逆了

把时间线拉长看，这件事其实不新鲜。历史反复在演同一个剧本：

1990 年代，计算机是机房里的大家伙，普通人摸不到。后来 PC 普及，算力搬进了家。
2010 年代，智能语音、图像识别都在云端。后来手机 NPU 起来，端侧能跑了。
2026 年，大模型正站在同一个拐点上——从"只能调 API"到"能塞进一张显卡"。

Qwen3.8-27B 刷屏，本质是这个拐点到了的信号弹。几条具体判断：

1）27B 会成为本地部署的甜点档。再小（7B 级）能力不够看，再大（70B+）消费级装不下，27B 量化后正好卡在 24G 卡的舒适区。
2）电脑的下一个标配可能是"能跑大模型的显卡"。就像当年独立显卡为了游戏普及，下一轮可能是为了本地大模型。买电脑看显存会变成常识。
3）统一内存一体机会兴起，MoE 在一体机上翻盘。DGX Spark、Mac Studio、AMD Ryzen AI Max+395 这类"显存=内存"的一体机正在普及——容量上百 GB，装得下 124B 的 MoE。这时激活小的 MoE 反而比 Dense 快（实测 Ling-3.0-flash 35 tok/s 是 27B Dense 的 8 倍）。独显小显存看 Dense，统一内存大容量看 MoE，两种硬件走两条路。
4）多模态原生会成为默认形态。单独下个语言模型再接视觉模块的拼装路线，会被"一个模型全吃"的原生多模态替代——Qwen3.8-27B 就是这个形态的样本。

==大模型本地化不是要不要做的问题，是哪台电脑先装上的问题。==

风险 / 注意事项

1）显存别只看参数。27B 听着不大，BF16 要 54GB，FP8 要 27GB——4090 24G 跑 FP8 会 OOM，但 5090 32G 刚好能装。买卡前先按第 3.4 节算一遍。
2）长上下文吃 KV cache。256K 上下文很香，但真开到那么长，KV cache 显存会暴涨，并发和长度得取舍。
3）GGUF 版本滞后。社区量化通常比官方慢半拍，要最新版还是得盯 HF/ModelScope 官方。
4）第三方实测要自己跑。刷屏帖里的速度数硬件各异，照搬没意义，拉下来用 vLLM 自带 benchmark 跑一遍才是自己的数。
5）License 确认。Qwen3.8-27B 是 Apache-2.0 商用友好，但衍生量化版的 License 以各自仓库为准，商用前看一眼。

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，可以直接在终端里帮你写代码、查 bug、读项目。但因为它走的是 Anthropic 官方 API，国内用户直接使用有门槛。我在自己的 Windows 电脑和云服务器（Linux）上都跑通了，也帮几个朋友配置过，发现整个过程对于不熟悉命令行的同学来说，坑还挺多的。本文从一台新电脑的视角出发，手把手带你装好 Claude Code，并接入第三方 API 中转服务，让国内用户也能流畅使用。

本文将覆盖：Windows、Mac、Linux 三个平台。

1 前置准备：安装 Node.js

Claude Code 是通过 npm 分发的，npm 是 Node.js 自带的包管理器。所以第一步：装 Node.js。

Claude Code 目前要求 Node.js ≥ 22.0.0，建议直接装最新的 LTS 版本。

1.1 Windows 安装

1）打开 Node.js 官网：https://nodejs.org

2）下载左边的 LTS 版本（长期支持版），右边是最新版也可以用，但 LTS 更稳。你会得到一个 .msi 安装包，比如 node-v22.x.x-x64.msi。

3）双击运行安装包，一路点 "Next" 就行。注意这一步：在安装选项页面，确保 "Add to PATH" 是勾选状态（默认就是勾的），这样才能在任意位置使用 node 和 npm 命令。

4）安装完成后，验证一下。按 Win + R，输入 cmd 回车，打开命令提示符，输入：

node --version
npm --version

如果分别输出 v22.x.x 和 10.x.x，说明安装成功。

1.2 Mac 安装

Mac 推荐用 Homebrew，一行搞定。如果你还没有 Homebrew，先去 https://brew.sh 复制那行安装命令跑一遍。

# 安装 Node.js
brew install node

# 验证
node --version
npm --version

如果你习惯用 nvm 管理 Node 版本，也可以 nvm install 22，效果一样。对小白来说 Homebrew 就够。

1.3 Linux 安装

以 Ubuntu/Debian 为例：

# 添加 NodeSource 源（Node.js 22.x）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装
sudo apt-get install -y nodejs

# 验证
node --version
npm --version

CentOS/RHEL 用对应的 yum 源；其他发行版请参考 NodeSource 官方文档。装完验证版本号，确保 ≥ 22。

2 安装 Claude Code

Node.js 就位后，打开终端（Windows 是 cmd 或 PowerShell，Mac/Linux 是 Terminal），执行一行命令：

2.1 通过 npm 全局安装

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

-g 表示全局安装，装完后在任意目录都能使用 claude 命令。

安装过程大概 1-2 分钟，取决于网络速度。如果下载很慢，可以先设置 npm 镜像：

# 可选：设置淘宝镜像加速下载
npm config set registry https://registry.npmmirror.com

# 然后再安装
npm install -g @anthropic-ai/claude-code

2.2 验证安装

claude --version

如果输出版本号（如 2.1.217），说明安装成功。

3 接入第三方 API

这是本文最核心的部分。Claude Code 默认连的是 Anthropic 官方 API（https://api.anthropic.com），需要海外信用卡和网络。国内用户可以通过 API 中转服务（也叫 API Proxy / API 网关）来使用，原理很简单：

你的 Claude Code → 中转服务器 → Anthropic 官方 API → 中转服务器 → 你的 Claude Code

你只需要一个中转服务的 API Key 和一个 Base URL，就能跟官方一样使用。

3.1 获取中转 API 地址和 Key

市面上有多个中转服务商，比如 APIHub、AIHubMix、LobeChat 网关、CloudFlare Worker 自建等，选一个注册获取：

• Base URL：类似 https://your-api-proxy.com 的地址
• API Key：类似 sk-xxxxxxxxxxxxxxxxxxxxxxxx 的密钥
• 模型名称：中转服务会告诉你可以用哪些模型，比如 claude-sonnet-4-20250514

注意
不要把 API Key 发给任何人，不要贴到公开的 GitHub 仓库里。Key 泄露会被盗刷。

3.2 配置 settings.json

Claude Code 的配置统一放在 settings.json 里。这个文件有两级：

推荐先配置用户级，这样不管在哪个目录用 Claude Code，都能用同一个中转 API。

步骤 1：找到或创建配置文件

.claude 文件夹在用户主目录下，不同系统的路径：

• Windows：C:\Users\你的用户名\.claude\
• Mac / Linux：~/.claude/

如果该目录不存在，自己创建：

# Windows (PowerShell)
mkdir $env:USERPROFILE\.claude

# Mac / Linux
mkdir -p ~/.claude

步骤 2：编写 settings.json

在 .claude/ 目录下新建 settings.json，写入以下内容：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-proxy.com",
    "ANTHROPIC_API_KEY": "sk-your-api-key-here",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "model": "claude-sonnet-4-20250514"
}

逐项解释：

步骤 3：创建文件的方式

Windows 用户如果不熟悉命令行，用记事本就行：

1. 打开记事本，把上面的 JSON 复制进去，替换 BASE_URL 和 API_KEY 为你的真实值
2. 另存为 → 路径填 C:\Users\你的用户名\.claude\settings.json
3. 保存类型选"所有文件"，编码选 UTF-8

Mac / Linux 用户直接用命令：

# 创建并编辑
vim ~/.claude/settings.json

3.3 环境变量方式（备选）

除了 settings.json，也可以直接用环境变量，效果一样：

# Windows PowerShell
$env:ANTHROPIC_BASE_URL="https://your-api-proxy.com"
$env:ANTHROPIC_API_KEY="sk-your-api-key-here"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

# Mac / Linux
export ANTHROPIC_BASE_URL="https://your-api-proxy.com"
export ANTHROPIC_API_KEY="sk-your-api-key-here"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

不过这种方式只在当前终端窗口有效，关掉就没了。想持久化的话，把 export 写到 ~/.bashrc 或 ~/.zshrc 里，或者在 settings.json 里配置（推荐后者，集中管理）。

4 配置 CLAUDE.md

CLAUDE.md 是给 Claude Code 看的"说明书"。你在这个文件里告诉 Claude：你做什么工作、这个项目是什么、有什么特殊规则——Claude 每次启动都会自动读它，并按照里面的约定来帮你干活。

分两级（跟 settings.json 一样）：

4.1 项目级 CLAUDE.md

放在你正在做的项目的根目录下。比如你有一个项目叫 my-project/，就在里面放一个 CLAUDE.md。Claude Code 在那个目录启动时会自动加载。

典型场景：

my-project/
├── CLAUDE.md          ← 这个项目的专属指令
├── src/
├── package.json
└── ...

CLAUDE.md 内容示例：

# 项目说明

这是一个个人博客项目，基于 Next.js 构建。

## 技术栈
- Next.js 14 + TypeScript
- Tailwind CSS
- Contentlayer 管理文章

## 规则
- 所有新组件放 `src/components/`
- 提交前先跑 `npm run lint`
- 不要直接改 `content/` 下的 .mdx，走 Contentlayer 生成

4.2 用户级 CLAUDE.md

放在 ~/.claude/CLAUDE.md（即 C:\Users\你的用户名\.claude\CLAUDE.md），对所有项目生效。适合放通用的个人偏好和工作习惯：

# 个人偏好

- 用中文回复
- 写代码先解释思路再动手
- 每次改完代码自动跑测试
- 不要主动新建文件，先问我

4.3 一个简单的入门模板

如果你是第一次用，跟我一样只是拿 Claude Code 处理零散任务，用户级 CLAUDE.md 够用了：

# 通用指令

- 默认用中文交流
- 修改文件前先和我确认
- 代码注释用中文
- 遇到不确定的，列出选项让我选，不要直接做决定

创建后用 claude 命令启动，它会自动读取 CLAUDE.md。你可以问它："你读到了什么规则？"来验证是否加载成功。

5 开始使用

配置完成后，打开终端，进入你的项目目录，输入：

claude

首次启动可能提示权限确认，一路 Yes 就行。启动后你会看到类似这样的界面：

  Claude Code v2.1.217
  Model: claude-sonnet-4-20250514
  API: https://your-api-proxy.com

> 

到这里就成功了。试着输入第一个指令：

帮我看看这个项目的结构

按 Ctrl + C 或输入 /exit 退出。

6 常见问题

Q: 启动后报 "401 Unauthorized"？
A: API Key 写错了，或者 Base URL 格式不对。检查 settings.json 里的 key 有没有多余空格，Base URL 末尾不要带斜杠。

Q: 报 "Model not found"？
A: model 名称写错了，或者中转服务不支持这个模型。先确认中转给的支持列表，然后把 "model" 字段改成正确的。也可以删掉 model 字段，加上 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 让程序自动发现。

Q: 速度很慢？
A: 中转服务走的海外线路，有天然延迟，正常现象。换一个延迟更低的中转商，或者自建 Worker 能改善。

Q: npm install 报错 / 权限不够？
A: Mac/Linux 如果不用 sudo 就报权限错，可以这样修：

# 方法1：修复 npm 全局目录权限（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 方法2：直接 sudo（不推荐，但快）
sudo npm install -g @anthropic-ai/claude-code

Q: Windows 上 PowerShell 提示"无法加载文件"？
A: PowerShell 执行策略限制了脚本运行。管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新打开终端即可。

Q: 怎么更新 Claude Code？

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

Q: 怎么卸载？

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

本节课只解决一个问题：怎么用最简单的代码调用一次大模型。
先不要急着学 CoT、ReAct、工具调用、记忆、多 Agent。因为这些能力最后都会回到同一个基础动作：

把问题发给大模型
→ 大模型返回答案
→ 程序拿到答案继续处理

如果这一步都不能稳定运行，后面写 Agent 时会很痛苦。

1.1 本节课要做什么

本节课只做四件事：

1. 说明现在常见的大模型调用方式
2. 说明为什么本节先使用 OpenAI 兼容接口
3. 写一个简单的 llm.py
4. 写一个简单的 main.py，运行后能看到模型输出
   本节课不追求封装得很完整，也不做太多抽象。代码要做到：高中生看得懂，复制下来能运行，后面课程能继续复用。

2 当前有几种大模型调用方式

2.1 第一种：官方原生接口

每个大模型厂商一般都有自己的官方接口。
例如：

这种方式的好处是能力最完整，坏处是每家写法不完全一样。你刚开始学习时，如果一上来同时适配 OpenAI、Claude、Gemini，很容易被 SDK 差异打断思路。

2.2 第二种：OpenAI 兼容接口

很多模型厂商支持 OpenAI 兼容接口。
简单说，就是它们让你继续使用 OpenAI SDK，只需要改三样东西：

API Key
Base URL
Model Name

常见支持 OpenAI 兼容接口的平台包括：

这就是本节课选择 OpenAI 兼容接口的原因：代码最少，迁移最简单，适合入门。

2.3 第三种：统一网关

还有一种方式是使用 LiteLLM、One API、公司内部网关这类统一代理。
它的作用是把多个模型包装成一个统一入口：

业务代码
→ 模型网关
→ OpenAI / DeepSeek / Qwen / Claude / Gemini

这种方式适合团队使用，但不适合第一节课。因为它又多引入了一层系统，初学者很容易不知道问题出在代码、网关还是模型服务。

2.4 本节课的推荐做法

本节课推荐：

先用 OpenAI SDK
→ 连接一个 OpenAI 兼容模型
→ 跑通最小调用
→ 后面课程全部复用这个 LLM 客户端

这样后面写 CoT 时，只需要关注 prompt 怎么写；写 ReAct 时，只需要关注模型怎么推理和行动；写工具调用时，再扩展工具参数即可。

3 一次大模型调用需要哪些信息

3.1 最少需要三个配置

一次大模型调用最少需要三个配置：

可以把它理解成点外卖：

LLM_MODEL_ID：你要点哪道菜
LLM_API_KEY：证明这是你的账号
LLM_BASE_URL：外卖平台地址

3.2 为什么配置放到 .env

不要把 API Key 写死在 Python 代码里。
不推荐：

api_key = "sk-xxxx"

推荐：

api_key = os.getenv("LLM_API_KEY")

原因很简单：

• API Key 是密码，不能随便暴露
• 换模型时不需要改代码
• 后面部署到服务器时也更方便
  所以本节课把 .env 当作配置文件使用，先不引入 config.yaml。对第一节课来说，.env 已经够用了。

4 项目结构

4.1 最终目录

创建一个目录：

agent-course-01-llm-call/
├── .env
├── llm.py
├── main.py
└── requirements.txt

每个文件的作用如下：

5 安装依赖

5.1 创建 requirements.txt

创建 requirements.txt：

openai
python-dotenv

这里只安装两个包：

• openai：用来调用 OpenAI 兼容接口
• python-dotenv：用来读取 .env 配置

5.2 安装依赖

执行：

pip install -r requirements.txt

如果你的电脑需要使用 pip3，就执行：

pip3 install -r requirements.txt

5.3 验证安装

执行：

python -c "from openai import OpenAI; from dotenv import load_dotenv; print('ok')"

预期输出：

ok

如果这里都不能运行，先不要继续写代码，先解决 Python 环境和依赖安装问题。

6 配置 .env

6.1 创建 .env 文件

创建 .env：

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

把 你的API_KEY 换成真实的 API Key。

6.2 不同平台的配置示例

如果你使用 DeepSeek：

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的DeepSeek_API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

如果你使用阿里云百炼 Qwen：

LLM_MODEL_ID=qwen-plus
LLM_API_KEY=你的DASHSCOPE_API_KEY
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_TIMEOUT=60

如果你使用OpenAI：

如果你使用 OpenAI：
```bash
LLM_MODEL_ID=gpt-5-mini
LLM_API_KEY=你的OPENAI_API_KEY
LLM_BASE_URL=https://api.openai.com/v1
LLM_TIMEOUT=60

注意：模型名称可能会变化，最终以对应平台控制台和官方文档为准。如果报 model not found，优先检查 LLM_MODEL_ID。

7 编写 llm.py

7.1 代码目标

llm.py 只做一件事：把 messages 发给大模型，然后返回文本结果。
这里保留流式输出。因为流式输出体验更好，运行时能看到模型一个字一个字返回，不会一直卡着没反应。

7.2 完整代码

创建 llm.py：

import os
from typing import List, Dict, Optional
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
class HelloAgentsLLM:
    """
    一个最小可用的 LLM 客户端。
    只支持 OpenAI 兼容接口。
    """
    def __init__(
        self,
        model: Optional[str] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[int] = None,
    ):
        self.model = model or os.getenv("LLM_MODEL_ID")
        self.api_key = api_key or os.getenv("LLM_API_KEY")
        self.base_url = base_url or os.getenv("LLM_BASE_URL")
        self.timeout = timeout or int(os.getenv("LLM_TIMEOUT", "60"))
        if not self.model:
            raise ValueError("缺少模型名称，请在 .env 中配置 LLM_MODEL_ID")
        if not self.api_key:
            raise ValueError("缺少 API Key，请在 .env 中配置 LLM_API_KEY")
        if not self.base_url:
            raise ValueError("缺少服务地址，请在 .env 中配置 LLM_BASE_URL")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url=self.base_url,
            timeout=self.timeout,
        )
    def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
        """
        调用大模型，并返回完整文本。
        messages 是对话列表，例如：
        [
            {"role": "system", "content": "你是一个有帮助的助手"},
            {"role": "user", "content": "你好"}
        ]
        """
        print(f"🧠 正在调用模型：{self.model}")
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                temperature=temperature,
                stream=True,
            )
            print("✅ 模型返回：")
            result = []
            for chunk in response:
                if not chunk.choices:
                    continue
                content = chunk.choices[0].delta.content
                if not content:
                    continue
                print(content, end="", flush=True)
                result.append(content)
            print()
            return "".join(result)
        except Exception as e:
            print(f"❌ 调用大模型失败：{e}")
            return ""

7.3 这段代码怎么理解

这段代码里最重要的只有三部分。
第一，读取配置：

self.model = model or os.getenv("LLM_MODEL_ID")
self.api_key = api_key or os.getenv("LLM_API_KEY")
self.base_url = base_url or os.getenv("LLM_BASE_URL")

意思是：如果代码里传了参数，就用代码里的；如果没有传，就从 .env 里读取。
第二，创建客户端：

self.client = OpenAI(
    api_key=self.api_key,
    base_url=self.base_url,
    timeout=self.timeout,
)

意思是：告诉 OpenAI SDK，我要访问哪个模型服务。
第三，发送 messages：

response = self.client.chat.completions.create(
    model=self.model,
    messages=messages,
    temperature=temperature,
    stream=True,
)

意思是：把对话内容发给模型，并使用流式返回。

8 编写 main.py

8.1 代码目标

main.py 是入口文件，只负责演示怎么使用 HelloAgentsLLM。
它不要复杂，也不要封装太多逻辑。第一节课最重要的是让读者看清楚调用顺序。

8.2 完整代码

创建 main.py：

from llm import HelloAgentsLLM
def main():
    llm = HelloAgentsLLM()
    messages = [
        {
            "role": "system",
            "content": "你是一个讲解清楚、表达简单的 AI 助手。",
        },
        {
            "role": "user",
            "content": "用高中生能听懂的话解释什么是 LLM Agent。",
        },
    ]
    print("--- 调用 LLM ---")
    response_text = llm.think(messages)
    if response_text:
        print("\n--- 完整模型响应 ---")
        print(response_text)
if __name__ == "__main__":
    main()

8.3 调用顺序

这个文件的执行顺序很简单：

创建 HelloAgentsLLM
→ 准备 messages
→ 调用 llm.think(messages)
→ 打印模型返回内容

这就是后面所有 Agent 课程的基础。

9 运行验证

9.1 执行命令

在项目目录下执行：

python main.py

预期输出类似：

--- 调用 LLM ---
🧠 正在调用模型：deepseek-chat
✅ 模型返回：
LLM Agent 可以理解成一个由大语言模型驱动的智能助手，它不只是回答问题，还能根据目标规划步骤、调用工具，并根据结果继续完成任务。
--- 完整模型响应 ---
LLM Agent 可以理解成一个由大语言模型驱动的智能助手，它不只是回答问题，还能根据目标规划步骤、调用工具，并根据结果继续完成任务。

只要能看到模型返回内容，就说明本节课完成了。

9.2 修改问题再运行

你可以把 main.py 里的问题改成：

"写一个 Python 快速排序算法"

再执行：

python main.py

如果模型能返回代码，说明你的调用链路是正常的。

10 常见坑

10.1 .env 没有生效

如果提示：

缺少 API Key，请在 .env 中配置 LLM_API_KEY

先检查 .env 是否在当前目录。
正确目录应该是：

agent-course-01-llm-call/
├── .env
├── llm.py
├── main.py
└── requirements.txt

然后检查变量名是不是写错了。
必须是：

LLM_MODEL_ID=xxx
LLM_API_KEY=xxx
LLM_BASE_URL=xxx

不是：

MODEL_ID=xxx
API_KEY=xxx
BASE_URL=xxx

10.2 base_url 写成了完整接口地址

这是新手最常见的问题。
如果你使用 SDK，一般配置的是：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

不要写成：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

因为 /chat/completions 这段路径 SDK 会自动拼接。

10.3 模型名称写错

如果报错里出现：

model not found

一般是模型名不对。
解决办法：

1. 去模型平台控制台确认模型名
2. 确认账号是否有这个模型权限
3. 先使用官方示例里的模型名
4. 不要照抄过期文章里的模型名

10.4 API Key 错误

如果报错里出现：

401
unauthorized
invalid api key

一般是 API Key 错了。
先检查：

• API Key 有没有复制完整
• API Key 前后有没有多余空格
• 当前平台和 API Key 是否匹配
• DeepSeek 的 Key 不要拿去调用 Qwen
• Qwen 的 Key 不要拿去调用 Kimi

10.5 temperature 设置

本节课默认：

temperature=0

可以简单理解成：让模型尽量稳定回答。
推荐：

刚开始学习 Agent，推荐先用 0。结果稳定，方便排查问题。

11 本节课最终代码

11.1 requirements.txt

openai
python-dotenv

11.2 .env

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

11.3 llm.py

import os
from typing import List, Dict, Optional
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
class HelloAgentsLLM:
    def __init__(
        self,
        model: Optional[str] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[int] = None,
    ):
        self.model = model or os.getenv("LLM_MODEL_ID")
        self.api_key = api_key or os.getenv("LLM_API_KEY")
        self.base_url = base_url or os.getenv("LLM_BASE_URL")
        self.timeout = timeout or int(os.getenv("LLM_TIMEOUT", "60"))
        if not self.model:
            raise ValueError("缺少模型名称，请在 .env 中配置 LLM_MODEL_ID")
        if not self.api_key:
            raise ValueError("缺少 API Key，请在 .env 中配置 LLM_API_KEY")
        if not self.base_url:
            raise ValueError("缺少服务地址，请在 .env 中配置 LLM_BASE_URL")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url=self.base_url,
            timeout=self.timeout,
        )
    def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
        print(f"🧠 正在调用模型：{self.model}")
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                temperature=temperature,
                stream=True,
            )
            print("✅ 模型返回：")
            result = []
            for chunk in response:
                if not chunk.choices:
                    continue
                content = chunk.choices[0].delta.content
                if not content:
                    continue
                print(content, end="", flush=True)
                result.append(content)
            print()
            return "".join(result)
        except Exception as e:
            print(f"❌ 调用大模型失败：{e}")
            return ""

11.4 main.py

from llm import HelloAgentsLLM
def main():
    llm = HelloAgentsLLM()
    messages = [
        {
            "role": "system",
            "content": "你是一个讲解清楚、表达简单的 AI 助手。",
        },
        {
            "role": "user",
            "content": "用高中生能听懂的话解释什么是 LLM Agent。",
        },
    ]
    print("--- 调用 LLM ---")
    response_text = llm.think(messages)
    if response_text:
        print("\n--- 完整模型响应 ---")
        print(response_text)
if __name__ == "__main__":
    main()

12 总结

12.1 本节课学到了什么

本节课只做了一个最小闭环：

.env 配置模型
→ llm.py 封装调用
→ main.py 发起请求
→ 控制台看到模型输出

这个闭环很小，但非常重要。后面所有 Agent 能力都会建立在它上面。

12.2 为什么这样写

本节课没有做复杂封装，原因是：

• 第一节课的目标是跑通，不是设计框架
• .env 已经能满足基础配置需求
• OpenAI 兼容接口能覆盖很多常见模型
• llm.think(messages) 这个入口后面可以继续复用
  后面进入 CoT 时，可以这样调用：

  messages = [
  {"role": "system", "content": "你是一个擅长一步一步推理的助手。"},
  {"role": "user", "content": "请一步一步分析这个问题：..."}
  ]
  llm.think(messages)

  也就是说，本节课不是孤立代码，而是后续 Agent 课程的底座。

13 参考文献

13.1 官方文档

• OpenAI API Reference：Chat Completions、Streaming、OpenAI Python SDK
• DeepSeek API Docs：OpenAI-compatible API format
• 阿里云百炼 Model Studio 文档：OpenAI 兼容接口调用千问模型
• Moonshot Kimi API 开放平台文档：OpenAI 兼容 API
• 智谱 AI 开放文档：OpenAI API 兼容接入说明
• Anthropic Claude API Docs：Claude Python SDK、Messages API
• Google AI for Developers：Gemini API、Google Gen AI SDK

13.2 后续课程

• 02 CoT：显式步骤推理
• 03 ReAct：推理和行动交替
• 04 Tool Use：让模型调用工具
• 05 Memory：让 Agent 记住上下文
• 06 Reflection：让 Agent 自我修正

一、网络规划

先统一规划 IP，后面所有配置都按这个来。

需要记住一个原则：一台设备一套密钥，一个独立 IP，不要多个设备共用同一个配置。

二、服务器安装 WireGuard

1. 安装软件

Ubuntu / Debian 执行：

sudo apt update
sudo apt install -y wireguard qrencode iptables

CentOS / Rocky / AlmaLinux 执行：

sudo dnf install -y wireguard-tools qrencode iptables

2. 开启 IP 转发

编辑系统配置：

sudo vim /etc/sysctl.conf

加入或确认有这一行：

net.ipv4.ip_forward=1

让配置立即生效：

sudo sysctl -p

检查结果：

cat /proc/sys/net/ipv4/ip_forward

输出 1 就是成功。

3. 查看服务器公网网卡

执行：

ip route | grep default

你会看到类似：

default via 172.31.0.1 dev eth0

这里的 eth0 就是公网网卡。也可能是 ens3、ens5、enp1s0，后面配置里的 eth0 要按实际结果替换。

4. 生成服务端密钥

sudo mkdir -p /etc/wireguard/clients
cd /etc/wireguard
sudo umask 077
sudo wg genkey | sudo tee server_private.key | sudo wg pubkey | sudo tee server_public.key

查看服务端私钥和公钥：

sudo cat /etc/wireguard/server_private.key
sudo cat /etc/wireguard/server_public.key

私钥不要泄露，公钥后面要填到客户端里。

5. 创建服务端配置

编辑配置文件：

sudo vim /etc/wireguard/wg0.conf

写入：

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = 填服务端PrivateKey
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

注意：如果你的公网网卡不是 eth0，把上面的 eth0 改成你的实际网卡名。

6. 放行 UDP 端口

如果服务器用了 UFW：

sudo ufw allow 51820/udp
sudo ufw reload

如果是云服务器，还要去云厂商安全组放行：

协议：UDP
端口：51820
来源：0.0.0.0/0

这是最容易漏的一步。WireGuard 用的是 UDP，不是 TCP。

7. 启动 WireGuard

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

查看状态：

sudo wg show

看到 interface: wg0 就说明服务端启动成功。

三、添加手机、电脑、CatWrt 客户端

1. 生成客户端密钥

生成手机密钥：

cd /etc/wireguard
sudo wg genkey | sudo tee clients/phone_private.key | sudo wg pubkey | sudo tee clients/phone_public.key

生成电脑密钥：

sudo wg genkey | sudo tee clients/pc_private.key | sudo wg pubkey | sudo tee clients/pc_public.key

生成 CatWrt 密钥：

sudo wg genkey | sudo tee clients/catwrt_private.key | sudo wg pubkey | sudo tee clients/catwrt_public.key

2. 把客户端加入服务端

编辑服务端配置：

sudo vim /etc/wireguard/wg0.conf

在文件末尾追加：

[Peer]
# phone
PublicKey = 填phone_public.key里的内容
AllowedIPs = 10.8.0.2/32
[Peer]
# pc
PublicKey = 填pc_public.key里的内容
AllowedIPs = 10.8.0.3/32
[Peer]
# catwrt
PublicKey = 填catwrt_public.key里的内容
AllowedIPs = 10.8.0.10/32

服务端这里一定要写 /32，不要给每个客户端都写 10.8.0.0/24，否则多客户端容易冲突。

3. 重启服务端

sudo systemctl restart wg-quick@wg0
sudo wg show

四、生成客户端配置文件

1. 手机配置 phone.conf

查看需要填的密钥：

sudo cat /etc/wireguard/clients/phone_private.key
sudo cat /etc/wireguard/server_public.key

创建手机配置：

sudo vim /etc/wireguard/clients/phone.conf

写入：

[Interface]
PrivateKey = 填phone_private.key里的内容
Address = 10.8.0.2/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

AllowedIPs = 0.0.0.0/0 表示手机所有流量都走 WireGuard。如果只想访问 WireGuard 内网，改成：

AllowedIPs = 10.8.0.0/24

生成二维码：

sudo qrencode -t ansiutf8 < /etc/wireguard/clients/phone.conf

2. 电脑配置 pc.conf

查看电脑私钥：

sudo cat /etc/wireguard/clients/pc_private.key

创建电脑配置：

sudo vim /etc/wireguard/clients/pc.conf

写入：

[Interface]
PrivateKey = 填pc_private.key里的内容
Address = 10.8.0.3/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

3. CatWrt 配置 catwrt.conf

查看 CatWrt 私钥：

sudo cat /etc/wireguard/clients/catwrt_private.key

创建 CatWrt 配置：

sudo vim /etc/wireguard/clients/catwrt.conf

写入：

[Interface]
PrivateKey = 填catwrt_private.key里的内容
Address = 10.8.0.10/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

如果你第一次配置 CatWrt，建议先把 AllowedIPs 写成：

AllowedIPs = 10.8.0.0/24

确认能连通后，再改成：

AllowedIPs = 0.0.0.0/0

这样可以避免路由器一启用 WireGuard 就全家断网。

五、手机设置 WireGuard

1. iPhone / iPad

在 App Store 安装 WireGuard，打开 App，点击 +，选择扫码导入，扫描服务器生成的二维码，保存后打开开关。

2. Android

安装 WireGuard App，点击 +，选择扫码导入或导入配置文件，保存后打开开关。

3. 手机测试

手机打开 WireGuard 后，访问查 IP 网站。如果显示的是服务器公网 IP，说明手机流量已经走服务器。如果只是访问内网，可以测试：

ping 10.8.0.1

六、电脑设置 WireGuard

1. Windows

安装 WireGuard 官方客户端，点击 Import tunnel(s) from file，选择 pc.conf，然后点击 Activate。

2. macOS

在 App Store 安装 WireGuard，导入 pc.conf，然后启用。

3. Linux

安装：

sudo apt update
sudo apt install -y wireguard

复制配置：

sudo cp pc.conf /etc/wireguard/wg0.conf
sudo chmod 600 /etc/wireguard/wg0.conf

启动：

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

查看：

sudo wg show

七、CatWrt 设置 WireGuard

CatWrt 可以按 OpenWrt 的方式配置。这里推荐把 CatWrt 当客户端，连接云服务器。

1. 安装 WireGuard 组件

SSH 登录 CatWrt，执行：

opkg update
opkg install luci-proto-wireguard wireguard-tools kmod-wireguard qrencode

安装后重启：

reboot

如果提示 kmod-wireguard 内核版本不匹配，不要硬装。通常是固件和软件源不匹配，需要换匹配的软件源或升级 CatWrt 固件。

2. 新建 WireGuard 接口

进入 CatWrt 后台：

网络 -> 接口 -> 添加新接口

设置：

名称：wg_vps
协议：WireGuard VPN

如果没有 WireGuard VPN 选项，说明插件没装好，或装完没有重启。

3. 填写接口信息

在 wg_vps 接口中填写：

私钥：catwrt_private.key 的内容
IP 地址：10.8.0.10/32
MTU：1420
监听端口：留空

CatWrt 作为客户端时，监听端口可以留空。

4. 添加服务端 Peer

在 对端 / Peers 里添加：

公钥：server_public.key 的内容
端点主机：服务器公网IP或域名
端点端口：51820
允许的 IP：10.8.0.0/24 或 0.0.0.0/0
持久 KeepAlive：25

如果只是测试，允许的 IP 先写：

10.8.0.0/24

如果想让 CatWrt 下的设备都走 WireGuard，再改成：

0.0.0.0/0

如果页面有 Route Allowed IPs / 路由允许的 IP，需要勾选。

5. 设置防火墙区域

如果只是让 CatWrt 自己访问 WireGuard，把 wg_vps 放到 lan 区域即可。
如果想让 CatWrt 下面的设备通过 WireGuard 上网，建议把 wg_vps 放到 wan 区域，因为 wan 通常已经开启 NAT，并允许 lan -> wan 转发。
如果你新建了 vpn 区域，需要确认：

lan -> vpn：允许转发
vpn：开启 Masquerading
vpn：允许输出

普通用户建议先放到 wan 区域，少踩坑。

6. CatWrt 测试

SSH 到 CatWrt：

wg show
ping 10.8.0.1

如果看到 latest handshake，说明已经连上。如果 CatWrt 配的是全局流量，可以测试出口 IP：

curl ifconfig.me

显示服务器公网 IP，说明 CatWrt 已经通过 WireGuard 出口上网。

八、常见坑

1. 没有握手

优先检查：云服务器安全组是否放行 UDP 51820，服务器防火墙是否放行 UDP 51820，客户端 Endpoint 是否写错，服务端是否添加了对应客户端 Peer，公钥是否填反。

2. 有握手但不能上网

检查服务器是否开启转发：

cat /proc/sys/net/ipv4/ip_forward

必须输出：

1

再检查 NAT 网卡名是否正确：

ip route | grep default

如果实际网卡是 ens3，配置里却写 eth0，就会连上但不能上网。

3. 多个客户端互相顶掉

原因通常是多个设备用了同一个配置。每台设备都要有独立 PrivateKey 和独立 Address。

4. CatWrt 一启用就断网

先把 CatWrt 的 AllowedIPs 从：

0.0.0.0/0

改成：

10.8.0.0/24

确认基础连接正常后，再考虑全局代理。旁路由不会自动接管全家流量，如果 CatWrt 是旁路由，还需要让设备网关指向 CatWrt，或者使用策略路由。

5. 能连但网页打不开

优先检查 DNS。客户端可以先写：

DNS = 1.1.1.1

如果某些网络下不稳定，保留：

PersistentKeepalive = 25

必要时把 MTU 改小：

MTU = 1280

九、新增客户端接入时怎么修改

后面如果要新增手机、电脑、平板、路由器，不需要重装 WireGuard，只需要做三件事：生成新客户端密钥、服务端增加一个 Peer、生成新客户端配置。

1. 规划一个新 IP

先给新设备分配一个没有用过的 WireGuard IP。例如前面已经用了：

手机：10.8.0.2
电脑：10.8.0.3
CatWrt：10.8.0.10

新增一台平板，可以用：

平板：10.8.0.4

不要和已有设备重复。

2. 生成新客户端密钥

假设新客户端叫 pad：

cd /etc/wireguard
sudo bash -c 'umask 077; wg genkey | tee /etc/wireguard/pad_private.key | wg pubkey > /etc/wireguard/pad_public.key'

查看新客户端公钥：

sudo cat /etc/wireguard/pad_public.key

3. 修改服务端配置

编辑服务端配置：

sudo vim /etc/wireguard/wg0.conf

在文件末尾追加：

[Peer]
# pad
PublicKey = 填pad_public.key里的内容
AllowedIPs = 10.8.0.4/32

注意：服务端这里只需要新增这个客户端的 [Peer]，不要修改已有手机、电脑、CatWrt 的配置。

4. 重启 WireGuard

sudo systemctl restart wg-quick@wg0

查看状态：

sudo wg show

重启时已有客户端会短暂断开，几秒后会自动恢复。普通用户用这种方式最简单。

5. 生成新客户端配置

查看服务端公钥和新客户端私钥：

sudo cat /etc/wireguard/server_public.key
sudo cat /etc/wireguard/clients/pad_private.key

创建新客户端配置：

sudo vim /etc/wireguard/clients/pad.conf

写入：

[Interface]
PrivateKey = 填pad_private.key里的内容
Address = 10.8.0.4/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

如果这个客户端只想访问 WireGuard 内网，不想让所有流量都走服务器，把：

AllowedIPs = 0.0.0.0/0

改成：

AllowedIPs = 10.8.0.0/24

6. 导入新客户端

手机或平板可以生成二维码：

sudo qrencode -t ansiutf8 < /etc/wireguard/clients/pad.conf

然后用 WireGuard App 扫码导入。电脑客户端则直接导入 pad.conf 文件。

7. 新增客户端时最容易出错的地方

新增客户端时，只记住这几条：

1. 新设备必须用新的 PrivateKey 和 PublicKey
2. 新设备必须用新的 Address，不能和旧设备重复
3. 服务端必须新增一个对应的 [Peer]
4. 服务端 Peer 里的 AllowedIPs 要写这个客户端的 /32
5. 原有客户端配置不用改

例如新增 pad，服务端只新增：

[Peer]
# pad
PublicKey = pad的PublicKey
AllowedIPs = 10.8.0.4/32

客户端只使用：

Address = 10.8.0.4/32

不要复制旧手机的配置直接用，否则两个设备会互相顶掉。

tmux        负责多终端会话持久化
claude-tmux 负责查看多个 Claude Code 会话状态
claude-tui  负责查看上下文、成本、工具调用、session 统计

一、环境说明

本文以 Ubuntu / Debian / WSL / SSH 终端环境为主。
先确认 Claude Code 已经能用：

claude --version

如果这里都不能运行，先把 Claude Code 装好，再继续后面的步骤。

二、安装 tmux

Ubuntu / Debian

sudo apt update
sudo apt install -y tmux curl git build-essential

macOS

brew install tmux

验证：

tmux -V

三、安装 Rust / Cargo

claude-tmux 推荐通过 Cargo 安装，所以需要 Rust 工具链。
先检查：

cargo --version

如果没有 Cargo，安装 Rust，如果没有魔法可能安装失败，可以部分用国内安装：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
env RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup \
    RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup \
    sh -s -- -y --profile minimal

source "$HOME/.cargo/env"

验证：

cargo --version

四、安装 claude-tmux

执行：

cargo install claude-tmux

确认二进制文件存在：

which claude-tmux
ls -lh ~/.cargo/bin/claude-tmux

正常路径一般是：

/home/你的用户名/.cargo/bin/claude-tmux

五、配置 tmux 快捷键打开 claude-tmux

编辑 tmux 配置：

vim ~/.tmux.conf

加入这一行：

bind-key C-c display-popup -E -w 80 -h 30 "~/.cargo/bin/claude-tmux"

重载配置：

tmux source-file ~/.tmux.conf

进入 tmux：

tmux

然后按：

Ctrl-b  Ctrl-c

就会弹出 claude-tmux 面板。
claude-tmux 常见状态：

● Working           Claude 正在工作
○ Idle              Claude 空闲，等你输入
◐ Waiting for input 等待权限确认，例如 [y/n]
? Unknown           不是 Claude 会话，或者状态无法判断

六、安装 claude-tui

claude-tui 的坑比较多，核心要求是：

Python 3.13+

先检查当前 Python：

python3 --version

如果输出是 Python 3.13.x，可以直接安装：

curl -sSL https://raw.githubusercontent.com/slima4/claude-tui/main/install.sh | bash

安装后执行：

claudetui setup
claudetui mode full

验证：

which claudetui
claudetui --help

七、如果 Python 版本不是 3.13+

很多 Ubuntu 机器默认是 Python 3.10 或 3.12。不要直接替换系统的 /usr/bin/python3，否则可能影响 apt 和系统脚本。
推荐做法：只在当前用户环境里使用 Python 3.13。
先检查：

python3.13 --version
which python3.13

如果能看到 Python 3.13，执行：

mkdir -p ~/.local/bin
ln -sf "$(command -v python3.13)" ~/.local/bin/python3
grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hash -r

验证：

which python3
python3 --version

你应该看到类似：

/home/你的用户名/.local/bin/python3
Python 3.13.x

然后重新安装 claude-tui：

curl -sSL https://raw.githubusercontent.com/slima4/claude-tui/main/install.sh | bash
claudetui setup
claudetui mode full

八、常见坑

1：代理环境变量导致 curl 失败

如果你看到类似错误：

curl: (97) Can't complete SOCKS5 connection

或者明明没有主动加代理，但 curl 自动走了 socks/http 代理，先检查环境变量：

env | grep -i proxy

也可以逐个 echo：

echo "http_proxy=$http_proxy"
echo "https_proxy=$https_proxy"
echo "all_proxy=$all_proxy"
echo "HTTP_PROXY=$HTTP_PROXY"
echo "HTTPS_PROXY=$HTTPS_PROXY"
echo "ALL_PROXY=$ALL_PROXY"

临时清掉当前终端代理：

unset http_proxy
unset https_proxy
unset all_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

再次确认：

env | grep -i proxy

如果没有输出，说明当前 shell 的代理已经清掉。
重新测试：

curl -I --max-time 10 https://astral.sh
curl -I --max-time 10 https://raw.githubusercontent.com

如果你想查代理从哪里自动注入：

grep -nEi 'proxy|1080|8080|7890|socks' ~/.bashrc ~/.profile ~/.bash_profile ~/.zshrc 2>/dev/null

2：apt 代理配置导致 502 Bad Gateway

如果你给 apt 配过代理，比如：

Acquire::http::Proxy "http://127.0.0.1:8080/";
Acquire::https::Proxy "http://127.0.0.1:8080/";

然后出现：

502 Bad Gateway [IP: 127.0.0.1 8080]
仓库 InRelease 的签名不再生效

这通常不是 Ubuntu 源坏了，而是 apt 拿到的是代理返回的 502 页面，不是真正的 InRelease 文件。
先删掉 apt 代理：

sudo rm -f /etc/apt/apt.conf.d/99proxy
sudo apt clean

确认没有残留：

ls /etc/apt/apt.conf.d/*proxy* 2>/dev/null
cat /etc/apt/apt.conf.d/*proxy* 2>/dev/null

然后重新测试：

sudo apt update

如果你的网络必须走代理，先确认代理端口真的可用。
测试 HTTP 代理：

curl -v --max-time 10 -x http://127.0.0.1:8080 https://www.cloudflare.com/cdn-cgi/trace

测试 SOCKS5 代理：

curl -v --max-time 10 --socks5-hostname 127.0.0.1:1080 https://www.cloudflare.com/cdn-cgi/trace

如果 8080 返回 502，说明这个 HTTP 代理出口不可用，不要给 apt 配 8080。
如果 1080 可用，可以尝试 apt 使用 socks5h：

sudo tee /etc/apt/apt.conf.d/99proxy <<'EOF'
Acquire::ForceIPv4 "true";
Acquire::http::Proxy "socks5h://127.0.0.1:1080/";
Acquire::https::Proxy "socks5h://127.0.0.1:1080/";
EOF

然后：

sudo apt clean
sudo apt update

不用代理时，删除它：

sudo rm -f /etc/apt/apt.conf.d/99proxy
sudo apt clean

3：deadsnakes PPA 连接超时

如果你用 deadsnakes PPA 安装 Python 3.13，可能遇到：

连接超时
无法连接 ppa.launchpadcontent.net
IPv6 网络不可达

这时有三个选择：

选择 1：优先用 uv，绕开 apt PPA

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env" 2>/dev/null || export PATH="$HOME/.local/bin:$PATH"
uv python install 3.13

选择 2：修好代理后再 apt install

确认代理可用后再执行：

sudo apt update
sudo apt install -y python3.13 python3.13-venv libpython3.13-stdlib

选择 3：不用 claude-tui，先只用 tmux + claude-tmux

如果网络暂时修不好，claude-tmux 已经足够看多个 Claude 是否 working、idle、waiting。

九、推荐的 tmux 工作流

创建多个 Claude 任务 session：

tmux new -s claude-api
tmux new -s claude-web
tmux new -s claude-test
tmux new -s claude-monitor

在前三个 session 里启动 Claude：

claude

在 monitor session 里启动 claude-tui：

claudetui monitor

最终结构类似：

tmux
├── claude-api      # Claude 任务 1
├── claude-web      # Claude 任务 2
├── claude-test     # Claude 任务 3
└── claude-monitor  # claudetui monitor

日常命令：

tmux ls
tmux attach -t claude-api
tmux attach -t claude-web
tmux attach -t claude-test

在任意 tmux session 里打开 claude-tmux：

Ctrl-b  Ctrl-c

打开 claude-tui 实时监控：

claudetui monitor

查看历史统计：

claudetui stats

查看 session 列表：

claudetui sessions list

十、最终配置

我的推荐组合是：

vim ~/.tmux.conf

配置：

# Ctrl+a c      新建 window
# Ctrl+a d      detach
# Ctrl+a |      左右分屏
# Ctrl+a -      上下分屏
# Alt+h/j/k/l   直接切 pane
# 鼠标点击       选择 pane
# 鼠标拖边框     调整 pane 大小
# 把 prefix 从 Ctrl+b 改成 Ctrl+a

unbind C-b
set -g prefix C-a
bind C-a send-prefix

# 开启鼠标
set -g mouse on
setw -g mode-keys vi
# 鼠标左键拖选：自动进入 copy-mode，并限定在当前 pane
bind-key -T root MouseDrag1Pane if-shell -F "#{pane_in_mode}" "send-keys -M" "copy-mode -M"

# 鼠标松开：复制并退出 copy-mode
bind-key -T copy-mode-vi MouseDragEnd1Pane send -X copy-selection-and-cancel

bind-key -T copy-mode-vi v send -X begin-selection
bind-key -T copy-mode-vi y send -X copy-selection-and-cancel
bind-key -T copy-mode-vi Enter send -X copy-selection-and-cancel

set -g set-clipboard on

# 按 r 重新加载配置
bind r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"

# 更容易记的分屏
bind h split-window -h
bind v split-window -v

# Alt + hjkl 直接切换 pane，不需要先按 prefix
bind -n M-h select-pane -L
bind -n M-j select-pane -D
bind -n M-k select-pane -U
bind -n M-l select-pane -R

# Alt + 方向键也可以切换 pane
bind -n M-Left select-pane -L
bind -n M-Down select-pane -D
bind -n M-Up select-pane -U
bind -n M-Right select-pane -R

# Alt + 数字切 window
bind -n M-1 select-window -t 1
bind -n M-2 select-window -t 2
bind -n M-3 select-window -t 3
bind -n M-4 select-window -t 4
bind -n M-5 select-window -t 5

# 绑定claude-tmux
bind-key C-c display-popup -E -w 80 -h 30 "~/.cargo/bin/claude-tmux"

常用命令

openclaw gateway stop
openclaw gateway start

ssh代理远程访问

ssh -N -L 18789:127.0.0.1:18789 claw@192.168.100.104

登录：
查看.openclaw/openclaw.json中token秘钥，然后登录：

http://localhost:18789/chat?token=XXXX

最近正好在使用figma的make功能，正巧代码工具又层出不穷，除了我常用的cursor， codex、claude code、gemini-cli等Agent代码工具迎来了重大升级，正巧我使用阿里云盘在追剧，痛点是当有新剧增加的时候，别人是分享到网盘链接里的，每次我都需要找到对应的网盘，然后保存到我的阿里云盘里。如果是已更新完的剧还好，如果是正在更新的剧，我还需要记住对应的链接，没事点开看看有没有更新，然后转存到我的网盘里。所以正好想开发一个小工具，能够根据链接进行转存，并且定时查看分享链接里的内容有没有更新，如果更新以后则转存到我的目标云盘里。
因此做了一个阿里云盘自动转存的功能，目前支持的功能如下：

• 支持阿里云盘登录、查看存储状态
• 支持阿里云盘通过分享链接转存
• 支持转存为特定的名字
• 支持定时转存设置
• 支持对订阅内容进行编辑、暂停、删除
• 支持查看转存日志
  本项目完全没有主动编写任何代码，全程使用和大模型对话方式进行实现，本次只是说明如何使用该软件，后续我会将如何用figma+codex自动化编写代码进行分享。

2. 软件安装与使用

2.1 安装

目前已经上传到docker hub，建议直接使用docker进行安装，也可以访问我的github，按照github进行安装

https://github.com/apostle9891/aliautosave

使用docker进行安装

# 拉取aliautosave
docker pull apostle9891/aliautosave:latest

# 运行docker，其中/path要改成你的path
docker run -d --name aliautosave -p 8144:8144 -v /path/aliautosave_data:/app/data apostle9891/aliautosave:latest

如果是网页docker，可以直接搜索：aliautosave

点击下载，并进行安装，安装过程中端口映射为8144，存储位置替换/app/data

2.2 软件使用

当安装完成后，可以打开对应的IP:8144,比如我的网页是192.168.100.101:8144
打开以后，点击扫码登录阿里云盘

打开阿里云盘，登录阿里云盘

登录完毕后，可以看到对应的云盘信息

点击新增订阅，填入需要新增的分享链接

可以看到拉取到对应的云盘里的电视剧信息，支持多种自动命名规则，会自动提取里面的名字、集数、季数、扩展信息等，然后转为标准的姓名，目前支持：

• {title}.S{season:02}E{episode:02}{ext}
• {title}.E{episode:02}{ext}
• {name}{ext}
• {title}.{index:02}{ext}
  提取出来以后，我们可以自定义命名title，比如我们这次的电视剧叫做大生意，那我们改为大生意人。
  
  可以看到整体预览名字改成了大生意人
  
  选择对应的目标文件夹
  
  支持新建文件夹
  
  选择定时的策略，默认选择立即订阅并开始复制，会对内容进行复制
  
  点击后即可立即进行复制
  
  支持暂停、编辑、删除、查看转存日志
  
  暂停
  
  日志
  

结尾

大模型能力越来越强了，如果说在2023年我第一次开通vscode的copilot还是属于辅助编程，去年我买了cursor属于自定义编程，现在从6月份开始就真正可以叫做Agent编程了，可以全程通过对话进行编程，以后只需要一个ideal，就可以实现自己的想法。

背景

当我们使用大模型对ASR（语音识别）文本进行总结时，如何判断总结质量的好坏？这里提供一个简单的测试框架。

核心测试维度

1. 完整性 ✅

原文的关键信息是否都被覆盖？

2. 准确性 🎯

总结内容是否与原文一致？

3. 简洁性 📝

是否做到了有效压缩？

4. 可读性 👀

总结文本是否流畅易懂？

快速打分表

💡 评分参考：4分以上为优秀，3-4分为合格，3分以下需要优化提示词

常见问题与优化方向