1. 为什么我要把 Agent 从云端搬回本地PocketBot 是一套轻量化、可私有化部署的本地 AI 自动化智能体基于 LangGraph 原生实现 ReAct 智能循环核心能力是目标拆解、长期记忆与定时自动化。它适合三类人想让 AI 帮自己干重复活的个人用户、想学 LangGraph 工程化落地的开发者、以及需要在内网跑自动化助手又不想把数据传出去的团队。我最早用云端 Agent 的时候最大的别扭不是模型不够聪明而是任务活不过一次对话。你让它整理一份资料它整理完就忘了你让它每周一汇总一次数据它根本不知道每周一是什么概念。普通对话机器人的本质是请求-响应一次会话结束上下文清空任务链条随之断裂。这不是模型能力问题是架构问题——它没有被设计成能记住、能等待、能自己醒来的东西。PocketBot 解决的就是这一段。它用 LangGraph 的 StateGraph 把 Agent 节点、工具节点、条件分支显式串起来推理过程是可控的循环而不是黑盒用 SQLite FTS5 做全文检索式长期记忆不需要额外部署向量数据库用 APScheduler 做定时调度到点自动唤醒执行不需要你保持对话在线。整套东西只依赖原生 SQLite普通 PC、小型服务器、低功耗设备都能跑起来。这篇文章不讲概念讲落地。我会带你从零搭一个能离线运行的自动化助手先装依赖再配模型通道然后写 Agent 配置片段最后跑一次完整的目标拆解验证流程。模型调用这块我用 TaoToken 统一 Key 和 API 通道来接入这样本地模型和云端模型可以随时切换不用改代码。整个过程你照着敲就能复现。需要提前说明的是PocketBot 具备文件读写和 Shell 执行能力所以它内置了沙盒机制文件操作锁定在指定工作目录Shell 命令有黑名单和超时限制WebUI 高危操作有二次确认。即便如此我仍然建议只在内网可信环境部署不要直接把服务暴露到公网。这一点后面排障章节还会再提。2. 环境准备与 TaoToken 通道接入PocketBot 的模型调度层兼容所有 OpenAI 兼容接口这意味着你既可以用 Ollama 跑本地开源模型也可以接云端大模型。我自己的做法是日常轻量任务走本地模型复杂的目标拆解和长链条推理走云端通过 TaoToken 统一管理 Key 和 Base URL切换时只改配置不改代码。先说依赖清单。PocketBot 后端是 Python 项目WebUI 是 Next.js。如果你只用 CLI 模式Python 环境就够了。我实测下来Python 3.10 以上比较稳3.11 也可以。核心依赖包括 langgraph、langchain、apscheduler、sqlite 相关库以及模型 SDK。建议用虚拟环境隔离python -m venv pocketbot-env source pocketbot-env/bin/activate # Windows 用 pocketbot-env\Scripts\activate pip install -U pip然后克隆仓库并安装依赖git clone https://github.com/jiangnanboy/pocketbot.git cd pocketbot pip install -r requirements.txt如果你要跑 WebUI还需要 Node.js 18 以上进入前端目录执行npm install。这一步耗时较长可以先放着等 CLI 验证通过再装。接下来是模型通道。PocketBot 的模型配置支持 OpenAI 兼容格式你需要准备三样东西Base URL、API Key、Model ID。我用 TaoToken 的原因是它把多个模型的调用统一到一个通道下Key 和地址固定换模型只换 Model ID。你可以先到 TaoToken 的控制台创建一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建好 Key 之后Base URL 填https://taotoken.net/api注意这个地址不带 UTM 参数是纯 API 端点。Model ID 按你实际要用的模型填比如你想用某个推理能力强的模型做目标拆解就填对应的模型标识。这里有个容易踩的坑很多人把 Base URL 写成带/v1或者带查询参数的完整地址结果请求 404。OpenAI 兼容接口的 Base URL 通常只到域名加/api这一层SDK 会自己拼/chat/completions。你如果拿不准先用 curl 测一下再写进配置。配置方式有两种。一种是在项目根目录建.env文件把 Key 写进去# .env OPENAI_API_KEY你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api DEFAULT_MODEL你的模型ID另一种是在 PocketBot 的模型预设配置里直接写。项目内置了统一模型调度层支持在 CLI 和 WebUI 中随时切换预设。我建议两种都配.env放敏感信息模型预设放可切换的候选列表。这样你既不会把 Key 提交到仓库又能快速换模型。如果你更习惯用配置文件管理PocketBot 支持 JSON 格式的模型预设。下面这段可以直接复制把 Key 和 Model ID 换成你自己的{ model_presets: { cloud_reasoning: { base_url: https://taotoken.net/api, api_key: ${OPENAI_API_KEY}, model: 你的云端模型ID, temperature: 0.3 }, local_ollama: { base_url: http://localhost:11434/v1, api_key: ollama, model: qwen2.5:7b, temperature: 0.5 } }, default_preset: cloud_reasoning }注意api_key这里用了${OPENAI_API_KEY}占位实际读取时会从环境变量注入这样配置文件本身可以安全地放进版本控制。temperature我设得比较低因为目标拆解需要稳定的结构化输出温度太高容易拆出乱七八糟的步骤。配好之后先别急着跑 Agent用一条最简单的请求验证通道是否通。这一步很关键通道不通后面全是白忙。3. 可复制的 Agent 配置与 ReAct 循环搭建通道验证通过后进入核心部分Agent 配置。PocketBot 的智能体核心是标准 StateGraph 搭建的 ReAct 执行链路包含 Agent 节点、工具节点和条件分支。你要做的是告诉它用哪个模型、开哪些工具、记忆存哪里、沙盒目录是哪个。先看目录结构。PocketBot 的工作沙盒是文件操作的边界所有读写都被限制在这个目录内。我建议单独建一个工作区不要指向你的主目录mkdir -p ~/pocketbot-workspace/{files,memory,logs}然后写 Agent 配置。下面是一个可复制的基础配置片段我把它放在config/agent.json{ agent: { name: local-assistant, model_preset: cloud_reasoning, max_iterations: 12, sandbox_dir: /home/yourname/pocketbot-workspace, memory: { backend: sqlite_fts5, db_path: /home/yourname/pocketbot-workspace/memory/memory.db }, tools: { enabled: [ file_manager, shell_exec, web_search, long_term_memory, goal_manager, scheduler ], shell_blacklist: [rm -rf /, mkfs, dd if], shell_timeout: 30 }, scheduler: { enabled: true, timezone: Asia/Shanghai } } }几个参数值得展开说。max_iterations控制 ReAct 循环的最大轮数设太小复杂任务拆不完设太大可能陷入无效循环12 是我实测比较平衡的值。shell_timeout是单条命令的超时秒数防止某个命令卡死整个 Agent。shell_blacklist是黑名单项目本身有内置的这里可以追加你自己的。ReAct 循环的工作方式是Agent 节点接收目标思考下一步该做什么决定调用哪个工具工具节点执行后把结果返回条件分支判断任务是继续还是结束。这个循环在 LangGraph 里是显式定义的所以你能看到每一步的推理轨迹而不是只拿到一个最终答案。工具方面PocketBot 内置了 23 个工具覆盖文件管理、Shell 执行、网页检索、长期记忆、目标管理、定时自动化、媒体生成、子智能体调度等九大场景。你不需要全开按需启用能减少模型的选择负担。比如你只做文档整理file_managerlong_term_memorygoal_manager就够了。长期记忆这块用的是 SQLite FTS5全文检索式。它的好处是不用额外部署向量数据库一个.db文件搞定。Agent 会把重要信息写进记忆库下次对话时通过全文检索召回。你可以手动查看记忆内容也可以让 Agent 自己管理。定时自动化是 PocketBot 区别于普通对话 Agent 的关键。内置 APScheduler 支持 Cron 表达式和固定间隔任务。配置里scheduler.enabled打开后你可以通过 CLI 或 WebUI 添加定时任务。比如每天早上九点整理一次下载目录pocketbot schedule add \ --name daily-cleanup \ --cron 0 9 * * * \ --goal 整理 ~/pocketbot-workspace/files 目录把文档按类型归档生成一份归档报告这条命令注册后即使你不开对话到点 Agent 也会自动唤醒执行。执行结果会写进日志和记忆库你下次打开就能看到。如果你要接 MCP 协议扩展工具能力PocketBot 也兼容。项目设计了动态技能系统你可以写自定义工具包不用改核心代码就能加载。仓库里内置了 PPT 生成技能可以直接体验。MCP 的接入方式是在配置里加mcp_servers字段指向你的 MCP 服务地址。不过 MCP 直连生产库这种事我不建议做工具权限要收窄只给它必要的访问范围。配置写完后用 CLI 启动一次确认 Agent 能正常加载pocketbot run --config config/agent.json --mode cli如果启动时报模型连接错误回到上一章检查 Base URL 和 Key。如果报沙盒目录不存在检查sandbox_dir路径是否真实存在且有写权限。4. 一次完整的目标拆解验证流程配置就绪后跑一次完整的目标拆解验证 ReAct 循环、工具调用、记忆写入是否都正常。我选一个真实场景让 Agent 帮我整理一批散落的 Markdown 笔记按主题归档并生成索引。启动 CLI 后直接下达目标目标把 ~/pocketbot-workspace/files/notes 目录下的所有 Markdown 文件按主题分类归档到 archive 子目录每个主题一个文件夹最后生成一份 index.md 索引列出每个主题下的文件清单。Agent 收到目标后会先做目标拆解。你会在终端看到类似这样的推理轨迹[Agent] 分析目标需要读取 notes 目录、识别文件主题、创建归档目录、移动文件、生成索引。 [Agent] 拆解步骤 1. 列出 notes 目录下所有 .md 文件 2. 读取每个文件内容提取主题关键词 3. 按主题分组 4. 创建 archive/主题 目录 5. 移动文件到对应目录 6. 生成 index.md [Tool] file_manager.list_dir - 返回 14 个 .md 文件 [Tool] file_manager.read_file - 逐个读取内容 [Agent] 主题聚类结果langgraph(5), prompt(4), tooling(3), misc(2) [Tool] file_manager.mkdir - 创建 4 个目录 [Tool] file_manager.move - 移动 14 个文件 [Tool] file_manager.write_file - 写入 index.md [Agent] 任务完成共处理 14 个文件归档为 4 个主题。这个过程里ReAct 循环至少转了六七轮每轮都是思考-行动-观察的完整闭环。你能清楚看到它为什么调这个工具、拿到什么结果、下一步怎么走。这就是显式 StateGraph 的价值——推理可控出问题能定位。执行完后验证结果ls -R ~/pocketbot-workspace/files/archive cat ~/pocketbot-workspace/files/archive/index.md你应该看到四个主题目录每个目录下是对应的 Markdown 文件index.md里列出了完整清单。如果文件没动检查沙盒目录权限如果主题分类不合理说明模型的主题提取能力不够可以换个推理更强的 Model ID 重试。接着验证长期记忆。问 Agent 一个跟刚才任务相关的问题上次我让你整理的笔记langgraph 主题下有几个文件Agent 应该能从记忆库里召回刚才的任务记录并回答5 个。如果它答不上来说明记忆写入没生效检查memory.db是否生成、FTS5 扩展是否可用。最后验证定时任务。添加一个每分钟执行一次的测试任务pocketbot schedule add \ --name test-heartbeat \ --cron * * * * * \ --goal 在 ~/pocketbot-workspace/logs/heartbeat.log 追加一行当前时间等两分钟然后查看日志cat ~/pocketbot-workspace/logs/heartbeat.log如果看到两行时间戳说明调度引擎正常工作Agent 确实能在没有对话的情况下自主唤醒执行。验证完记得删掉这个测试任务避免一直跑。这一整套流程跑通说明你的本地 Agent 已经具备目标拆解、工具调用、长期记忆、定时自动化四项核心能力。接下来就是按你自己的需求扩展工具和技能。5. 常见报错与排查对照落地过程中最容易卡在几个地方我把真实遇到过的报错和排查路径列出来你对照着看。401 Unauthorized。这个最常见基本是 Key 或 Base URL 的问题。先确认.env里的OPENAI_API_KEY没有多余空格和换行再确认 Base URL 是https://taotoken.net/api而不是带/v1或带查询参数的地址。如果 Key 是从控制台复制的注意别把前后空白带进去。还有一种情况是 Key 权限不对到 API Keys 页面确认这个 Key 有对应模型的调用权限。local proxy failed / connection refused。这个报错通常出现在你配了本地模型比如 Ollama但服务没起来的时候。检查ollama serve是否在跑端口是不是 11434。如果你用的是云端通道出现这个报错说明请求被本地网络策略拦了检查你的环境变量里有没有残留的HTTP_PROXY设置有的话清掉。Error reading choices / 返回体解析失败。这个报错说明请求发出去了但返回的 JSON 结构不符合 OpenAI 兼容格式。常见原因是 Base URL 指向了一个非兼容端点或者 Model ID 填错了导致服务端返回错误页。先用 curl 直接打一次看原始返回curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d {model:你的模型ID,messages:[{role:user,content:hi}]}如果 curl 能通而 PocketBot 不通那就是配置读取的问题检查配置文件里的字段名有没有拼错。OAuth 相关报错。如果你用的是需要 OAuth 的模型服务报错会提示 token 过期或 scope 不足。PocketBot 本身走的是 API Key 模式不涉及 OAuth 流程。如果你在 Codex 的auth.json里配了 OAuth 凭证又想复用注意格式差异auth.json里的字段和 PocketBot 的模型预设不是一套。建议分开管理别混用。沙盒权限拒绝。Agent 报permission denied时先确认sandbox_dir存在且当前用户有写权限。如果你把沙盒指向了系统目录大概率会被拒。另外 Shell 命令如果命中黑名单也会被拦报错里会提示命令被阻止。这是预期行为不要为了跑通就去掉黑名单。定时任务不触发。检查scheduler.enabled是否为 true时区设置是否正确。Cron 表达式是五段式分 时 日 月 周别写成六段。如果任务注册成功但不执行看日志里有没有调度器启动的记录。还有一种情况是进程被杀了APScheduler 是进程内调度进程没了任务自然不跑长期运行建议用 systemd 或 supervisor 托管。记忆召回不准。FTS5 是全文检索对中文分词支持有限。如果你的记忆内容以中文为主召回效果可能不如预期。解决办法是在写入记忆时让 Agent 附带关键词标签检索时用标签加全文双路召回。这个可以在自定义技能里实现。排查的核心思路是分层先确认通道通不通curl 测再确认配置读没读对打印配置最后确认工具权限够不够看沙盒和黑名单。大部分问题在前两层就能定位。6. 把本地 Agent 接进你的日常工作流跑通验证流程之后真正有价值的是把它接进日常。我自己的用法是三条线并行一条是定时线用 Cron 跑周期性任务比如每天早上整理下载目录、每周汇总一次项目日志一条是交互线需要临时处理复杂任务时开 CLI 或 WebUI 直接下达目标还有一条是服务线把 PocketBot 的 OpenAI 兼容 API 暴露给内网其他工具调用让它当本地 AI 服务底座。服务线这块值得多说一句。PocketBot 提供了 SSE 流式对话、WebSocket 实时通讯同时实现了 OpenAI 兼容 API。这意味着你内网里任何支持 OpenAI 接口的软件都可以把 Base URL 指向 PocketBot由它来调度背后的模型。这样你只需要维护一套模型通道配置所有工具共享。模型通道我仍然建议用 TaoToken 统一管理。原因是本地模型和云端模型的能力差异明显本地模型跑简单任务够用且免费但遇到需要长链条推理的目标拆解云端模型的稳定性更好。用统一通道的好处是切换成本低改一个 Model ID 就行不用重新配 Key 和地址。如果你要长期跑编码类或 Agent 类任务可以看看 Coding Plan 方案按用量规划比零散调用更划算模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite安全边界再强调一次。PocketBot 有文件读写和 Shell 执行能力沙盒和黑名单是底线但底线之上仍然要靠部署环境兜底。只在内网可信环境跑不要暴露公网不要给它生产库的直连权限MCP 扩展的工具权限要收窄到最小必要范围。这些不是限制是让自动化能长期稳定运行的前提。最后给一个实用技巧把常用的目标写成模板存起来用的时候直接调用不用每次重新描述。比如整理目录、生成周报、监控网页变化这几个高频场景各写一个目标模板配合定时任务基本就能覆盖个人自动化的八成需求。Agent 的价值不在于一次对话多聪明而在于它能记住、能等待、能重复执行——这才是本地自动化助手真正省时间的地方。