workbuddy首次启动必做三件事：一、确认workbuddy_home环境变量指向正确绝对路径，否则配置无效且静默写入默认目录；二、关闭auto_update_check并验签插件，避免登录界面卡白屏；三、检查oauth2_redirect_port（默认8089）是否被占用，否则oauth回调失败且无提示。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

WorkBuddy 首次启动不设防，但配置错一步，后续所有操作都可能写进错误目录、卡在空白页、或连 OAuth 回调都收不到——它不会报错，只会静默失效。

确认 WORKBUDDY_HOME 环境变量是否指向正确路径

WorkBuddy 启动时只认 WORKBUDDY_HOME 指向的目录，其他地方改的配置全无效。它不会提示你“配置没生效”，而是默默在 ~/.workbuddy 或 C:\Users\XXX\AppData\Roaming\workbuddy 下建一套新配置。

• Linux/macOS：终端运行 echo $WORKBUDDY_HOME，必须输出绝对路径（如 /opt/workbuddy），不能是相对路径或空
• Windows（PowerShell）：运行 $env:WORKBUDDY_HOME，值应为不含中文、空格的路径（如 C:\workbuddy）
• 若为空：macOS/Linux 编辑 ~/.zshrc 或 ~/.bash_profile，追加 export WORKBUDDY_HOME="/your/path"；Windows 在系统环境变量中新增，然后重启终端或资源管理器

关闭 auto_update_check 并验证插件签名

默认开启的自动更新检查会在首次启动时阻塞登录界面 15 秒以上，表现就是“点击登录后窗口变白”，控制台无报错，你以为卡死了，其实是它在后台等超时。

WorkBuddy Visio — Visio 兼容架构图生成器

使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表

下载

• 编辑 $WORKBUDDY_HOME/config.yaml，把 auto_update_check: true 改成 false
• 插件加载失败也不会报错：所有 .wbx 文件必须带有效签名，否则直接跳过加载。用 workbuddy-cli verify-plugin plugin.wbx 提前验签
• 开发调试可临时绕过：启动时加参数 workbuddy --disable-plugin-signature，但生产环境严禁使用

检查并释放 oauth2_redirect_port 端口

WorkBuddy 默认用 8089 接收企业 IM 的 OAuth2 回调。一旦被占用，授权流程就停在“正在跳转”，浏览器控制台只显示 ERR_CONNECTION_REFUSED，没有进一步线索。

• macOS/Linux：运行 lsof -i :8089；Windows：运行 netstat -ano | findstr :8089
• 若端口被占，要么杀掉对应进程（看 PID），要么改端口：同步修改两处——$WORKBUDDY_HOME/config.yaml 中的 oauth2_redirect_port，以及你在企业 IM 后台填的「重定向 URI」（如从 http://localhost:8089/callback 改为 http://localhost:8090/callback）
• 避开常见端口：别选 80、443、8080，它们常被 Docker、Nginx 或 macOS 自带服务占用，且部分系统对 80 有额外权限限制

这三个设置不是“可做可不做”的引导步骤，而是 WorkBuddy 启动链上的硬性依赖点。漏掉任何一个，它都能跑起来，但你永远不知道哪条路走不通——因为错误不抛出，只沉默。