上个月有朋友问我DeepSeek 都已经这么强了你折腾本地模型干嘛又费电又费显卡的。我反问他那你平时用模型是直接在网页上聊天还是会让它干点“活”他说就是聊天偶尔写点文案。我说问题就出在这儿——聊天只是模型的最浅层用法真正有价值的是把它变成一个会自己思考、会调工具、会反复试错完成的AI Agent。这篇内容就是把我这段折腾过程完整写出来从最底层的 GGML 推理到本地模型跑通再到现在用的 Claude Code 这套 agent 外壳一条线串下来新手照着做基本都能在自己电脑上搭出一个能用的本地 Agent。先说几个关键词方便大家对号入座AI Agent指能自主规划、调用工具、迭代完成任务的智能体GGML是一套本地模型推理的底层方案GGUF 文件就是跑在它上面的模型格式Qwen、Llama 的本地版本都要靠它Claude Code是目前很火的命令行 Agent 工具可以在终端里接管读文件、改代码、执行命令这一整套操作。这篇文章适合谁如果你跟我一样不想只停留在“聊天”阶段想真正搞懂 Agent 是怎么跑起来的、本地模型和云端模型分别适合什么场景以及怎么快速薅到一个趁手的 Agent 框架那你接着往下看应该会有收获。后面我会把网络热搜里大家反复搜的“Claude Code 安装”“VSCode 配置”“Agent 组成结构”“接入 DeepSeek 模型”这些话题全部落到实处。1. 先想清楚Agent、LLM、AI 模型这仨到底什么关系1.1 LLM 只是模型家族里的“文科大脑”很多人会把“AI 模型”“LLM”“AI Agent”混着叫但严格来讲它们不是一个层面的东西。AI 模型是个大集合里面既有能做语言理解的 LLM大语言模型也有能做图像识别的多模态模型甚至还有文生视频模型。总之一句话只要是你通过训练得到的那些权重参数都叫模型。LLM是模型家族里最出圈的一支ChatGPT、DeepSeek、Qwen这些大家耳熟能详的名字本质上都是 LLM 的某个实现。它们的能力核心就是两个字预测——根据上文预测下一个 token只不过预测的准确度做到了一定程度后涌现出了逻辑推理、代码生成这些能力。所以你问“DeepSeek 算模型还是 Agent”答案很明确它是模型而且是非常优秀的 LLM但单独一个模型不会主动帮你改代码、不会自动搜索网页、不会持续迭代修正它只能在那儿“吐词”。1.2 Agent 才是那个真正“干活”的角色如果说 LLM 是一个聪明但坐轮椅的专家那Agent就是给这个专家配上了手和脚。Agent 不是某个新模型它是一个系统一个把模型、工具、记忆、执行循环组合起来的系统。我举一个最简单的例子。你让 LLM“帮我把这个目录下所有 .txt 文件转成 .md”模型会怎么做它只能在对话框里给你一段 Python 脚本然后说“你可以自己跑一下”。而让 Agent 干同样的事它会直接列出当前目录、发现文件、写脚本、执行脚本、检查输出如果报错还会自己修再来一轮。整个过程不需要你复制粘贴任何代码它自己就把活儿干了。搜索热词里很多人在问“Agent 和 LLM 和 AI 模型的区别”区别的核心就在这儿模型负责思考Agent 负责从思考到行动的完整闭环。1.3 一个最小 Agent 的四个组成模块如果你想从代码层面理解 Agent我建议直接记住这四个部件模型Model推理内核负责理解任务、生成策略。本地可以用 GGUF 量化模型云端可以用 DeepSeek、Claude 这类 API。工具ToolsAgent 能调用的外部能力常见的有代码执行器、文件读写、网页搜索、数据库查询。在 Claude Code 里工具就是终端命令和文件操作在 MCP 体系里则是一大堆现成的服务。记忆Memory短期记忆是 Agent 手里的上下文窗口长期记忆则靠向量数据库、知识库或外部存储文件来承担。执行循环Agent Loop这是 Agent 的灵魂。观察结果、根据结果思考下一步、再行动、再观察一直循环到任务目标达成或达到终止条件。把这四个部件装进一个壳子里就形成了一个 Agent 框架业界常管这种壳叫agent harness。Claude Code 就是一个极其优秀的 harness它把不需要你重复造的轮子全部封装好了你只需要把模型 API 接进去就能跑。2. GGML 与 GGUF本地跑模型前必须搞懂的地基2.1 GGML 不是模型是一套推理方案先纠正一个常见误区。很多人把 GGML 当成某个模型或者以为 GGML 已经过时了。其实GGML 是一个 C 语言实现的张量计算库专门为本地推理而设计它的核心价值是让你能在 CPU、GPU、Apple Silicon 上高效地跑大模型不需要像 PyTorch 那样整一大套依赖环境。在 GGML 生态发展早期模型文件格式就叫 GGML后来原作者推出了升级版格式GGUF把旧格式彻底替代了。所以你今天下载到的大多数本地模型文件名后缀都是.gguf比如qwen2.5-7b-instruct-q4_k_m.gguf。这些模型跑在 llama.cpp 这类推理程序上而 llama.cpp 底层依赖的正是 GGML 库。严谨一点说GGML 是底层计算库llama.cpp 是基于 GGML 的推理程序GGUF 是模型的持久化格式。这三个名字经常一起出现但指的东西完全不同。2.2 下载模型前怎么读懂名称里的参数第一次接触 GGUF 的人会被文件名吓到一长串又臭又长里面其实全是关键信息。我拿一个典型的模型名拆给你看qwen2.5-7b-instruct-q4_k_m.ggufqwen2.5模型系列是阿里开源的那个 Qwen 2.5。7b参数量 70 亿决定模型的基础智商也决定你显存吃多少。instruct带指令微调版本适合对话和任务场景。没有这个后缀的一般是基座模型不适合直接当 Agent 用。q4_k_m量化方式。q4 表示权重用 4 bit 存储k_m 表示混合量化策略简单说就是“用较小的体积换接近原版的智力”。对于本地 Agent 来说q8_0 精度最高但体积最大q4_k_m 是性价比之王。如果显存有富余可以上 q6_k推理质量会有可感知的提升。记住一个经验值7B 模型的 q4 量化文件大概 4~5GB13B 大概 8~9GB70B 直接往 40GB 以上走普通电脑基本不用想除非你有两张 24GB 的大显存显卡。2.3 用 llama.cpp 起一个本地推理服务本地跑模型最成熟的方案还是 llama.cpp。安装方式不复杂Mac 用户直接用 Homebrewbrew install llama.cppLinux 或者想从源码编译的可以拉仓库自己编git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp cmake -B build -DGGML_CUDAON # 如果你有 NVIDIA 显卡 cmake --build build --config Release模型文件我建议从 Hugging Face 上找量化好的 GGUF以 Qwen 系列为例huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF qwen2.5-7b-instruct-q4_k_m.gguf --local-dir ./models然后启动一个带 OpenAI 兼容接口的服务这样后面 Agent 就能直接用llama-server -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 127.0.0.1 --port 8080 \ --ctx-size 8192 --n-gpu-layers -1跑起来之后你会得到http://127.0.0.1:8080/v1/chat/completions这个接口跟 OpenAI 的接口格式完全兼容。这个细节很重要因为现在绝大多数 Agent 框架都支持 OpenAI 兼容端点本地模型一旦跑成这个接口就能无缝接入各种现成的 Agent 工具不用写一堆自定义代码。3. 从 GGML 到 Agent一条本地工作链路的完整拆解3.1 Agent 的工作循环不是魔法很多人第一次用 Agent 时会觉得它“像人一样聪明”其实剥开看核心机制就是 ReAct 模式思考Reason 行动Act 观察Observe循环往复。想象一下你让一个实习生整理项目文档。他会先看一眼目录观察决定从哪里入手思考然后打开文件夹开始改行动改完检查效果再观察。Agent 的工作逻辑完全一样模型在每一步生成的内容里除了回复还会输出“下一步该调用什么工具、传什么参数”框架解析这个指令、执行工具、把结果塞回上下文再让模型继续决策。所以你会发现Agent 对模型的指令遵循能力和上下文容量要求很高。如果模型的工具调用格式都学不明白那这个 Agent 基本废了。这也是为什么本地模型跑 Agent 时7B 以下的模型体验普遍很差——不是不聪明是压根理解不了复杂的工具协议。3.2 手搓一个最小 Agent 理解全流程虽然现在有 Claude Code 这种现成框架我依然建议你手搓一个最小版本体验一下 Agent 的骨架。用 Python 写其实非常简单核心就二十来行import requests import json OLLAMA_URL http://127.0.0.1:8080/v1/chat/completions TOOLS { list_files: lambda: __import__(os).listdir(.), read_file: lambda path: open(path, encodingutf-8).read(), } def call_llm(messages): resp requests.post(OLLAMA_URL, json{ model: qwen2.5-7b, messages: messages, tools: [ { type: function, function: { name: list_files, description: 列出当前目录下的所有文件, }, }, { type: function, function: { name: read_file, description: 读取指定文件的内容, parameters: { type: object, properties: { path: {type: string} }, required: [path] }, }, }, ], }, timeout60) return resp.json()[choices][0][message] def run_agent(task): messages [{role: user, content: task}] for _ in range(5): # 最多循环 5 轮防止死循环 msg call_llm(messages) messages.append(msg) if msg.get(tool_calls): for tc in msg[tool_calls]: name tc[function][name] args json.loads(tc[function][arguments]) result TOOLS[name](**args) messages.append({ role: tool, tool_call_id: tc[id], content: json.dumps(result, ensure_asciiFalse), }) else: print(最终回复:, msg[content]) break run_agent(查看当前目录读取第一个 .txt 文件的内容并总结它说了什么)这套代码概括了 Agent 的全部核心模型收到带工具描述的请求判断需要调工具返回一段结构化的tool_calls你执行完把结果追加到上下文模型再继续推理。当你看到它自己完成了“读文件-总结内容”这个过程你就算真正学会了 Agent 的底层原理。3.3 为什么最终还是要引入现成框架手搓能帮理解但真干活时你会骂街。当你希望 Agent 能改代码、跑测试、提交 Git、同时记住多轮任务的上下文时自己维护这套循环的成本会非常高而且模型、工具、权限、并发调度、失败重试这些事情会占据你绝大部分精力。这就是为什么需要 agent harness 这类现成框架。搜索热词里频繁出现的Claude Code、n8n以及老牌的 LangChain、LlamaIndex本质上都是 harness 的不同形态。Claude Code 偏向“终端里的结对程序员”可以在项目里自主改代码n8n 偏向“工作流自动化”把 Agent 当成节点编排进业务流程LangChain 则给了开发者最大自由度随便组合模型和工具。我自己的选择是常规开发任务用 Claude Code因为它对代码项目的理解深度、上下文管理能力都不是半路出家的框架能比的要搭服务流程再用 n8n。4. 引入 Claude Code 作为 Agent 的执行外壳4.1 Claude Code 本质上是个“自动驾驶舱”Claude Code 是 Anthropic 出的命令行 Agent 工具但它绝不只是一个 Chat CLI。它最深的价值在于四件事理解项目结构它能递归读取你的项目目录构建一个代码地图知道哪些文件跟当前任务相关。安全执行命令它能在你的终端里直接执行 bash 命令、修改文件、运行测试每一步都需要授权也可以开全自动模式。持续多轮迭代跑测试报错了它会自己看报错信息定位到对应代码修改后再跑直到通过。子 Agent 调度面对大任务时它会拆成多个子任务并行或串行地调用多个子 Agent 分别处理再汇总结果。很多人问“Claude Code 和 Codex 有什么区别”。一句话Codex 更偏向代码生成和 IDE 内补全Claude Code 则是一个能主动规划、执行、排错的完整 Agent 形态。至少在能接受的范围内Claude Code 的任务完成度和上下文控制做得更让人放心。4.2 安装与初始化一步都别省略环境要求只有两样Node.js 18 以上版本以及系统要有 git。然后用 npm 全局安装npm install -g anthropic-ai/claude-code装好之后在你想要 Agent 干活的目录下执行cd ~/my-project claude如果是第一次启动它会要求你做一次登录授权把你的 API Key 或者订阅账号绑定到 CLI 上。这里我提醒一句不要因为懒就把权限全选“完全访问”特别是当你在服务器或者公司电脑上跑的时候。我习惯每次项目目录新开一个会话时先看它请求了什么命令权限再决定给不给避免 Agent 在某个上下文误导下执行了不该执行的清理命令。如果在 VSCode 里使用直接在集成终端里跑claude就行也可以在终端里输入/doctor检查环境状态。这个命令会显示当前 Claude Code 版本、授权状态、模型连接情况。4.3 不换工具只换模型Claude Code 如何接入 DeepSeek 等模型源这一节我特意单独拿出来讲因为网络搜索热词里“claude code 接入 deepseek”“cc switch deepseek”确实被问爆了。Claude Code 本身是一个 agent harness它和模型服务之间走的是 API 协议。默认配置下它直连 Anthropic 的模型服务但这不等于你只能用那一个模型源。只要对方提供了兼容 API 端点你就可以通过环境变量指过去。举个例子DeepSeek 官方提供了一个 Anthropic 兼容接口配置逻辑非常标准export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEY你的DeepSeek密钥 export ANTHROPIC_MODELdeepseek-chat配置完重新运行claude你会发现整套 Agent 工具全部照常工作但实际上推理已经走在了 DeepSeek 模型上。这个做法的核心价值在于成本Claude Code 的 Agent 循环会消耗大量 token实际使用时每轮任务都要吞进好几轮工具调用结果如果全部用高端闭源模型账单会比较惊喜。接上价格友好的模型之后十几万 token 的成本也就是一杯奶茶钱体验还不打折扣。但我也要明确一个前提这种自定义端点方案要求目标服务本身提供兼容协议并且在企业场景下大多数是内部 API 网关来做统一转发。我的建议是只要设备上装了多个模型源的密钥就用这种方式把它集中管理起来目录不同就写进各自的.env文件里互不干扰。4.4 让 Claude Code 顺手的小配置有几条配置是我每次新装后必做的能少踩很多坑模型上下文开关/config里把自动接受文件编辑打开但把自动执行权限保持为“每次询问”。这样开发效率高一些同时不至于失去控制。指定系统提示词在项目根目录放一份CLAUDE.md把项目结构、技术栈、编码规范写清楚。Claude Code 每次启动都会自动读它这个文件相当于给 Agent 写了一个“入职手册”效果立竿见影。关闭不必要的输出如果只是想让 Agent 干活不回消息用--print非交互模式跑适合在 CI 里串任务。不要先装一堆 MCP 插件MCP 是 Agent 连外部系统的标准协议Claude Code 对 MCP 支持很好。但新手最容易犯的错是看到什么 MCP 都装结果 Agent 被一堆工具定义占满了上下文反而变笨。先跑通纯文件命令操作再按需加 MCP 服务。5. 五分钟实战从零跑通一个本地 Agent 任务5.1 保底方案没有显卡也能跑如果你的电脑既没有 NVIDIA 显卡也没有大内存又想体验本地 Agent我建议先走“云端模型 Claude Code”路线。这一步不需要 GPU五分钟绝对够# 1. 安装 Node 和 Claude Code npm install -g anthropic-ai/claude-code # 2. 建一个测试项目 mkdir agent-test cd agent-test git init # 3. 配置模型源以 DeepSeek 兼容接口为例 export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEY你的密钥 # 4. 启动 claude进去之后在对话框输入“给这个项目创建一个 README.md说明它是一个 Agent 测试项目并写一个 Python 脚本来统计当前目录下文件数量”。你会看到 Claude Code 列出文件、创建文件、运行脚本、把结果贴给你。这一套流程下来确实不用五分钟。项目本身是空的它也不需要什么语义理解能力纯粹在演示 Agent 循环。5.2 进阶方案接上本地 GGUF 模型想在完全没有外部 API 的环境下跑一套 Agent也不是不行。步骤是把第 2.3 节启动的llama-server的地址告诉 Claude Code。但这里有个残酷的现实Claude Code 对模型的指令遵循和复杂推理要求很高。7B 的中小参数量模型虽然能聊天但在 Agent 场景里经常会出现流程混乱、工具调用格式不合法这类问题。我实测下来的经验是至少 14B 以上的模型才有比较可用的 Agent 体验推荐试试 Qwen 2.5 14B Instruct 的 q4_k_m 量化或者 Llama 3.1 8B 在简单任务里也能凑合。启动命令不变配置时把ANTHROPIC_BASE_URL指向http://127.0.0.1:8080模型名按 llama.cpp 里加载的模型名填就行。注意本地模型的上下文长度一定要在启动时给够不然单轮 Agent 循环里放不下工具定义加中间结果Session 直接断掉。另外一个容易被忽略的点是低配机器跑 14B 模型时生成速度慢到让人怀疑人生。如果你的 CPU 没有足够的内存带宽一个 Agent 循环十几轮要等十几分钟这时候的“五分鐘搭建”已经没有任何实际意义了。所以我的判断始终是可以把本地模型当作学习和隐私场景的备用方案但绝大多数日常 Agent 开发用一个兼容接口接云端模型才是效率最优解。5.3 排错速查表我踩过的坑全在这以下这类问题在社区里几乎每天都有人在问我这里给出一份速查清单:现象原因解法启动后连接不上模型服务ANTHROPIC_BASE_URL配错或目标服务未启动先curl一下接口地址确认通,再检查环境变量是否在当前终端生效模型一直返回重复内容上下文被工具定义撑爆减小--ctx-size之外的 token 限制,减少 MCP 工具数量Agent 无法修改文件权限没开在/permissions里允许项目目录的读写,或重新授权本地模型执行工具时乱来模型太小,指令遵循能力差换更大参数量模型,或者换回云端模型测试排除问题还有一条最隐蔽的报错Unable to connect to Anthropic services。这个词条常被搜索但它绝大多数时候不是玄学问题而是本机的网络环境无法访问目标 API或者 API Key 过期、权限不足可以先检查密钥状态和网络连通性不要一上来就重装工具。重装解决不了配置问题。5.4 在 VSCode 里把它当“结对程序员”用如果你和我一样主要开发环境是 VSCode其实不用装任何额外插件直接在终端里跑claude就是最顺畅的体验。它的输出会直接出现在终端面板文件修改会实时同步到编辑器你在编辑器里就能看到 Agent 改动代码的过程。一个更高阶的玩法是把 Claude Code 作为 Git 的辅助流程让它在分支上完成一个小功能自动跑完测试然后你 review 一下改动记录再 merge。我在实际项目中试过小任务的完成度相当不错像“写一个工具函数解析这段日期的各种格式”“批量把日志输出改成结构化 JSON”这种任务基本不需要返工。6. 我换到“本地模型 Claude Code”组合之后的真实体会6.1 不要迷信本地跑模型这件事我一开始也是“能跑本地绝不用云端”的坚定拥护者觉得模型在自己机器上跑才有掌控感。后来折腾次数多了我现在的态度是本地模型是手段不是信仰。本地 GGUF 模型最大的好处有三个隐私数据不出机器、离线可用、无限调用不心疼钱。但它的短板同样明显——受限于量化精度和参数量复杂工具调用的稳定性始终不如云端大模型而且硬件投入是真的贵。如果你有一张 24GB 显存的显卡那跑 14B 模型还能有一个体面的体验要是没有纯 CPU 推理的等待时间会让你放弃治疗。所以我现在的方案是“两条腿走路”日常编码和文件处理类的 Agent 工作走云端模型做的兼容接口因为成本可控效率拉满涉及敏感代码、保密文档或者出差在飞机上想写点东西的时候切到本地模型保证基本可用。6.2 Skills 和 MCP什么时候值得加网上关于Agent Skill和MCP的文章特别多我看了下搜索热词发现很多人都在找“skill 开发指南”和“MCP 安装教程”。我的建议很直白先别急。Skill的本质是预定义好的提示词模板 技能脚本让 Agent 遇同类任务时能按一套固定流程执行MCP则是标准化的外部工具协议把数据库、网页浏览器、飞书文档这些系统全部接入 Agent。这两样都是“锦上添花”的东西核心链路跑不通的话装再多 Skill 也只是让 Agent 多学了一堆它用不明白的口诀。我的实际推进顺序是先把模型、上下文、工具调用这个三角跑顺然后加一个最急用的 MCP 服务比如代码搜索再慢慢把常用工作流沉淀成 Skill。等 Agent 的利用率上来了你自然知道下一个该接什么。6.3 实在话五分钟是新手的最佳上手时间最后说点掏心窝子的话。标题里写了“5分钟”其实我是不希望你因为这句话产生错误的预期——五分钟能搭起来的是一个能重复执行、能干活的最小闭环不是一台替你写完整产品的超级开发机。但反过来讲五分钟如果能让你第一次亲眼看到 Agent 在你终端里列目录、改文件、跑测试、修报错那这个时间的价值就已经远超很多教程花两小时讲的理论了。我见过太多人在学 Agent 这件事上迟迟不动手一直在等“配置最舒服的那天”。实际上没有那种日子你只有先把脏活累活跑通后面优化才有参照物。你先在自己电脑上装一个 Claude Code配好模型源给它丢一个真实的小任务它跑通的那一刻你会瞬间理解所有那些抽象名词到底在说什么。