WorkBuddy首次启动需确保WORKBUDDY_HOME环境变量正确设置、auto_update_check关闭并验证插件签名、oauth2_redirect_port端口未被占用，否则将静默失败且无提示。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
启动后立即检查 WORKBUDDY_HOME 环境变量是否生效
WorkBuddy 启动时会优先读取 WORKBUDDY_HOME 指向的配置目录，而不是当前路径或用户主目录。如果没设或设错，它会静默创建默认目录（如 ~/.workbuddy），后续所有配置、插件、日志都会写到那里，导致你改了配置文件却没生效。
- 在终端运行
echo $WORKBUDDY_HOME，确认输出是预期的绝对路径（如/opt/workbuddy） - 若为空，立刻在 shell 配置文件（
~/.zshrc或~/.bash_profile）中添加：export WORKBUDDY_HOME="/your/preferred/path"，然后source该文件 - Windows 用户需在系统环境变量中设置，且路径不能含中文或空格；PowerShell 中用
$env:WORKBUDDY_HOME="C:\workbuddy"
首次登录前必须关闭 auto_update_check 并手动验证插件签名
WorkBuddy 默认开启自动更新检查，但首次启动时若网络受限或代理未配置，它会在后台卡住 15 秒以上才超时，同时阻塞登录界面渲染——你看到的是“空白窗口”，不是崩溃。
workbuddy-pet
下载
WorkBuddy 桌宠工厂 —— 给一张角色图、一个 codex.pet 链接、一条 codex-pets.net 下载 URL、或一份现成的精灵表，就能自动创建一只可联动 WorkBuddy 状态的桌面宠物。当用户说"创建桌宠"、"做一只桌宠"、"用这张图做桌宠"、"从 codex.pet 安装桌宠"、"导入 codex 桌宠 XX"、"装一下 codex-pets.net 上的 XX&quo
- 编辑
$WORKBUDDY_HOME/config.yaml，找到auto_update_check: true，改为false - 插件目录（
$WORKBUDDY_HOME/plugins/）下任何.wbx文件都必须带有效签名，否则启动时直接拒绝加载且不报错；用workbuddy-cli verify-plugin plugin.wbx提前验签 - 跳过签名验证（仅开发调试）需显式加启动参数：
workbuddy --disable-plugin-signature，生产环境严禁使用
连接企业 IM 前先测试 oauth2_redirect_port 端口是否被占用
WorkBuddy 使用本地回环端口（默认 8089）接收 OAuth2 回调，一旦被 Chrome 插件、Zoom 或其他 Electron 应用占掉，授权流程会停留在“正在跳转”界面，控制台只显示 ERR_CONNECTION_REFUSED，无进一步提示。
- 检查端口：macOS/Linux 运行
lsof -i :8089，Windows 运行netstat -ano | findstr :8089 - 修改端口需同步改两处：
$WORKBUDDY_HOME/config.yaml中的oauth2_redirect_port，以及企业 IM 后台 OAuth 设置里的「重定向 URI」（如从http://localhost:8089/callback改为http://localhost:8090/callback） - 不要选 80/443/8080 这类常见端口——它们常被 Docker、Nginx 或其他服务预占，且部分 macOS 版本对 80 端口有额外权限限制
WorkBuddy 的“首次启动”行为高度依赖环境变量和本地端口状态，而不是界面引导。很多所谓“打不开”“卡在登录页”的问题，根源都在这三个点上，而且错误不抛异常、不写日志、不给提示。
