《WorkBuddy 实战蓝皮书》系列写到第三篇，前两篇聊了基础认知和本地环境搭建，后台收到不少私信，问得最多的问题集中在——装好之后怎么让它真正“通”起来？这个“通”不只是网络通畅，更是 WorkBuddy 跟你的电脑、你的资料、你的办公系统、你日常用的那些业务工具之间的连接。
所以这一篇我专门写“连接”。
我用 WorkBuddy 小半年，从单机试用一路折腾到给团队搭共享工作台，中间踩过的坑、梳理清楚的配置逻辑、还有几套实测能用的联动方案，都摊开来讲。这篇不会讲废话式的概念，全是怎么接、怎么配、怎么排查的思路和步骤，照着做基本能把 WorkBuddy 从“一个能聊天的应用”变成“真正替你干活的工作流节点”。
1. 连接到底连什么：先搞清楚 WorkBuddy 的四层连接模型
很多人以为 WorkBuddy 连接就是“能上网”，装完发现对话框能打字、能出结果，就觉得完事了。等你真正想让它帮你读本地文档、整理 Excel、定时推送消息、同步团队表格的时候，就会发现每一类需求背后都对应着不同层级的连接配置。理解这一点，后面配什么都顺。
1.1 连接的本质是能力边界，不只是网络连通
我在实战里把 WorkBuddy 的连接拆成四层，每一层解决一类问题：
第一层是服务链路连接。WorkBuddy 本身的前端应用要跟后端服务通信，后端服务要跟模型推理服务通信。这一层通了，你才能正常收货对话响应。装完以后如果提示超时、网络错误、服务不可用，基本都是这一层出了问题。
第二层是本地资源连接。WorkBuddy 要访问你电脑上的文件、文件夹、数据库或者知识库文档，需要明确的权限授权和路径配置。这一层决定了它能不能“看得见”你的工作资料。刚上手的人最容易在这里卡住——明明让 WorkBuddy 整理某个目录下的文档，它却说找不到文件，十有八九是访问范围没配置。
第三层是工具与技能连接。WorkBuddy 的能力来自它挂载的 Skill 和外部工具。每一个技能相当于一个插件接口，背后可能对应着命令执行、HTTP 请求、脚本调用或者第三方 API。你告诉它“去读一下数据库里的销售记录”，它背后其实是通过某个数据库技能连接完成的。技能没挂载或者参数不对，指令就执行失败。
第四层是业务系统连接。这是最接近真实办公场景的一层，比如钉钉多维表周同步、企业微信消息推送、邮件发送、IM 机器人之类的集成。这一层通常通过 Webhook、开放 API 或者定时任务实现，配置得当的话，WorkBuddy 就不只是你在对话框里问答的工具，而是能主动按计划干活的小助手了。
1.2 实战里最常见的误区：把四层混为一谈
我见过不少同事排查问题的姿势是——先怀疑服务器、再怀疑网络，最后把 WorkBuddy 卸载重装了三遍，才发现是本地文件夹授权没打开。因为四个层级的故障表现常常是同一个：功能没反应、任务失败、连接超时。
建议你在开始任何连接配置之前，先拿出一张纸，把你的目标需求写下来。然后问自己一个问题：这个需求依赖哪一层连接？只是要对话，那就是第一层；要读本地文件，那就是第二层加第一层；要自动跑定时任务，那就是第四层加第三层加第二层。从依赖的最底层开始排查，效率会高很多。
WorkBuddy 想成为你个人的效率中枢，“连接”是地基。地基打得稳，后面扩展技能、接自动化、上团队协作，全都顺理成章。
2. 环境选型与安装：Windows、Linux 还是网页版连接现状
《实战蓝皮书》的前一篇已经详细写过头一回安装的过程，这里我不重复安装步骤，重点聊一个我在实战里反复被问到的问题——到底该用哪个版本？以及不同版本下的连接效率有什么差异。
2.1 Windows 版适合本地办公，但要注意文件访问授权细节
我自己主力机是 Windows，WorkBuddy 的桌面版在这套系统上表现整体稳定。安装包下载后一路下一步就能装好，唯一要留意的是首轮启动后的授权弹窗。它会请求访问用户目录、临时目录和某些系统目录，很多人没细看就全部拒绝，结果后续让它“打开桌面上的报价单”直接失败。
我的建议是安装完成后先进设置，把常用工作目录（比如 D:\WorkFiles、桌面、文档目录）加进访问白名单。操作路径大概在：WorkBuddy 设置 -> 权限管理 -> 文件夹访问范围。加好之后记得测试一条指令，比如让它罗列某个目录下的文件名，能返回列表就说明通了。
在 Windows 上还有一个小坑：如果系统用户名是中文，某些版本的 WorkBuddy 在解析本地路径时会因为编码问题导致文件路径识别异常。这个不是必现问题，但如果你的电脑出现“路径不存在”但是资源管理器里路径明明存在的情况，优先检查用户名是否为中文。解决方案通常是新建一个纯英文名用户，或者调整系统的非 Unicode 程序语言设置。
2.2 Linux 服务器部署连接：适合跑定时任务和团队共享服务
如果你想把 WorkBuddy 部署成团队共享服务，或者让它 7x24 小时跑定时任务，我强烈建议放到 Linux 服务器上。Ubuntu 22.04 和 24.04 我都实测过，安装过程不复杂，核心是准备好 Node.js 运行环境和 Python 3.10+ 环境，然后执行官方脚本拉取服务端组件。
Linux 部署的意义在于：它是无人值守的。Windows 版需要保持用户登录状态，一旦锁屏或者注销，定时任务可能就挂了。而 Linux 服务端可以注册成 systemd 服务，开机自启、崩溃自动重启，非常省心。我目前在团队内部跑的那台 WorkBuddy，就是一台 2 核 4G 的旧服务器，跑了三个月没重启过一次。
不过 Linux 部署有一个需要提前规划的连接点——端口与防火墙。WorkBuddy 默认监听 3000 端口，如果你的服务器开了 UFW 防火墙，记得执行允许规则。另外如果你习惯用 Nginx 做反向代理，就把 WebSocket 升级和代理超时时间都调大一些，否则长对话场景下会出现连接被中断的情况。
2.3 网页版和本地版的连接差异
网页版的好处是免安装，打开浏览器登录就能用，适合临时机器或者外出办公。但从我自己的对比测试来看，网页版在本地文件访问能力上有明显限制，它很难像桌面版那样直接读取你本地磁盘的目录结构。如果你主要在网页版上使用，WorkBuddy 更多的定位就是一个纯对话助手。
本地版更适合做“个人效率工作台”。它可以读取本地文件、执行脚本、扫描文件夹、操作 Excel、管理下载目录等等。这背后的原因很简单：桌面客户端有本机权限，浏览器网页只能走受限协议。所以我的建议是——日常轻聊用网页版，真正要干活必须在本地客户端里操作。
3. Skill 连接与自定义指令：让 WorkBuddy 学会用你的工具
WorkBuddy 的 Skill 机制是它区别于普通聊天机器人的核心所在。Skill 可以理解为一项具体能力的封装——它知道“遇到什么指令时启用”“需要调用什么工具”“参数怎么填”。技能连接得好不好，直接决定 WorkBuddy 的智商上线。
3.1 Skill 的工作原理：模型、指令、工具三要素
拆开来看，一个 Skill 本质上是三样东西的绑定：一段触发逻辑、一段指令模板、一个或多个工具调用接口。
举个例子，我希望 WorkBuddy 能定期统计某个文件夹里新增了多少文档。那我需要给它做一个“目录统计”Skill，触发词是“统计新增”，指令逻辑是让它扫描特定目录下最近 24 小时内的文件变化情况，工具接口指向本地文件系统。这个过程你不需要懂多深的编程，WorkBuddy 的 Skill 配置界面支持自然语言描述，你把“当我说统计新增的时候，你要做什么、调用什么、返回什么”写清楚，它就能生成对应的配置。
实测下来，Skill 描述越具体，执行越可靠。比如“统计新增文件”就比“帮我看看文件夹”好一万倍。前者有明确对象，后者要靠模型猜。
3.2 我常用的五个自定义指令推荐
这里直接分享几个我实际在用的自定义指令，都是轻度办公场景非常实用的：
文件归档指令：当我输入“归档 ”时，WorkBuddy 会读取指定文件夹，按文件扩展名和修改日期自动移动到对应子目录。这个我用来处理每天下载的各种文件，实测能把桌面从“灾难现场”拯救回来。
会议纪要模板指令：输入“生成会议纪要”后，它会自动按“背景、结论、待办、负责人、截止时间”的结构整理当天的对话内容，输出一份可复制的 Markdown 文档。对于经常开线上会的场景特别好用。
日报自动汇总指令：每天下班前，它会扫描当天我在工作台上处理过的任务节点（比如读写过的文档、执行过的查询），自动生成一份日工作概要。这个指令写好后，我几乎没再手动写过日报。
Excel 交叉查询指令：输入“比对两个表格的差异，按订单号关联”之类的指令，它会调起数据表格连接技能，在本地执行数据匹配，返回差异记录。以前用 Excel 公式做一遍至少十分钟的活儿，现在变成一句话。
定时健康检查指令：这个适合部署在 Linux 服务器上，让它每隔一段时间检查一下服务日志的异常关键字，有异常就推送提醒。我用这个来盯团队共享 WorkBuddy 实例的运行状态。
3.3 自定义指令要避开的坑和参数配置心得
第一个坑是“贪多嚼不烂”。一次自定义指令只做一件事，效果远比一个“全能指令”要稳定。原因在于 WorkBuddy 底层模型在执行复杂任务时需要多步推理，每一步之间的状态延续是容易出错的环节。比如“统计文件并生成报表并发送邮件”这类复合指令，我在早期测试中经常出现“报表生成了但邮件附件为空”之类的问题。
第二个坑是参数范围越明确越好。访问文件夹范围一定要精确到具体路径，不要给“全部目录”这种宽泛授权。这既是权限安全的考虑，也是效率的考虑——路径越明确，模型查找和扫描的速度越快。
第三个心得是 Skill 需要趁热“训练”。新建一个 Skill 后，前几次使用时如果结果不理想，我会在对话里直接纠正它“以后遇到这种情况，你应该先做什么、再做什么”。WorkBuddy 会吸收这些纠偏信息并体现在后续执行中。这个特性对我这种不太想手动写复杂 JSON 配置的人来说非常友好。
4. 数据连接：历史对话、记忆迁移和本地知识库
用了一个月之后，WorkBuddy 就像一个越来越懂你的搭档，它不仅记得你之前交代过的事情，还能基于你的历史文档做出更有针对性的回答。而这一切的前提是——把数据连接做好。
4.1 历史对话记录与本地记忆如何备份迁移
换电脑或者重装系统之前，千万记得把历史对话和本地记忆迁移出来。我刚换主力机时没注意，结果旧机器上攒了两个月的对话背景全没了，WorkBuddy 像得了失忆症一样，什么都要重新介绍。
备份路径一般在 WorkBuddy 的数据目录下，Windows 上通常是安装目录的 data 文件夹，里面包含 conversation 和 memory.sqlite 两个核心文件。把这两个文件复制到新机器的对应目录下，再启动 WorkBuddy，历史对话和记忆就会恢复。Linux 部署时同理，建议定期用 crontab 计划任务把这个目录打包备份到别的位置，防止硬盘故障导致重要记忆全丢。
我个人的习惯是每周五下班前自动打包一次数据目录，保留最近 30 天的备份文件，滚动删除旧备份。这样即使哪天真出了问题，最多损失一周的记忆。
4.2 连接本地知识库：让 WorkBuddy 回答得更“懂行”
默认状态下，WorkBuddy 的知识来自它的基础模型。但如果你希望它更懂你所在的行业、团队的业务、项目的背景，就要把它跟本地知识库做连接。
WorkBuddy 的知识库连接分两层：第一层是纯文档导入，把你常见的 PDF、Word、Markdown 文件导入知识库索引；第二层是动态目录挂载，直接指定一个文件夹，WorkBuddy 会持续索引该目录下新增或变更的内容。
我的实操经验是：第二层的效果远好于第一层。因为文档导入是一次性的，后续更新还得手动操作，而目录挂载是持续性的，新增的合同、方案、制度文档往目录里一丢，WorkBuddy 立刻就知道了。
配置位置在：设置 -> 知识库 -> 新增数据源 -> 选择文件夹。索引深度、文件类型过滤、更新频率都可以自定义。我通常设置每十分钟检测一次目录变更，文件类型选 PDF、Word、Markdown、TXT，不扫描图片。
4.3 记忆迁移时的几个血泪教训
备份文件复制过去之后，一定要验证版本匹配。我吃过一次亏：从旧版 WorkBuddy 备份出来的数据文件，在新版上直接启动时出现了数据库结构不匹配的问题。解决办法是先启动新版生成初始数据，退出后在备份目录里只覆盖对话记录文件，再启动。
如果你的记忆文件里存有敏感内容，迁移时请务必通过加密通道拷贝，不要在公网环境下裸传。毕竟这里面可能有账号信息、业务数据、甚至是个人隐私，安全这根弦什么时候都不能松。
5. 业务系统连接实例：钉钉多维表同步和定时发微信消息
接下来进入最有实用价值的部分——把 WorkBuddy 接入真实办公系统。我挑了后台问得最多的两个场景详细拆解：钉钉多维表定期同步、定时发送微信消息。这两个场景做顺了，你基本就理解 WorkBuddy 跟外部业务系统连接的全部套路了。
5.1 钉钉多维表定期同步：让 WorkBuddy 当你的表格管家
场景背景：团队的项目进度表存在钉钉多维表里，每天有大量更新，我需要定期把它同步到本地工作区，用于周报汇总和数据分析。
实现方案分三步：
第一步，在钉钉开放平台创建一个企业内部应用，拿到 AppKey 和 AppSecret。如果你们公司已经有人创建过应用，可以让管理员直接授权，不用重复创建。
第二步，在 WorkBuddy 的技能中心新增一个“钉钉多维表同步”技能。填写内容时注意：选择 HTTP 请求类型的工具，方法选 GET，URL 填入钉钉开放文档里的多维表记录查询接口地址，再往请求头里绑定鉴权参数。这个步骤如果对接口不熟悉，可以先在 WorkBuddy 的对话里描述你的意图，让它帮你生成请求模板。
第三步，配置定时任务。WorkBuddy 的定时任务支持 cron 表达式，我设置的是每天 18:00 执行一次，拉取当天变化的数据记录，写入本地指定的 CSV 文件，然后生成增量摘要。
整个流程跑通之后，我每天下班前打开工作区就能看到一张当天同步好的更新表，再配合日报汇总指令，半个小时的活五分钟就干完了。
5.2 定时发送微信消息：工作提醒自动化
另一个高频需求是定时发微信消息。注意，这里要发的是企业微信或者微信网页版通道，不是个人微信，这一点要注意合规性。
我的场景是这样：每天早上 9 点，WorkBuddy 自动读取当天日历安排，把当天会议时间、待办事项整理成一段文字，通过企业微信应用消息推送到我手机上。
实现上，先把企业微信应用配置好，拿到企业 ID、应用 AgentId 和 Secret。然后在 WorkBuddy 的自动化流程里新增“发送应用消息”动作，消息模板引用“今日安排”变量的输出。定时触发设为工作日 09:00。
这套逻辑搭好以后，同事都以为我设了什么高级提醒系统，其实就是 WorkBuddy 在后台准时干活。
5.3 外部连接失败时的通用排查思路
业务系统连接最常见的错误就是鉴权失败和接口地址变化。鉴权失败要先检查密钥是否过期、IP 白名单是否包含了 WorkBuddy 的运行机器。接口地址变化则需要关注相应开放平台的公告，通常调整配置里的 URL 即可。
另外一个容易忽略的点是时区问题。服务器如果设在 UTC 时区，你设置的 09:00 触发实际会是北京时间 17:00，整个定时任务就全部乱了。建议部署时第一时间统一确认系统时区为 Asia/Shanghai，并且 WorkBuddy 的时区设置也同步调整。
6. 常见故障实录：连接失败、启动慢和网络报错速查手册
最后一个章节，把我在使用 WorkBuddy 过程中遇到的高频故障单独整理出来。这些问题的答案分散在各个技术社区和讨论群里，我按自己的实践把它们集中过了一遍，方便你直接翻对应条目。
6.1 网络连接失败 3002 的定位与解决
这是后台私信里出现频率极高的一个报错：启动后提示网络连接失败，错误码 3002。
我遇到的 3002 有两类：一类发生在首次启动阶段，通常是客户端无法连接本地网关服务；另一类发生在对话请求发送阶段，提示后端服务连接超时。
第一类处理办法：检查电脑上是否有进程占用了 WorkBuddy 内部服务的默认端口，比如 127.0.0.1:xxxx 这种本地端口被其他软件占用，会导致客户端跟本地服务握手失败。在终端里执行端口检查命令，把占用端口的进程结束后重启 WorkBuddy，大概率能恢复。
第二类处理办法：检查工作环境中的网络配置，如果是公司网络，确认是否需要设置 HTTP 代理或白名单放行。WorkBuddy 的网络设置里支持手动配置代理地址，按公司的网络要求填进去就行。
还有一种比较隐蔽的情况：安全软件或系统防火墙拦截了 WorkBuddy 的本地回环连接。Windows 上装第三方杀毒软件的朋友要多注意这一点，把 WorkBuddy 加进信任列表可以省很多事。
6.2 启动非常慢的优化方向
不少用户反映 WorkBuddy 冷启动时间很长，动不动几十秒到一分钟。这个问题我遇到过，分享一下排查经验。
先判断是初始化慢还是加载技能慢。如果是启动后界面要卡很久才能输入文字，多半是它在加载本地的知识库索引。知识库文件如果很庞大（几个 GB），首次启动的索引加载确实会耗时很久。我的优化方案是把知识库目录拆分成热数据和冷数据：热数据放常用文档，冷数据放归档文档，只在需要时挂载。
另一个常见原因是启动时自动拉起了一堆 Skill 的初始化流程，尤其是那些要对外部系统做健康检查的技能。如果某个外部系统连着好几个，全部超时一遍，启动速度自然被拖垮。解决办法是把这些技能改为手动触发，而不是开机自动加载。
6.3 一些容易被忽略的连接细节
日志文件的查看权限。排查问题的时候日志是最好用的线索，WorkBuddy 的运行日志一般在数据目录的 logs 文件夹下。遇到任何异常先去翻日志，比到处问人高效得多。
同步不成功先看任务状态。如果你设置了定时任务但没有按预期执行，查看任务列表里的最近执行状态，再点进详情看报错信息。很多定时任务失败的根因是外部接口临时不可用，重试一次就好。
模型连接偶尔会抽风。即便是本地部署的模型服务，长时间运行后也可能出现响应缓慢甚至无响应，定时或者手动重启一下模型服务进程就能恢复。我在 Linux 服务器上放了一个简单的看门狗脚本，检测到异常自动重启，从此再也没半夜爬起来处理过。
最后的经验分享
这套连接配置一点点搞定之后，WorkBuddy 在我的工作流里已经不是“偶尔问一句”的工具了。它替我盯表格、整理文件、发提醒、写草稿，我上班打开电脑先看它给我准备了什么，而不是它等我问什么。
我个人的体会是：连接工作最花时间的不是配置本身，而是想清楚边界。你希望 WorkBuddy 接管哪些事，不希望它碰哪些东西，这个边界要先划明白。文件权限给到什么范围、自动任务挂在哪个目录、外部系统哪些数据可以拉取，这些都是连接配置之前就要想好的。
如果这篇能帮你把 WorkBuddy 从“玩具”变成“工具”，那这五千字就没白写。下一篇蓝皮书我计划写《自动化篇》，重点聊聊怎么把单个技能串成真正端到端的自动化流程。等不及的朋友可以先自己试试把推送和同步组合起来，祝大家好运。
