最近这个话题热度不低小扎不死心Manus“自研”了一个但模型用的 Claude……我没有兴趣去考证这句话里的“小扎”和“自研”是否准确单从技术角度看它戳中了一个特别普遍的产品形态越来越多的 Agent 产品外层全是自己搭的底层大模型却用的是 Claude 或者其他第三方模型。也就是说Agent 和模型从工程上早就不是一回事了。这篇文章不打算停在概念层面我会带你把这件事落地到一套可以照做的本地方案上。主角是 Claude Code——Anthropic 官方的终端 Agent。它能在本地执行命令、读写文件、批量处理文档核心能力来自 Claude 系列模型同时也可以换成其他兼容模型服务。Manus 这类云端通用 Agent 我们没办法在本地完整复现但它的典型场景之一——批量整理 Word 文件——完全可以用 Claude Code 在本地做一遍。本文会覆盖这些实操内容Claude Code 的安装与启动、第一次任务验证、用 Python 脚本配合 Agent 批量整理 Word 文档、把批量任务脚本化、切换到底层模型可替换模式以及一份从安装到运行的高频问题排查清单。适合正在研究 Agent 产品、想把终端 Agent 接进办公自动化流水线、或者想评估“模型可替换”架构的开发者。这个方案不依赖高端显卡普通笔记本就够用真正的推理能力全在模型服务端。1. “自研 Agent”到底自研了什么要弄明白“自研 Agent但模型用 Claude”这个现象先看一个通用 Agent 的完整链路。以 Manus 这类云端通用 Agent 为例一次典型任务通常要经过六个环节用户界面接收指令任务规划模块把“整理这堆 Word 文件”拆成“扫描文件 - 提取内容 - 归类 - 生成报告”工具调用模块实际去读写文件、打开网页或执行脚本记忆模块保存任务中间状态底层大模型负责推理和生成最后还有一个沙箱环境让执行过程安全落地。这六个环节里真正烧钱、烧数据、门槛最高的是底层大模型。其余环节的工程难度并不在于单个模块本身而在于把它们组合到一起之后不崩溃、不失控、不跑偏。所以当一个产品说“自研了一个 Agent”它更多时候想表达的其实是任务编排、工具链、文档处理、界面体验这些外围链路是自己写的大模型直接采购第三方服务。这个架构在当前阶段没有任何问题反而是大多数 Agent 产品控制成本、保证质量的最优选择。Agent 组件典型实现方式自研成本交互界面Web 前端 / 终端 CLI中任务规划Prompt 编排 / Agent 框架中工具调用本地脚本 / 浏览器 / API 网关较高记忆与上下文会话持久化 / 向量库中文档处理解析库 业务规则较高底层大模型Claude / DeepSeek / 自研模型非常高看清楚这个架构之后再回头看标题里那件事就一点也不奇怪了。真正需要关注的不是它“用没用自己的模型”而是它在编排层、工具层、数据层上有没有做出真实可用的能力。如果只是套了一层 UI换个模型就废掉那才是问题如果外围链路足够健壮底层模型就可以随时替换——这也正是下面我们要实践的方向。2. Manus 与 Claude Code两类 Agent 的定位差异把镜头拉近一点对比两个具体产品Manus 和 Claude Code。Manus 是云端异步执行的通用 Agent适合把一个任务丢到网页上让它慢慢干典型能力包括整理 Word 文件、搜索资料、生成报表。Claude Code 则是终端 Agent它不给你一个网页后台而是直接住在命令行里读写本地文件、执行 shell 命令、批量处理文件。两者底层都依赖大模型能力但产品形态完全不同。对比项ManusClaude Code产品形态Web / 云端异步 Agent终端命令行 Agent典型任务文件整理、资料检索、报告生成代码开发、命令执行、本地文件批量处理使用门槛网页注册后使用安装 Node.js 后通过 npm 安装运行环境云端沙箱本地电脑 / 服务器底层模型以官方说明为准默认 Claude 系列可配置其他兼容模型适合人群办公与业务用户开发者、运维、自动化工程师为什么把这两个产品放在一起因为它们都会面对同一个核心场景文档整理。很多人问“Manus 整理 Word 文件的能力到底怎么样”其实把场景拆开就是三步解析 docx 内容、按规则提取关键信息、输出成结构化表格或报告。这个过程模型负责语义理解外围工具负责文件读写和格式转换。所以只要在本地搭一套同样具备“解析 理解 输出”能力的链路就能复现接近的效果。下面我就用 Claude Code 加 Python 脚本来演示。3. Claude Code 本地部署环境准备开始之前先说清楚Claude Code 不是一个网页应用它本身是一个 Node.js 命令行程序不需要独立显卡推理能力全部来自模型服务端。前置条件清单如下操作系统macOS、Linux或 Windows 10/11。Windows 用户建议启用 WSL2大量原生 Windows 下的权限和沙箱报错换了 WSL 环境会少很多。Node.js建议使用 LTS 版本要求 18 或更高。npmNode.js 自带。模型访问凭证需要一个可以访问 Claude Code 的账号或 API Key官方服务的可用地区以 Anthropic 官方说明为准。磁盘空间程序本身占用很小主要预留的是后续文档输入输出目录。先检查环境node -v npm -v然后安装 Claude Code。推荐全局安装npm install -g anthropic-ai/claude-code如果不想全局安装或者担心 npm 全局目录权限问题也可以直接用 npx 临时运行npx anthropic-ai/claude-code安装完成后验证版本claude --version这里有一个需要特别注意的问题。Windows 下启动时如果遇到提示Workspace requires the Virtual Machine Platform on Windows原因是 Claude Code 的部分工作区功能依赖 Windows 的“虚拟机平台”组件。解决路径有两条。第一打开“启用或关闭 Windows 功能”勾选“虚拟机平台”重启系统后重试第二不折腾原生 Windows直接在 WSL2 里安装和运行。从社区反馈看第二种更省心很多依赖、权限、沙箱问题在 WSL2 下不会再出现。如果你的 npm 全局目录没有写权限安装过程会报no write permission to npm prefix。这种情况不要急着用 sudo 硬扛可以先看全局目录路径npm prefix -g然后把这个目录改成当前用户可写或者直接改用 npx 方案。改 npm prefix 的命令模板如下npm config set prefix $HOME/.npm-global执行后记得把$HOME/.npm-global/bin加到 PATH 环境变量里。4. 启动 Claude Code 并验证第一次任务进入一个专门用于测试的目录直接执行claude第一次启动会进入登录流程。不同版本的提示可能不一样常见情况是在浏览器里完成账号授权或者在终端里粘贴 API Key。如果官方服务有可用地区限制登录阶段就会暴露出来。这里不讨论任何绕过服务商限制的方法请使用官方支持的合规渠道和合法凭证。登录成功后会进入交互式对话界面。第一次验证不要做太复杂的任务先用下面的提示词确认链路是通的请先列出当前目录下的所有文件和文件夹然后找一个文本文件读取用中文告诉我它是干什么用的。判断这次验证是否成功看四个标准Claude 能调用本地命令并返回文件清单。能正确读取文件内容没有权限错误。返回内容是有意义的总结而不是空话。界面显示 token 消耗和耗时这组数据是后续批量任务的成本估算依据。如果卡在登录、网络或者权限环节直接跳到第 9 章的排查表。第一次跑通之后就可以开始接触实际场景了。5. 实战用 Claude Code 批量整理 Word 文件文档整理是 Manus 这类 Agent 最典型的落地场景之一。如果你只有两三个 Word 文件直接在 Claude Code 对话里让它读就行但如果文件数量上来了或者格式比较复杂建议先装一个 docx 解析工具把机械工作交给代码让 Agent 专注做语义理解。安装 python-docxpip install python-docx下面这个脚本会扫描inputs目录下的所有 docx 文件抽取段落数和文本预览。它的作用是降低 Agent 直接解析复杂 Office 格式的难度也方便先检查源文件是否正常。# extract_docx_meta.py # 抽取 docx 文件的关键文本信息供 Agent 后续做摘要和汇总 import glob from pathlib import Path from docx import Document def extract_meta(filepath: str) - dict: doc Document(filepath) lines [p.text.strip() for p in doc.paragraphs if p.text.strip()] full_text \n.join(lines) return { file: Path(filepath).name, paragraphs: len(lines), chars: len(full_text), preview: full_text[:600], } if __name__ __main__: for fp in sorted(glob.glob(./inputs/*.docx)): meta extract_meta(fp) print(f {meta[file]} ) print(f段落数: {meta[paragraphs]}, 字符数: {meta[chars]}) print(meta[preview]) print()实际操作时先创建inputs和output两个目录往inputs里放两三个测试 Word 文件然后先手动跑一次脚本python extract_docx_meta.py脚本输出正常后再把以下提示词发给 Claude Code先运行 python extract_docx_meta.py 扫描 inputs 目录下的所有 docx 然后把输出里的文件信息整理成一份 markdown 表格 每一行包含文件名、字符数、前几句中的主题信息保存到 output/summary.md。判断这次文档整理是否成功主要看三个点markdown 表格是否正确生成文件名和脚本输出一一对应。关键信息没有遗漏比如合同编号、时间、金额这类常见字段。Agent 没有擅自修改原始 docx 文件输出都写到了output目录。这个流程里常见失败原因有三种docx 文件是扫描图片python-docx 抽不出文字这种情况需要额外的 OCR文件被加密或加了只读保护路径中包含特殊字符导致编码问题。无论哪种情况先跑一遍解析脚本就能很快定位是文件问题还是 Agent 问题。6. 批量任务脚本化从交互式聊天到无人值守一次对话处理几十个文件容易出现上下文混乱也容易中途卡住。更工程化的做法是把 Claude Code 当成一个可以被脚本调用的任务执行器。在批量操作之前建议先看接口参数claude --help不同版本支持的非交互执行参数可能有差别但思路是统一的传入一段明确的任务提示词让它执行完就退出不进入多轮聊天。下面是一个批量处理 docx 的 shell 示例mkdir -p output for f in inputs/*.docx; do name$(basename $f .docx) echo 处理 ${name} ... claude -p 读取 ${f}提取核心要点保存为 output/${name}.md \ || echo 失败: ${name} batch_errors.log done注意这里的-p参数以你本机版本的claude --help输出为准。如果当前版本没有非交互模式就改用交互式脚本或者按官方文档推荐的方式驱动。批量任务的工程化要点有四个分批运行。每批 10 个文件跑完看日志不要一次性压给模型。成本预估。先用 3 个文件跑一轮记录单任务 token 消耗和平均耗时再乘以总文件数判断整体预算是否可接受。失败隔离。每个文件单独执行失败只记录错误日志不要中断整批任务。数据安全。外部 API 调用会把文本发送到模型服务端涉及客户合同、内部资料和个人隐私时先脱敏或更换为本地模型方案。还有一个更稳定的架构思路让 Python 脚本负责 docx 解析、字段抽取等机械操作Agent 只负责语义摘要和格式整理。这样批量任务一半靠代码一半靠模型翻车概率会明显下降。7. 模型切换把 Claude Code 接到其他模型服务标题里最值得聊的技术点其实是模型可替换。很多人看到 Claude 官方服务不可用或者按量付费成本偏高就想到能不能把 Claude Code 接到别的模型上。这个方向可行前提是你选的模型服务支持 Anthropic API 兼容格式。常见做法是通过环境变量覆盖模型服务的地址、鉴权令牌和模型名称。Linux 或 macOS 下export ANTHROPIC_BASE_URLhttps://your-endpoint.example.com export ANTHROPIC_AUTH_TOKENyour-token export ANTHROPIC_MODELyour-model-name claudeWindows PowerShell 下$env:ANTHROPIC_BASE_URL https://your-endpoint.example.com $env:ANTHROPIC_AUTH_TOKEN your-token $env:ANTHROPIC_MODEL your-model-name claude这里需要强调几个边界条件端点必须兼容 Anthropic Messages API 的请求和响应格式否则会报 400/401 错误。目前包括 DeepSeek 在内的不少模型服务方提供了 Anthropic API 兼容入口但具体路径、模型名和鉴权方式都以官方文档为准不要凭记忆猜。不要把密钥写死在文档里或提交到 git 仓库优先读取环境变量。不要向来源不明的第三方中转服务发送真实代码、密钥和客户数据这类服务可能记录你的全部请求内容。换模型后工具调用能力会直接影响任务成功率。Claude Code 的文件读写、命令执行依赖模型学会调用工具如果模型的工具调用能力不足会出现“说了不做、做了不对”的情况。也就是说模型可替换在架构上很干净但“能替换”不等于“替换后效果一样”。自己搭 Agent 工作台时建议把模型层封装在网关后面通过配置切换方便随时做 A/B 对比。8. 资源占用与性能观察方法Claude Code 这类终端 Agent 的性能观察要分两层看。第一层是本地资源它本质是一个 Node.js 进程再加上偶尔启动的子进程本身占用的内存并不大。真正的耗时大头是模型 API 的远程推理时间取决于你发送的文本长度、输出长度和模型响应速度。第二层是如果你不走云端 API而是把 Claude Code 接到本地模型服务比如通过 Ollama 这类工具起一个 Anthropic 格式兼容接口那么显存和内存占用就要看模型规模了7B 和 70B 是不同量级具体以实际模型和量化版本为准。这里给一套通用观察方法# 查看单次任务耗时 time claude -p 用一句话总结 inputs/demo.docx 的内容 # 查看 GPU 显存占用如果走了本地模型 nvidia-smi对话界面本身一般会显示 token 数和耗时批量脚本里可以把这两项写入日志。如果批量任务整体变慢优先看三点单次请求输出是否太长、模型服务是否限流、网络往返时延是否偏高。性能调优的思路也很有用限制任务范围。提示词里明确“只扫描某个目录”避免 Agent 到处翻文件。减少重复解析。先用 Python 脚本把文本抽好缓存下来再交给模型做语义处理。任务拆分。一个任务只做一件事避免超长上下文累积。控制输出长度。要求“输出 200 字以内”可以显著减少 token 消耗。9. 常见问题与排查方法下面是 Claude Code 从安装到批量运行的高频问题排查表适合直接收藏备用。问题现象可能原因排查方式解决方案npm 全局安装报 no write permissionnpm prefix 目录无写权限执行npm prefix -g查看目录修改 npm prefix 到个人目录或改用 npx启动提示需要 Virtual Machine PlatformWindows 缺少虚拟机平台组件检查“启用或关闭 Windows 功能”勾选虚拟机平台并重启或换 WSL2登录后提示 unavailable / region 限制官方服务在部分地区不可用查看官方状态和说明使用官方支持的合规渠道不讨论绕过方式npx 执行卡住首次下载依赖慢或网络问题观察终端进度输出检查网络连接等待下载完成对话报 401/403凭证错误或端点不兼容检查环境变量确认 base_url、token、model 三项配置换其他模型后任务总失败模型工具调用能力不足查看日志中是否出现工具调用记录换回默认模型或选择工具调用能力更强的模型批量任务跑到一半卡住单任务超时或输出过长查看批处理日志增加超时拆分任务加入失败重试docx 读取后输出乱码解析库版本低、文件加密或编码问题先跑 Python 脚本查看原始文本升级 python-docx确认文件未加密Claude Code 更新失败自动更新目录无写权限查看报错中的路径修复目录权限或改用 npx 临时版本这些问题的共同点是“先看日志、再定位原因、再做最小范围修改”。不要一上来就重装环境尤其是当配置文件里已经有自定义环境变量时先把它临时清空排除干扰项。10. 给“自研 Agent”的工程建议回到标题。如果真要给“自研 Agent但模型用 Claude”下一个工程结论那就是绝大多数 Agent 产品都应该默认走模型可替换架构而不是把所有赌注押在一个模型上。模型层是可以被替换的真正需要长期投入的是任务编排、工具调用、文档处理、权限控制、批量调度和用户体验这些外围链路。如果你计划自己做一个 Agent 产品我的建议是先用现成的终端 Agent 把核心工作流验证一遍。直接用 Claude Code 跑通文档整理、批量报告生成把每一步的 prompt、脚本、输出格式沉淀成模板然后再评估哪些环节值得自研哪些直接保留现成方案。模型层封装在网关后面通过环境变量切换避免把模型厂商写死在代码里。做批量任务时权限边界永远是第一优先级。给 Agent 一个最小可操作目录敏感数据先脱敏外部 API 调用前确认数据流向。办公自动化做得越顺越要谨慎处理客户信息、合同、身份数据相关文件这是工程问题也是合规问题。下一步建议很具体本地装好 Claude Code准备 3 个真实 Word 文件按第 5 节的流程跑一遍整理任务记录 token 消耗、耗时和输出质量。如果稳定再扩展到 10 个、50 个如果翻车对照第 9 节的排查表定位原因。跑通之后你基本就能理解那类“自研 Agent”产品真正的护城河在哪里了。