A4 · 入门指南

环境安装配置

2026-07-27

本文提供 WorkBuddy 的完整安装配置指南，从系统要求到网络配置，从账号注册到常见问题排查，帮你从零搭建好工作环境。

💻系统要求

WorkBuddy 支持三大主流操作系统，以下是各平台的最低和推荐配置：

📥下载与安装

Windows 安装步骤

下载安装包
访问 workbuddy.qq.com，点击"下载 Windows 版"，获取 WorkBuddy-Setup-x64.exe（约 120MB）。
运行安装程序
双击 .exe 文件，如果弹出 SmartScreen 提示，点击"更多信息" → "仍要运行"。安装向导会自动处理依赖。
选择安装路径
默认路径为 C:\Users\{用户名}\AppData\Local\WorkBuddy，建议保持默认。如需自定义，避免路径含中文或空格。
等待安装完成
安装程序会自动下载运行时组件（约 200MB），请保持网络畅通。完成后桌面会出现 WorkBuddy 图标。
首次启动
双击图标启动，首次启动会进行环境初始化（约 10-30 秒），之后进入登录界面。

macOS 安装步骤

下载 DMG 镜像
从官网下载 WorkBuddy.dmg，Universal Binary 同时支持 Apple Silicon 和 Intel 芯片。
拖入 Applications
双击打开 DMG，将 WorkBuddy 图标拖入 Applications 文件夹。

处理安全提示

首次打开时，macOS 可能提示"无法验证开发者"。解决方法：

# 方法1：系统偏好设置 → 安全性与隐私 → 点击"仍要打开"
# 方法2：终端执行
xattr -cr /Applications/WorkBuddy.app

启动并登录
从 Launchpad 或 Applications 中启动 WorkBuddy，进入登录界面。

Linux 安装步骤

安装系统依赖

WorkBuddy 依赖 libsecret 用于密钥存储，需先安装：

# Ubuntu / Debian
sudo apt-get install libsecret-1-dev

# Fedora / RHEL
sudo dnf install libsecret-devel

下载并安装

# Debian/Ubuntu — .deb 包
wget https://workbuddy.qq.com/download/workbuddy-latest-amd64.deb
sudo dpkg -i workbuddy-latest-amd64.deb
sudo apt-get install -f   # 修复依赖

# Fedora/RHEL — .rpm 包
wget https://workbuddy.qq.com/download/workbuddy-latest-x86_64.rpm
sudo rpm -i workbuddy-latest-x86_64.rpm

# 通用 — AppImage（免安装）
wget https://workbuddy.qq.com/download/WorkBuddy-latest-x86_64.AppImage
chmod +x WorkBuddy-latest-x86_64.AppImage
./WorkBuddy-latest-x86_64.AppImage

启动 WorkBuddy

# deb/rpm 安装后
workbuddy

# AppImage 方式
./WorkBuddy-latest-x86_64.AppImage

🔑账号注册与登录

WorkBuddy 支持多种登录方式，推荐使用腾讯账号或微信扫码登录：

🔐

腾讯账号登录

使用 QQ 号或腾讯云账号登录，适合企业用户。支持 SSO 单点登录。

📱

微信扫码登录

打开微信扫一扫，扫描登录二维码即可。最快捷的登录方式。

🏢

企业微信登录

企业微信用户可直接登录，自动关联企业组织架构和权限。

🔑

API Key 登录

在设置中填入 API Key，适合 CI/CD 环境或无界面场景。

首次登录流程

选择登录方式
启动 WorkBuddy 后，在登录界面选择腾讯账号、微信扫码或企业微信。
完成身份验证
按照提示完成验证。首次使用可能需要绑定手机号接收验证码。
同意服务条款
阅读并同意《WorkBuddy 服务协议》和《隐私政策》。
进入主界面
登录成功后，WorkBuddy 会自动初始化工作空间，进入主界面。

🌐网络配置

WorkBuddy 需要联网才能使用 AI 模型和云端服务。如果你的网络环境有特殊限制，需要进行额外配置。

代理配置

如果你在公司内网或需要通过代理访问外网，WorkBuddy 支持以下代理方式：

# 方式1：在 WorkBuddy 设置中配置
设置 → 网络 → 代理服务器
  HTTP 代理：http://proxy.company.com:8080
  HTTPS 代理：http://proxy.company.com:8080
  排除地址：localhost, 127.0.0.1, *.internal.company.com

# 方式2：通过环境变量配置（适合 CLI 模式）
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

# Windows PowerShell
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"

SOCKS5 代理

# 支持 SOCKS5 代理
设置 → 网络 → 代理服务器
  SOCKS5 代理：socks5://127.0.0.1:1080

# 或通过环境变量
export ALL_PROXY="socks5://127.0.0.1:1080"

防火墙与端口

WorkBuddy 需要访问以下域名和端口，请确保防火墙放行：

# 必须放行的域名
workbuddy.qq.com          → API 服务（HTTPS 443）
cdn.workbuddy.qq.com      → 资源 CDN（HTTPS 443）
ai.tencent.com            → AI 模型接口（HTTPS 443）
mcp.workbuddy.qq.com      → MCP 连接器服务（HTTPS 443）

# 本地服务端口（仅本机访问）
127.0.0.1:9200            → 本地沙箱服务
127.0.0.1:9300            → 本地文件索引服务

⚠️ 企业防火墙注意：如果公司防火墙使用 SSL 证书拦截（SSL Inspection），WorkBuddy 可能因证书验证失败而无法连接。解决方法：将公司 CA 证书导入 WorkBuddy 的信任列表（设置 → 网络 → 证书管理）。

离线/内网部署

WorkBuddy 支持企业内网私有化部署。如果需要完全离线使用，请联系腾讯云获取私有化部署方案。私有化版本支持：

本地部署 AI 模型（需 GPU 服务器）
内网 MCP 连接器
企业 SSO 集成
审计日志对接

📁配置文件位置

了解配置文件位置，方便手动修改配置或排查问题：

Windows

# 主配置目录
%APPDATA%\WorkBuddy\
  ├── config.json          # 主配置文件
  ├── preferences.json     # 用户偏好设置
  ├── accounts.json        # 账号信息（加密存储）
  ├── mcp-config.json      # MCP 连接器配置
  └── cache\               # 缓存目录
      ├── models\          # AI 模型缓存
      └── index\           # 文件索引缓存

# 日志目录
%APPDATA%\WorkBuddy\logs\
  ├── main.log             # 主进程日志
  ├── sandbox.log          # 沙箱执行日志
  └── mcp.log              # MCP 连接器日志

# 工作区配置（每个项目独立）
{项目目录}\.workbuddy\
  ├── workspace.json       # 工作区配置
  ├── memory.json          # 项目级记忆
  └── automations\         # 自动化任务

macOS

# 主配置目录
~/Library/Application Support/WorkBuddy/

# 日志目录
~/Library/Logs/WorkBuddy/

# 工作区配置（同 Windows）
{项目目录}/.workbuddy/

Linux

# 主配置目录
~/.config/WorkBuddy/

# 日志目录
~/.local/share/WorkBuddy/logs/

# 工作区配置（同 Windows）
{项目目录}/.workbuddy/

⚙️关键配置项说明

config.json 中的常用配置项：

{
  "defaultMode": "craft",           // 默认工作模式: craft | plan | ask
  "sandbox": {
    "enabled": true,                 // 是否启用沙箱
    "timeout": 300,                  // 沙箱超时时间（秒）
    "maxMemory": "512MB",            // 沙箱最大内存
    "allowedCommands": ["*"]         // 允许的命令（* 为全部）
  },
  "mcp": {
    "autoConnect": true,             // 启动时自动连接 MCP
    "connectionTimeout": 10          // MCP 连接超时（秒）
  },
  "memory": {
    "cloudSync": true,               // 云端记忆同步
    "projectMemory": true,           // 项目级记忆
    "maxContextTokens": 32000        // 最大上下文 Token 数
  },
  "network": {
    "proxy": "",                     // 代理地址
    "requestTimeout": 30,            // 请求超时（秒）
    "retryCount": 3                  // 失败重试次数
  }
}

🔧常见安装问题排查

问题1：安装后无法启动

症状：双击图标后闪退或无反应

# Windows — 检查日志
type "%APPDATA%\WorkBuddy\logs\main.log"

# macOS — 检查日志
cat ~/Library/Logs/WorkBuddy/main.log

# 常见原因：
# 1. 端口 9200 被占用 → 关闭占用进程或修改端口
# 2. 权限不足 → 以管理员身份运行
# 3. 依赖缺失 → 重新安装，确保网络畅通

问题2：登录失败 / 网络连接错误

症状：提示"网络连接失败"或"登录超时"

# 排查步骤：
# 1. 检查网络连接
ping workbuddy.qq.com

# 2. 检查代理设置
#    如果使用代理，确认代理地址和端口正确

# 3. 检查防火墙
#    确保 443 端口出站放行

# 4. 检查 SSL 证书
#    公司网络可能有 SSL 拦截，导入 CA 证书

# 5. 检查 DNS
nslookup workbuddy.qq.com
#    如果无法解析，尝试配置 DNS 为 8.8.8.8

问题3：沙箱执行失败

症状：代码执行报错"沙箱启动失败"

# Windows — 检查 WSL2
wsl --status
# 如果未安装 WSL2：
wsl --install

# macOS / Linux — 检查 Docker（可选）
docker --version
# WorkBuddy 沙箱不强制依赖 Docker，但 Docker 模式更安全

# 检查沙箱配置
# 设置 → 沙箱 → 确认"启用沙箱"已开启

问题4：macOS 提示"已损坏无法打开"

# macOS Gatekeeper 问题，终端执行：
sudo xattr -rd com.apple.quarantine /Applications/WorkBuddy.app

# 如果还不行，在系统设置中：
# 隐私与安全性 → 安全性 → 允许从以下位置下载的应用程序
# 选择"任何来源"（需先在终端执行 sudo spctl --master-disable）

问题5：Linux 下中文显示异常

# 安装中文字体
# Ubuntu / Debian
sudo apt-get install fonts-noto-cjk

# Fedora
sudo dnf install google-noto-sans-cjk-fonts

# 安装后重启 WorkBuddy

⚠️ 重要提醒：不要从第三方网站下载 WorkBuddy 安装包，务必从官网 workbuddy.qq.com 获取。第三方渠道的安装包可能被篡改，存在安全风险。

🔄更新与卸载

自动更新

WorkBuddy 默认开启自动更新。每次启动时会检查新版本，有更新时在后台下载，下次启动自动生效。你也可以在设置 → 关于 → 检查更新中手动触发。

手动更新

# Windows — 重新下载安装包覆盖安装
# macOS — 重新下载 DMG 覆盖安装
# Linux — 重新安装 deb/rpm 包
sudo dpkg -i workbuddy-latest-amd64.deb   # Debian/Ubuntu
sudo rpm -Uvh workbuddy-latest-x86_64.rpm # Fedora/RHEL

卸载

# Windows
# 设置 → 应用 → 找到 WorkBuddy → 卸载
# 或运行卸载程序：C:\Users\{用户名}\AppData\Local\WorkBuddy\uninstall.exe

# macOS
rm -rf /Applications/WorkBuddy.app
rm -rf ~/Library/Application\ Support/WorkBuddy
rm -rf ~/Library/Logs/WorkBuddy

# Linux (deb)
sudo dpkg -r workbuddy

# Linux (rpm)
sudo rpm -e workbuddy

✅安装验证清单

安装完成后，按以下清单逐项验证，确保环境正常：

1️⃣

启动正常

WorkBuddy 主界面能正常打开，无报错弹窗。

2️⃣

登录成功

能正常登录，左下角显示用户头像和名称。

3️⃣

AI 响应正常

在对话框输入"你好"，能收到 AI 回复。

4️⃣

沙箱可用

输入"运行 echo hello"，能正常执行并返回结果。

5️⃣

文件操作正常

输入"读取当前目录文件列表"，能正常返回。

6️⃣

模式切换正常

输入 /craft、/plan、/ask 能正常切换模式。