WorkBuddy 新手配置指南：本地桌面 AI 助手、模型 API 和沙箱权限怎么设置
用过十几个 AI 工具后你会发现，真正想长期留在桌面上的没几个。要么是网页版来回切换太麻烦，要么是本地部署的配置门槛高到让人想放弃。WorkBuddy 这个国产桌面 AI 助手最近出现在不少人视野里，它最大的特点就是能把不同模型捏在一起，再通过沙箱把权限管起来。但新手第一次打开它，面对工作空间路径、内置模型和自定义 API 的区别、沙箱怎么开，还是会有点懵。这篇文章就拆开这些配置项，不讲虚的，只讲你怎么一步步搭好，尤其是在代理环境下怎么让连接更稳，以及如果你有一台 VPS，能不能把它当成远程 AI 服务跑起来。
WorkBuddy 能干什么，为什么要关心 API 和沙箱？
简单说，WorkBuddy 是一个桌面端的 AI 工作流平台，你可以在它里面使用各种大语言模型（内置的或者自己接入的），然后让它根据你的指令操作本地文件、跑脚本、处理文档，甚至执行一些自动化任务。它的价值在于把 AI 的“思考”和“行动”连在了一起。
但问题也出在这里：一旦 AI 能读写你的文件、执行代码，权限就成了核心风险。WorkBuddy 引入了一个沙箱模式，限制 AI 能接触的文件夹范围。如果你只是用它的聊天功能，沙箱对你影响不大；但如果你打算让它帮你整理文档、批量重命名文件，那沙箱就是安全底线。
另一个关键点是 API。内置的模型（比如 WorkBuddy 自己的 MoE 模型）开箱即用，但如果你手头有 OpenAI、Claude 或者本地搭建的 ollama 服务，你想用自己的 API Key，就得配置“自定义 API”。这部分涉及端口、代理和请求格式，也是新手最容易卡住的地方。
第一步：安装与工作空间路径选择
WorkBuddy 支持 Windows 和 macOS，下载安装包直接装就行。默认工作空间在用户目录下的 WorkBuddy 文件夹，你也可以在设置里改成别的路径。这里有个容易被忽略的点：工作空间是 AI 读写文件的根目录，沙箱默认也只允许访问这个目录下的内容。如果你想让 AI 操作桌面或者别的盘，需要在沙箱设置里额外添加授权路径（后面会细说）。
建议一开始就选一个专用的文件夹，比如 D:\WorkBuddyWorkspace 或者 ~/Documents/WorkBuddy，不要直接指向整个文档目录。这样即便 AI 误操作，影响范围也有限。
内置模型和自定义 API：各自适合什么场景？
WorkBuddy 内置的 MoE 模型（官方名称是 WorkBuddy-Lite）在日常问答、简单文件操作上够用，而且零配置。但如果你需要更强的推理能力，比如代码生成、长文本分析，或者你想用特定的模型（比如 GPT-4o 或者本地部署的 Qwen2.5），就必须走自定义 API。
对比表：内置模型 vs 自定义 API
| 对比项 | 内置模型 | 自定义 API |
|---|---|---|
| 配置复杂度 | 无（开箱即用） | 需要填写 API URL、Key、模型名称 |
| 模型能力 | 中等，适合日常对话和简单任务 | 取决于接入的模型（如 GPT-4、Claude 3.5、本地开源模型） |
| 网络要求 | 连接 WorkBuddy 服务器 | 连接你自己指定的 API 服务端 |
| 数据隐私 | 数据经过 WorkBuddy 云服务器 | 数据直接发到你的 API 端点，隐私更可控 |
| 成本 | 免费额度用得少，超出需付费 | 按自备 API 的计费方式（比如 OpenAI 按 token ） |
| 适用场景 | 新手试用、简单文件整理 | 开发者、重度用户、对模型有特定偏好的人 |
如果你选择自定义 API，需要知道三个参数：API Base URL、API Key 和 模型名称（Model ID）。WorkBuddy 兼容 OpenAI 的 API 格式，所以大多数提供 OpenAI 兼容接口的服务（包括 ollama、vLLM、甚至一些反向代理工具）都能直接接入。
沙箱模式：权限隔离的两种级别
WorkBuddy 的沙箱不是二进制开关，而是分三个级别：
- 无沙箱（默认）：AI 可以访问整个系统文件（按操作系统权限）。不推荐在生产环境这么用。
- 工作空间沙箱：AI 只能读写工作空间文件夹内的文件。这是最常用的模式。
- 严格沙箱：只允许 AI 读写工作空间下特定的子文件夹，并且禁止执行系统命令。适合处理敏感数据。
设置路径在“设置 > 沙箱与安全”。你可以随时切换，但切换后 WorkBuddy 会重新启动才能生效。
一个实际例子：你可以设一个工作空间 ~/WorkBuddy/ProjectA，然后在严格沙箱里只允许 AI 访问这个文件夹。AI 想读 ~/Desktop 里的文件会直接被拒绝，并在日志里记录权限异常。这种日志排查起来很方便，直接在“活动日志”里能看到每步操作的权限结果。
代理环境下怎么让 API 连接更稳定
国内用户或者公司网络环境经常要过代理。WorkBuddy 目前没有内置的代理设置面板，它依赖系统代理或环境变量。如果你用的是 HTTP 代理，需要在终端或者系统网络设置里配置。常见做法：
- 系统代理：Windows 在“设置 > 网络 > 代理”里打开，macOS 在“系统设置 > 网络 > 代理”。WorkBuddy 会自动继承系统代理。
- 环境变量：在终端启动 WorkBuddy 前设置
HTTPPROXY、HTTPSPROXY。如果用的是 clash 等代理客户端，确保允许局域网连接。 - 反向代理到 VPS：如果你有一台海外的 VPS，可以把 API 请求通过隧道转发。例如用 gemini-web2api 部署到 VPS 这类工具，把 OpenAI 兼容的 API 反代到本地，WorkBuddy 直接连本地的
127.0.0.1:8080就行，省去系统代理的麻烦。
如果你在公司网络下经常遇到连接超时，检查一下是否有防火墙拦截了目标 API 服务器的端口。WorkBuddy 默认使用 443 端口（HTTPS），如果只有 HTTP 代理能过，你可能需要调整 API 为 HTTP 并确保 WorkBuddy 的沙箱不阻止该连接。
进阶思路：WorkBuddy 能不能部署到 VPS 上当远程 AI 服务？
WorkBuddy 本身是桌面应用，没有官方 server 版本。但如果你有一台 Linux VPS，可以试试用 Docker 或者远程桌面来运行它。更实际的做法是：把 WorkBuddy 安装在自己的本地电脑上，然后利用 VPS 作为 API 的中转或者模型服务的后端。
例如，你可以在 VPS 上部署 ollama 或者 vLLM，再用类似 Local Deep Research 部署到 VPS 的方法搭建一个私有 API 端点。然后 WorkBuddy 连这个端点，既用上了 VPS 的计算资源，又避免了在本地折腾显卡。这种方式对大模型推理特别有用，因为工作站级 GPU 成本太高，年付几十美元的 VPS（比如 HostEons 之类的便宜套餐）反而更划算。
不过要注意，WorkBuddy 的沙箱和文件权限在远程场景下会有变化——如果 WorkBuddy 运行在本地，沙箱只控制本地路径；如果你通过 VNC 或 RDP 在 VPS 上跑 WorkBuddy，沙箱的控制范围就变成了 VPS 的文件系统。权限设计逻辑不变，但部署复杂度增加了。
常见问题排查清单
1. 自定义 API 连接不上
- 检查 API Base URL 是否以
/v1结尾（例如https://api.openai.com/v1）。 - 确认 API Key 没有空格和换行。
- 在浏览器里访问
https://api.openai.com/v1/models测试网络是否通。 - 如果使用了代理，确认代理已正确配置且无验证。
2. 沙箱模式下 AI 无法操作文件
- 确认文件在工作空间目录内。
- 检查沙箱级别是否为“工作空间沙箱”或“严格沙箱”，且没有额外限制子文件夹。
- 查看活动日志，找到“权限拒绝”记录，根据提示放行路径。
3. 内置模型报错或超时
- 检查网络是否能访问
api.workbuddy.ai。 - 有时候使用量超过免费限制会报错，可以切换到自定义 API 测试。
4. 工作空间路径更改后 AI 找不到文件
- 更改路径后需要重启 WorkBuddy。
- 如果原来工作空间里有任务引用旧路径，需手动迁移或重建。
总结与建议
WorkBuddy 的价值在于把多个模型整合到一个桌面环境里，同时用沙箱做安全兜底。刚开始接触不要急着把所有模型都接上，先用内置模型跑通工作空间和沙箱，确认 AI 能按你的权限预期操作文件。之后再逐步接入自定义 API，测试代理下的稳定性。如果你本身有 VPS 并且习惯自建服务，可以把它和 WorkBuddy 结合起来，把模型推理放到远端，本地只跑轻量客户端。这样既省电，又能在不同设备间共享同一个 AI 服务。
需要人工核实的地方：WorkBuddy 的具体免费额度、内置模型的定价以及沙箱各级别的精确功能描述，请以官方的用户文档或最新发布日志为准。本文的代理配置步骤和环境变量方法在不同操作系统版本下可能略有差异，建议先在小环境中验证。
原创文章，作者：兆润，如若转载，请注明出处：https://vpscn2gia.com/workbuddy-local-ai-assistant-api-sandbox-guide/
