1. 从“paperclip”这个名字说起它到底想解决什么问题第一次看到“paperclip”这个项目名我脑子里蹦出来的画面是办公桌上那枚最不起眼的回形针。它便宜、简单、随处可见但几乎每个人的抽屉里都有一把——因为总有用得上的时候。一个用 Node.js 和 React 搭起来的 AI agent 项目取这个名字我猜作者的潜台词是这东西应该像回形针一样随手就能夹住你手头那些零散的、重复的、需要动脑子但又不想自己动手的小任务。结合关键词里的 Node.js、React、AI agents、OpenClaw以及热搜词里那一大串关于 node.js 安装、react hooks、openclaw 部署、qwen2.5-3b 关联到 openclaw 的内容可以基本判断出这个项目的定位一个基于 React 模式构建的、能思考与行动的 AI 智能体框架或应用。它大概率不是那种“大而全”的企业级平台而是偏向个人开发者、小团队快速搭建一个能跑起来的 agent 工具。那它到底解决什么问题我理解下来核心痛点有三个。第一AI agent 的开发门槛被各种框架抬得太高了。你想做一个能自己规划、自己调工具、自己反思的 agent往往要先啃完一堆抽象概念再配一堆环境最后发现跑起来的效果还不如直接调 API 写个 if-else。paperclip 如果走的是 React 模式那它的思路应该是把 agent 的“思考”和“行动”拆成类似组件的单元用状态驱动的方式去编排让前端开发者能用自己的老本行去理解 agent 的行为。第二Node.js 生态和 AI 能力的结合一直有点别扭。Python 那边有 LangChain、AutoGen 这些成熟的东西Node.js 这边虽然也有但要么太重要么文档稀烂。paperclip 用 Node.js 做运行时意味着你可以直接用 npm 装依赖用你熟悉的异步编程模型去处理 agent 的并发任务不用在 Python 和 JS 之间来回切。第三本地模型和 agent 的对接太麻烦。热搜词里反复出现 qwen2.5-3b 关联到 openclaw、openclaw ubuntu 安装教程、openclaw windows 搭建说明很多人想在自己机器上跑一个本地模型然后让 agent 去调用它。paperclip 如果能把这条链路打通让一个 3B 级别的小模型也能驱动 agent 干活那对个人开发者来说就很有吸引力了。所以这篇文章我想从实际落地的角度把 paperclip 这类项目的核心逻辑、环境搭建、React 模式在 agent 里的具体体现、以及和 OpenClaw 这类工具的配合方式掰开揉碎讲一遍。不管你是刚接触 Node.js 的新手还是已经写过几个 agent 的老手应该都能从中找到能直接抄作业的部分。2. 环境准备Node.js 版本选择和 OpenClaw 的安装顺序2.1 Node.js 到底装哪个版本别被 v24 的报错吓到热搜词里有一条很扎眼“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”。这个报错我太熟了几乎每次 Node.js 大版本更新前后都会有人踩。原因很简单你用的 nvm 或者 n 这类版本管理器它的远程版本列表还没同步到最新的版本号或者你手动指定的版本号根本不存在。对于 paperclip 这类项目我的建议是直接用 LTS 版本不要追最新的 Current 版本。截至我写这篇内容的时候Node.js 20.x 和 22.x 的 LTS 都是稳妥的选择。为什么因为 AI agent 项目通常会依赖一些原生模块比如处理向量、处理文件系统监听的这些模块对 Node.js 的 ABI 版本很敏感LTS 版本的预编译包最全你踩坑的概率最低。安装方式上Windows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包一路下一步就行。但如果你后面要跑 OpenClaw 或者 WSL 相关的东西我更推荐用 nvm-windows 来管理版本这样你可以在不同项目之间切换 Node.js 版本不会因为一个项目把全局环境搞乱。macOS 和 Linux 用户直接用 nvm 装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完之后验证一下node -v npm -v如果 node -v 输出的是 v20.x.x那就没问题。这里有个小细节npm 的版本最好也看一下Node.js 20 自带的 npm 是 10.x如果你后面要装一些对 npm 版本有要求的包可能需要手动升级 npmnpm install -g npmlatest但注意不要盲目升到最新的大版本有时候最新 npm 和某些包的兼容性反而有问题。我一般是在遇到明确的版本报错时再升。2.2 OpenClaw 的安装Windows 和 Ubuntu 两条路热搜词里关于 OpenClaw 的内容非常多openclaw 安装、openclaw 部署、openclaw ubuntu 安装教程、openclaw windows 搭建、openclaw windows companion 怎么配置、openclaw 无法安全验证 sl2 环境。这说明 OpenClaw 是一个需要一定环境配置的工具而且跨平台的支持情况不太一样。我先说结论如果你只是想在本地跑一个 agent 做实验优先考虑 Ubuntu 或者 WSL2 环境。Windows 原生环境不是不能跑但你会遇到更多路径、权限、依赖方面的问题。热搜词里那个“openclaw 无法安全验证 sl2 环境。请在 powershell 中运行 wsl --status”的提示其实就是在告诉你你的 WSL2 环境可能没装好或者没启动。在 Ubuntu 上安装 OpenClaw 的典型流程是这样的# 更新包列表 sudo apt update sudo apt upgrade -y # 安装基础依赖 sudo apt install -y curl git build-essential # 如果你用 nvm 管理 Node.js curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 # 然后按照 OpenClaw 的官方文档安装 # 通常是 npm 全局安装或者 clone 仓库后本地安装Windows 用户如果非要在原生环境跑需要先确认几件事PowerShell 的版本是不是 7有没有安装 Visual Studio Build Tools因为有些原生模块需要编译以及环境变量里 Node.js 的路径有没有配对。但说实话我强烈建议 Windows 用户直接用 WSL2在 WSL2 里装一个 Ubuntu然后在 Ubuntu 里按上面的流程走。这样你遇到问题时网上搜到的解决方案大概率能直接套用不用在 Windows 特有的报错里绕圈子。WSL2 的安装本身很简单在 PowerShell 里以管理员身份运行wsl --install装完之后重启系统会让你设置 Ubuntu 的用户名和密码。然后你就可以在 Ubuntu 终端里操作了。如果你已经装了 WSL 但不确定状态运行wsl --status这个命令会告诉你默认的 WSL 版本、内核版本等信息。如果显示 WSL2 没有正确配置可能需要运行wsl --update来更新内核。2.3 本地模型 qwen2.5-3b 和 OpenClaw 的关联热搜词里有一条“qwen2.5-3b 关联到 openclaw”这其实指向一个很实际的需求我想用本地的小模型来驱动 agent不想花 API 的钱也不想把数据发到云端。qwen2.5-3b 是一个 30 亿参数级别的模型量化之后大概 2-3GB 的显存占用普通的消费级显卡甚至 CPU 都能跑。把它和 OpenClaw 关联起来通常有两种方式一种是通过 Ollama 这类本地模型运行时来托管 qwen2.5-3b然后 OpenClaw 通过 HTTP API 去调用。Ollama 的安装很简单Ubuntu 下一条命令curl -fsSL https://ollama.com/install.sh | sh然后拉取模型ollama pull qwen2.5:3b跑起来之后Ollama 默认会在http://localhost:11434提供 API。OpenClaw 那边需要配置模型端点把它指向这个地址。另一种方式是直接用 llama.cpp 或者 text-generation-webui 来加载模型然后暴露一个兼容 OpenAI 格式的 API。这种方式更灵活但配置起来也更麻烦。对于刚开始折腾的人来说Ollama 是最省心的选择。这里有个经验3B 级别的模型在 agent 场景下的表现取决于你的任务复杂度。如果是简单的工具调用、信息提取、格式转换3B 模型够用。但如果需要多步推理、复杂规划3B 模型很容易跑偏。我的建议是先用 3B 模型把整个链路跑通确认 agent 的框架逻辑没问题然后再考虑换更大的模型或者接云端 API。这样你能分清到底是模型能力不行还是你的 agent 编排有问题。3. React 模式在 AI agent 里的具体体现3.1 为什么 agent 需要“React 模式”这里的 React 模式不是指 Facebook 那个前端框架而是Reasoning Acting的缩写。热搜词里有一条“基于 react 模式构建能思考与行动的 ai 智能体”说的就是这个。它的核心思想是agent 不是一次性把任务做完而是循环执行“思考下一步做什么 - 执行一个动作 - 观察结果 - 再思考”这个过程直到任务完成。为什么这种模式重要因为大模型本身是无状态的你给它一个输入它给你一个输出它不会自己记住上一步干了什么。如果你想让 agent 完成一个多步任务比如“帮我查一下明天北京的天气然后根据天气推荐穿什么衣服”你就需要把每一步的结果喂回给模型让它基于新的上下文继续决策。React 模式的典型循环是这样的Thought模型分析当前状态决定下一步需要做什么。Action模型选择一个工具并生成调用参数。Observation系统执行工具把结果返回给模型。重复 1-3直到模型认为任务完成输出最终答案。在 paperclip 这类项目里这个循环通常是用一个状态机或者一个 while 循环来实现的。用 Node.js 写的话大概长这样async function runAgent(task, tools, maxSteps 10) { let context [{ role: user, content: task }]; for (let i 0; i maxSteps; i) { const response await callModel(context); const { thought, action, actionInput } parseResponse(response); if (action final_answer) { return actionInput; } const observation await executeTool(action, actionInput, tools); context.push({ role: assistant, content: response }); context.push({ role: user, content: Observation: ${observation} }); } throw new Error(Max steps reached without final answer); }这段代码看起来简单但里面有几个关键决策点直接决定了 agent 好不好用。3.2 工具定义和调用格式别让模型猜React 模式能不能跑起来很大程度上取决于你怎么定义工具以及你怎么让模型输出结构化的调用指令。我见过太多人在这上面翻车模型输出的 JSON 格式不对或者工具名拼错了或者参数类型不对导致整个循环卡死。我的经验是工具定义要尽可能简单、明确参数不要太多。比如一个查天气的工具不要设计成get_weather(city, date, unit, language)这种四个参数的而是拆成get_weather(city)和get_weather_by_date(city, date)两个工具每个工具只做一件事。参数越少模型出错的概率越低。调用格式上现在比较流行的做法是让模型输出类似这样的结构Thought: 我需要查一下北京的天气 Action: get_weather Action Input: {city: 北京}然后在代码里用正则或者 JSON 解析去提取。但正则很容易被模型的各种变体搞崩所以我更推荐用JSON schema 约束或者function calling的方式。如果你用的模型支持 function calling比如 OpenAI 的 GPT-4 系列、Qwen 的某些版本直接用它原生的工具调用能力比自己解析文本靠谱得多。如果模型不支持 function calling那就需要在 prompt 里把格式要求写得非常死并且加上 few-shot 示例。比如你必须严格按照以下格式输出 Thought: [你的思考] Action: [工具名必须是以下之一get_weather, search_web, calculate] Action Input: [JSON 格式的参数] 示例 Thought: 我需要知道北京现在的温度 Action: get_weather Action Input: {city: 北京}即便如此你仍然需要在代码里做容错处理。我的做法是解析失败时不要直接抛异常而是把解析错误作为 Observation 返回给模型让它自己纠正。比如try { const parsed parseAction(response); // ... } catch (e) { context.push({ role: user, content: Observation: 解析失败错误信息${e.message}。请检查你的输出格式。 }); continue; }这样模型有机会自己修正格式而不是整个流程直接挂掉。3.3 状态管理和上下文窗口React 的 hooks 思维能帮上什么忙如果你是从 React 前端转过来做 agent 的你会发现 React 的 hooks 思维在这里意外地好用。React 里的useState、useEffect、useReducer这些概念本质上是在管理一个随时间变化的状态并且根据状态变化触发副作用。Agent 的循环也是一样的每一步的 Thought、Action、Observation 都是状态而工具调用就是副作用。在 paperclip 这类项目里如果你用 React 做前端界面那 agent 的运行状态可以很自然地用 React 的状态来管理。比如function AgentRunner({ task }) { const [steps, setSteps] useState([]); const [status, setStatus] useState(idle); useEffect(() { if (status ! running) return; async function run() { // 执行 agent 循环每步更新 steps // ... } run(); }, [status]); return ( div {steps.map((step, i) ( StepCard key{i} step{step} / ))} /div ); }这种写法让 agent 的每一步都可视化你能清楚地看到模型在想什么、调了什么工具、得到了什么结果。对于调试来说这比在终端里看日志要直观得多。但这里有个坑上下文窗口是有限的。Agent 跑得步数越多context 里积累的 Thought、Action、Observation 就越多很快就会超出模型的上下文长度限制。我的处理方式是设置一个最大步数比如 10 步超过就强制停止。对历史 Observation 做截断只保留最近 N 步的完整内容更早的只保留摘要。如果工具返回的结果特别长比如网页内容在放入 context 之前先做摘要或者只提取关键部分。这些策略没有银弹需要根据你的具体任务来调。但核心原则是不要让 context 无限膨胀否则模型会开始“遗忘”早期的关键信息。4. 从零跑通一个 paperclip 风格的 agent实操步骤和踩坑记录4.1 项目初始化和依赖选择假设我们现在要从零搭一个 paperclip 风格的 agent用 Node.js 做运行时用 React 做界面可选用 OpenClaw 或者类似的工具做模型接入。第一步是初始化项目mkdir paperclip-agent cd paperclip-agent npm init -y然后安装核心依赖。这里我列一下我实际会用到的包以及为什么选它们依赖用途为什么选它express提供 HTTP API轻量、生态成熟方便前端调用axios发 HTTP 请求比 node-fetch 更稳定拦截器好用zod参数校验工具调用的参数校验避免模型传错类型dotenv环境变量管理把 API key、模型地址等配置分离wsWebSocket 支持如果需要实时推送 agent 的每一步状态如果你要用 React 做前端还需要npx create-react-app client # 或者用 Vite更快 npm create vitelatest client -- --template react我个人的偏好是 Vite启动快配置简单对 Node.js 版本的兼容性也好。4.2 模型接入层的封装模型接入层是整个 agent 的地基。不管你后面接的是 OpenAI、Qwen 还是本地 Ollama我都建议先定义一个统一的接口然后再写具体的适配器。这样你换模型的时候只需要改适配器不用动 agent 的核心逻辑。// modelAdapter.js export class ModelAdapter { async chat(messages, options {}) { throw new Error(Not implemented); } } export class OllamaAdapter extends ModelAdapter { constructor(baseUrl http://localhost:11434, model qwen2.5:3b) { super(); this.baseUrl baseUrl; this.model model; } async chat(messages, options {}) { const response await axios.post(${this.baseUrl}/api/chat, { model: this.model, messages, stream: false, options: { temperature: options.temperature ?? 0.7, num_predict: options.maxTokens ?? 2048, }, }); return response.data.message.content; } }这里有个细节Ollama 的 API 默认是不带超时设置的如果模型推理很慢你的请求可能会一直挂着。所以最好在 axios 实例上设置一个合理的 timeout比如 120 秒。另外如果你用的是 3B 模型num_predict不要设太大否则模型会生成一堆废话浪费时间和显存。4.3 工具系统的实现注册、校验、执行工具系统是 agent 的“手脚”。我一般会用一个 Map 来注册工具每个工具包含名称、描述、参数 schema 和执行函数。// toolRegistry.js import { z } from zod; const tools new Map(); export function registerTool(name, description, schema, handler) { tools.set(name, { name, description, schema, handler }); } export function getTool(name) { return tools.get(name); } export function listTools() { return Array.from(tools.values()).map(t ({ name: t.name, description: t.description, parameters: t.schema, })); } export async function executeTool(name, input) { const tool tools.get(name); if (!tool) { return 错误未找到工具 ${name}; } const parsed tool.schema.safeParse(input); if (!parsed.success) { return 错误参数校验失败 - ${parsed.error.message}; } try { const result await tool.handler(parsed.data); return typeof result string ? result : JSON.stringify(result); } catch (e) { return 错误工具执行失败 - ${e.message}; } }注册一个查天气的工具大概是这样registerTool( get_weather, 查询指定城市的当前天气, z.object({ city: z.string().describe(城市名称如“北京”) }), async ({ city }) { // 实际调用天气 API const res await axios.get(https://api.example.com/weather?city${encodeURIComponent(city)}); return ${city}当前温度 ${res.data.temp}°C天气 ${res.data.condition}; } );注意这里的describe它会被序列化到工具的 JSON schema 里模型看到这个描述后更容易传对参数。描述写得越清楚模型用错工具的概率越低。4.4 完整的 agent 循环和错误处理把模型层和工具层拼起来就是完整的 agent 循环。我在前面给过一个简化版这里补充几个实际跑起来必须处理的细节。第一系统提示词要写清楚 agent 的身份和能力边界。不要只写“你是一个有用的助手”而要写“你是一个可以调用工具的 agent你可以使用以下工具...。当你需要信息时优先调用工具而不是凭记忆回答。当你认为任务完成时输出 Final Answer: [答案]”。第二每一步都要有日志。Agent 跑偏的时候日志是你唯一的线索。我会把每一步的 Thought、Action、Observation 都写到文件里方便事后分析。第三超时和重试。模型调用可能超时工具执行可能失败这些都要有兜底。我的做法是给模型调用设置 3 次重试每次间隔 1 秒工具执行失败时把错误信息作为 Observation 返回让模型决定是重试还是换一个工具。第四最大步数限制。这个前面提过但真的很重要。我见过 agent 陷入死循环反复调用同一个工具烧掉大量 token。设置一个硬性的 maxSteps比如 15 步超过就强制终止并返回当前已有的结果。async function runAgent(task, maxSteps 15) { const context [ { role: system, content: SYSTEM_PROMPT }, { role: user, content: task }, ]; for (let step 0; step maxSteps; step) { const response await callModelWithRetry(context); logStep(step, response); const parsed parseAgentResponse(response); if (parsed.type final) { return parsed.answer; } if (parsed.type action) { const observation await executeTool(parsed.action, parsed.actionInput); context.push({ role: assistant, content: response }); context.push({ role: user, content: Observation: ${observation} }); } else { // 解析失败让模型重新输出 context.push({ role: assistant, content: response }); context.push({ role: user, content: 你的输出格式不正确请严格按照 Thought/Action/Action Input 的格式重新输出。 }); } } return 达到最大步数限制任务未完成。; }4.5 我踩过的三个坑第一个坑模型输出的 JSON 里带了 markdown 代码块标记。比如模型输出 Action Input:json\n{city: 北京}\n我的解析器直接崩了。解决办法是在解析前先做一次清洗把json 和 去掉。这个坑很常见几乎每个做 agent 的人都遇到过。第二个坑工具返回的结果太长把 context 撑爆了。有一次我让 agent 去抓一个网页的内容结果整个 HTML 塞进了 context下一步模型直接报上下文超限。后来我加了一个截断逻辑超过 2000 字符的结果只保留前 2000 字符并在末尾加“...内容已截断”。第三个坑本地模型对工具调用的格式遵循度不高。用 GPT-4 的时候格式基本不会错换成 qwen2.5-3b 之后模型经常忘记输出 Action Input或者把工具名拼错。我的应对方式是加强 few-shot 示例并且在系统提示词里反复强调格式要求。即便如此3B 模型的出错率仍然明显高于大模型。所以如果你要做生产级的 agent模型能力是绕不过去的门槛小模型只适合做原型验证。5. OpenClaw 和 paperclip 这类项目的关系以及本地部署的取舍5.1 OpenClaw 在 agent 生态里扮演什么角色从热搜词来看OpenClaw 是一个被频繁提及的工具涉及安装、部署、Windows companion 配置、Ubuntu 安装教程等。我理解它大概率是一个agent 运行时或者 agent 编排平台提供模型接入、工具管理、任务调度这些基础能力。paperclip 如果是基于 OpenClaw 构建的那它的定位可能更偏向应用层专注于某个具体场景的 agent 实现。这种分层在 AI agent 领域很常见底层是模型和推理引擎中间是 agent 框架和运行时上层是具体的应用。OpenClaw 如果处在中间层那它的价值就是让开发者不用从零实现 agent 循环、工具注册、上下文管理这些重复劳动直接专注于业务逻辑。热搜词里还有一条“workbuddy 这种是不是也都参考了 openclaw 才搞出来的。你觉得时间对得上吧”这说明 OpenClaw 在社区里有一定的影响力可能被其他项目借鉴或参考。但具体的时间线和借鉴关系没有确凿信息我不做猜测。从技术角度看agent 框架的核心思路是相通的ReAct 循环、工具调用、上下文管理这些概念在多个项目里都会出现很难说是谁参考了谁。5.2 本地部署 vs 云端 API怎么选这是每个做 agent 的人都会面临的问题。我的建议是根据你的实际需求来分场景推荐方案理由原型验证、学习本地小模型qwen2.5-3b Ollama零成本数据不出本地随便折腾个人工具、低频使用云端 API按量付费省去环境维护模型能力强团队内部工具本地部署中等模型7B-14B平衡成本和能力数据可控生产环境、高频调用云端 API 本地缓存稳定性和能力优先成本可控本地部署最大的优势是数据隐私和零边际成本但代价是你要自己维护环境、处理模型更新、解决性能问题。云端 API 省心但长期用下来费用不低而且有网络延迟和数据合规的考量。对于 paperclip 这类项目如果你只是自己用我建议先用云端 API 把功能跑通确认 agent 的逻辑没问题再考虑迁移到本地模型。因为调试 agent 的时候你最大的敌人是模型的不确定性而不是环境配置。用能力强的模型先把流程理顺后面换小模型时你至少知道问题出在模型能力上而不是你的代码逻辑上。5.3 关于“通用 React 开发标准”的一点想法热搜词里有一条“有没有通用 react 开发标准”这个问题在 agent 开发里其实也适用。React 前端开发有一套相对成熟的社区规范组件拆分、状态管理、副作用处理、性能优化。但 agent 开发目前还没有这样的标准每个人都在摸索。我的看法是agent 开发可以借鉴 React 的很多思想但不能照搬。比如React 的组件化思想可以用来拆分 agent 的能力模块模型调用是一个模块工具执行是一个模块上下文管理是一个模块。React 的状态驱动思想可以用来管理 agent 的运行状态每一步的 Thought、Action、Observation 都是状态界面根据状态渲染。但 React 的虚拟 DOM、diff 算法这些和 agent 没关系不需要硬套。如果你是从 React 转过来做 agent 的你的优势在于对状态管理和组件化的理解这能帮你写出结构更清晰的 agent 代码。但你需要补的课是模型的基本原理、prompt 工程、工具调用的容错处理。这些是 agent 开发特有的React 的经验帮不上忙。6. 调试 agent 的实用技巧从日志到可视化6.1 日志要记什么怎么记Agent 的调试比普通程序麻烦因为它的行为是不确定的。同样的输入模型可能给出不同的输出。所以日志不能只记结果要记完整的决策过程。我一般会记录以下内容每一步的完整 prompt包括系统提示词和所有历史消息模型的原始输出不要只记解析后的结果解析后的 Thought、Action、Action Input工具执行的输入和输出每一步的耗时如果出错记录完整的错误堆栈日志格式上我偏好 JSON Lines每行一个 JSON 对象方便后续用脚本分析function logStep(step, data) { const entry { timestamp: new Date().toISOString(), step, ...data, }; fs.appendFileSync(agent.log, JSON.stringify(entry) \n); }这样你可以用jq或者写个简单的 Node.js 脚本快速筛选出所有出错的步骤或者统计平均每步的耗时。6.2 用 React 做一个简单的调试界面如果你用 React 做前端可以做一个很直观的调试界面左边是任务输入右边是 agent 的每一步执行记录每一步用一张卡片展示卡片里包含 Thought、Action、Observation。这样你一眼就能看出 agent 在哪一步跑偏了。实现上后端通过 WebSocket 把每一步推送给前端前端用useState维护一个 steps 数组每收到一条消息就追加。这个界面的代码量不大但对调试效率的提升非常明显。function DebugPanel() { const [steps, setSteps] useState([]); useEffect(() { const ws new WebSocket(ws://localhost:3001); ws.onmessage (event) { const step JSON.parse(event.data); setSteps(prev [...prev, step]); }; return () ws.close(); }, []); return ( div classNamedebug-panel {steps.map((step, i) ( div key{i} className{step step-${step.type}} div classNamestep-headerStep {i 1}: {step.type}/div div classNamestep-content{step.content}/div /div ))} /div ); }6.3 常见问题的排查思路Agent 跑不起来通常逃不出这几类问题模型不输出工具调用。可能是系统提示词没写清楚或者模型本身不支持工具调用。先检查提示词里有没有明确告诉模型“你可以使用工具”再确认模型是否支持 function calling。工具调用参数错误。检查工具的 schema 定义是否清晰参数描述是否准确。如果模型经常传错类型可以在 schema 里加更严格的约束比如z.number().int().positive()。循环不终止。检查最大步数限制是否生效以及模型是否在重复调用同一个工具。如果是可以在 Observation 里加入提示比如“你已经调用过这个工具了请尝试其他方法”。上下文超限。检查历史消息的长度加入截断逻辑。另外工具返回的结果如果太长也要在放入 context 之前做处理。本地模型响应太慢。检查模型的量化级别和硬件配置。3B 模型在 CPU 上跑每步可能要几秒到十几秒这是正常的。如果太慢考虑换更小的模型或者用 GPU 加速。7. 关于 paperclip 后续可以扩展的方向7.1 多 agent 协作单个 agent 的能力有限如果任务复杂可以考虑多个 agent 分工协作。比如一个 agent 负责规划一个 agent 负责执行一个 agent 负责检查结果。这种模式在 paperclip 这类项目里可以通过多开几个 agent 实例来实现每个实例有不同的系统提示词和工具集。但多 agent 的复杂度也高很多agent 之间怎么通信、怎么共享上下文、怎么避免死锁这些都是要解决的问题。我的建议是先把单 agent 跑稳再考虑多 agent。7.2 持久化和记忆现在的 agent 基本都是无状态的每次任务结束上下文就丢了。如果你想让 agent 记住之前的交互就需要引入持久化存储。简单的做法是用 SQLite 存历史记录复杂的可以用向量数据库做语义检索。对于 paperclip 这种个人工具级别的项目SQLite 足够了。每次任务结束后把完整的对话记录存进去下次启动时可以根据关键词或者时间范围检索。7.3 和 Obsidian 等工具的集成热搜词里有一条“openclaw obsidian”说明有人想把 agent 和笔记工具结合起来。这个方向很有意思让 agent 帮你整理笔记、生成摘要、建立笔记之间的关联。技术上Obsidian 的笔记就是本地的 markdown 文件agent 可以通过文件系统 API 去读写。如果你用 paperclip 做这个核心工作就是定义好工具读取笔记、搜索笔记、创建笔记、更新笔记。这个场景对 agent 的可靠性要求比较高因为笔记是用户的重要数据不能随便改坏。我的建议是所有写操作都要有确认机制agent 生成的内容先展示给用户用户确认后再写入。7.4 性能优化的一些思路Agent 的性能瓶颈通常在模型调用上。如果你用本地模型推理速度是硬限制。优化方向有几个减少不必要的模型调用。有些步骤可以用规则或者缓存来处理不需要每次都问模型。并行化工具调用。如果多个工具之间没有依赖关系可以并行执行减少总耗时。流式输出。模型生成的时候用流式模式用户可以更快看到部分结果体验更好。上下文压缩。定期对历史消息做摘要减少 context 长度加快推理速度。这些优化不是必须的但如果你要把 agent 用到日常工作中它们能明显提升体验。8. 一些个人体会折腾 paperclip 这类项目最大的感受是agent 的难点不在代码在预期管理。你很容易对 agent 抱有太高的期望觉得它能像人一样理解你的意图、自己规划步骤、处理各种意外情况。但实际跑起来你会发现它更像一个需要你反复调教的实习生你得把任务拆得足够细把工具描述得足够清楚把格式约束得足够死它才能稳定输出。另一个体会是本地小模型和云端大模型的差距在 agent 场景下会被放大。单轮对话的时候3B 模型和 GPT-4 的差距可能还能接受但到了多步推理、工具调用的场景3B 模型的出错率会急剧上升。所以如果你要做正经的 agent 应用模型能力是绕不过去的投入。最后日志和可视化是 agent 开发的生命线。不要等到出问题了才想起来加日志从第一天就把每一步的决策过程记下来。这样当 agent 跑偏的时候你能快速定位是提示词的问题、工具的问题还是模型本身的问题。这个习惯能帮你省下大量调试时间。