WorkBuddy 工作空间与工作目录使用指导与大模型 API 接入配置教程

公测深度实测｜腾讯WorkBuddy七大交互痛点全梳理，AI办公Agent体验避坑指南（2026.11） 本文基于腾讯 WorkBuddy 公测版真实实测体验，全面梳理产品在任务管理、上下文对话、自动化 Agent、界面操作、模型技能调用等场景下的交互设计缺陷，同时补充视频生成功能入口不一致、国内 npm 下载默认源超时、跨工作空间自定义大模型 API 配置等实测问题，并附上具体操作体验描述。全文内容完整无遗漏、问题描述精准客观，可为开发者、测试人员及普通用户提供避坑参考，也可为产品迭代优化提供真实用户反馈依据。

目录

• 一、什么是工作空间
• 二、工作空间 vs 打开文件目录
• 三、工作空间的内部结构（项目级 vs 全局配置）
• 四、工作空间算力配置：大模型 API 接入指导（官方通道 vs 国内中转站）
• 五、能建几个工作空间
• 六、如何切换 / 修改 / 删除 / 维护
• 七、常见问题与避坑清单

一、什么是工作空间

在 WorkBuddy 里，工作空间（Workspace）本质上是承载某一个项目相关数据的本地目录。你在任务输入框左下角「选择工作空间」选定的那个文件夹，就是 WorkBuddy 本次任务读取文件、执行命令、调用大模型生成产物的边界。

• 它不是云端虚拟空间，而是你电脑上的真实文件夹。
• 它决定了「这次任务在谁的地盘上干活」。
• 一个项目 = 一个工作空间；团队共用同一项目时，大家的工作空间就是同一个项目目录。

官方文档在「创建任务」页明确：选择工作空间后，WorkBuddy 会基于该目录读取和处理文件。

二、工作空间 vs 打开文件目录

很多人会把「打开文件目录」和「工作空间」混淆。一句话总结：「打开目录」是一次性动作（看文件），「工作空间」是持久的项目上下文（干活的地盘）。

• 打开文件目录（动作）：

• 文件系统视角：仅用于浏览/编辑文件

• 不产生 .workbuddy 文件夹

• 任务/自动化不绑定，关闭即释放，不留状态

• 不能存放项目级技能 → 用完即走，纯查看/编辑

• 工作空间 Workspace（状态与边界）：

• 项目级上下文：明确的 Agent 执行边界

• 自动生成 .workbuddy 项目数据

• 绑定任务/自动化/MCP 配置与大模型对话上下文

• 跨会话持久、可团队共享，可放项目级技能 → 持续承载项目，不是缓存

三、工作空间的内部结构

每个工作空间目录下，除了你自己的项目文件（代码、文档、数据），还会自动生成一个 .workbuddy 文件夹——这是项目数据，不是缓存，请勿删除。

同时，WorkBuddy 在系统用户主目录下还会维护一个全局的 ~/.workbuddy（Windows 下通常为 C:\Users\<用户名>\.workbuddy）目录，用来存放跨所有工作空间共享的个人技能、自动化数据库以及自定义大模型 API 配置文件。

四、工作空间算力配置：大模型 API 接入指导

WorkBuddy 在工作空间内执行文件读写、表格处理、代码生成或跑自动化 Agent 时，底层依赖大模型（LLM）的工具调用（Tool Call）与推理能力。模型配置保存在全局的 models.json 中，配置一次即可在所有工作空间生效。

目前在 WorkBuddy 中接入大模型 API 主要有以下两种方式，可根据实际使用场景选择：

1. WorkBuddy 官方内置与预设提供商接入

如果日常以常规办公文档处理为主，或者手头已有主流厂商的套餐，可以直接使用官方内置通道或预设入口：

• 内置 Auto 自动模式： 默认状态下开启 Auto 模式，WorkBuddy 会根据当前工作空间的任务类型自动匹配内置模型，开箱即用。
• 官方预设提供商接入： 点击客户端左下角头像进入 设置 → 模型 → 添加模型（或在对话输入框底部点击模型切换入口选择 + 配置自定义模型）。在提供商列表中可以直接选择 腾讯云 Token Plan / Coding Plan、智谱 / Kimi Coding Plan 或 DeepSeek 等预设选项。选择预设提供商后，系统会自动填充接口 URL 以及工具调用、图片输入等能力标记，只需填入对应平台的官方 API Key 保存即可。

2. 国内托管中转站接入（以 4SAPI 为例）

在复杂工作空间（例如多文件长上下文分析、跨目录重构或高频 Agent 自动化任务）中，不少开发者需要用到 Claude、GPT 或 Gemini 等海外模型，但直连海外官方接口经常遇到网络超时断连或海外信用卡绑卡受限的问题。针对这类场景，可以通过 WorkBuddy 的「自定义模型」功能接入国内托管中转站（例如 4SAPI 这类兼容 OpenAI 协议的聚合网关）来跳过内置积分限制：

1. 打开自定义配置： 进入 设置 → 模型 → 自定义模型，点击 + 添加模型，将提供商选为 「自定义 / Custom」。
2. 填写接入参数：

• 接口地址（Base URL）： 填入中转站（如 4SAPI）提供的 OpenAI 兼容接口地址（通常以 /v1 结尾）。
• API Key： 粘贴在中转站后台创建的密钥（密钥仅保存在本地 models.json 中，不会上传至 WorkBuddy 云端，WorkBuddy 仅作为本地通信转发链路）。
• 模型名称（Model Name）： 准确填写接口支持的模型 ID（例如 claude-3-5-sonnet、gpt-4o 或 deepseek-chat），并勾选开启「工具调用」能力选项以确保工作空间 Agent 能正常读写文件。

3. 测试与启用： 点击「测试连接」确认响应正常后保存，回到工作空间对话页底部的模型选择器中，切换到刚添加的模型即可。

对于需要在多个工作空间频繁跑 Agent 任务的用户，使用这类国内托管中转站的核心优势很直观：

• 单 Key 统管多模型： 一把 API Key 即可在工作空间内按需切换 Claude、OpenAI、Gemini 及各类国产模型，无需在多个平台分别注册维护密钥。
• 国内直连防超时： 省去配置本地全局代理的繁琐，避免 Agent 在工作空间执行长耗时文件批处理时因跨国网络波动而中途报错中断。
• 按量计费易控本： 免去海外支付门槛，不同工作空间消耗的 Token 统一按量结算，便于开发者核算实际成本。

五、能建几个工作空间

官方文档没有给出硬性数量上限。 工作空间对应的是本地目录，理论上你可以为任意数量的本地目录建立工作空间。从产品能力看，自动化配置里的 cwds（工作目录数组）也印证了系统可同时关联多个工作空间。

• 项目 A 目录 → 选定后首次使用自动生成 .workbuddy → 成为独立工作空间
• 项目 B 目录 → 选定后首次使用自动生成 .workbuddy → 成为独立工作空间
• 项目 C 目录 → 选定后首次使用自动生成 .workbuddy → 成为独立工作空间

实践建议： 按项目维度建工作空间（一个项目一个目录），而不是按单次任务拆碎。同一个项目的所有成员共用同一项目目录即可，避免重复配置与数据分散。

六、如何切换 / 修改 / 删除 / 维护

1. 切换 / 修改工作空间（最常见）

直接切换即可，无需删除重建：在任务输入框左下角「选择工作空间」重新选一个目录，或打开左侧栏切换。换目录后，新任务就在新工作空间运行；此前在全局配置好的大模型 API（无论官方通道还是 4SAPI 等自定义模型）会直接保留，无需重新配置。

2. 删除工作空间（高风险）

⚠️ 此操作非常危险，可能导致不可逆的数据丢失！

WorkBuddy 不提供「一键删除工作空间」的入口；删除只能落到文件系统。若确实要移除某个工作空间目录，必须严格遵循以下流程：

1. 先备份整个目录（含 .workbuddy）。
2. 确认备份成功。
3. 用系统回收站移除（**绝不用 rm -rf**）。
4. 每批最多处理 10 个文件、验证无误后再继续。

如果只是「不想再关联该目录」，在左下角换个工作空间就够了，根本不必删除本地文件夹。

3. 维护工作空间（日常）

• 切勿误删项目数据： 不要手动删除项目下的 .workbuddy 文件夹（存有项目级技能与任务状态）。
• 安全清理临时产物： 清理 outputs 里的旧文件时，先让 Agent 生成只读报告（路径/大小/日期），不直接移动或删除；人工确认后再通过系统回收站清理。
• 规范管理自动化与配置： 自动化数据（workbuddy.db）只能用专用工具管理，绝不用 rm / sqlite3 / shell 直接删改；全局 MCP 配置位于 ~/.workbuddy/mcp.json（不是 .mcp.json）。
• 定期备份核心配置： 建议定期把项目下的 .workbuddy 以及全局目录下的 ~/.workbuddy/models.json（含自定义 API Key 配置）备份到非项目目录，并记录好备份位置。

七、常见问题与避坑清单

• 误区： 把 .workbuddy 当成普通软件缓存清理掉 → 会导致项目技能、自动化关联、任务历史状态全部丢失。
• 正确： 工作空间 = 本地项目目录；数量按项目建、按需切换。
• 注意（技能路径）： 用户级全局技能存放在 ~/.workbuddy/skills/，项目级专属技能存放在 {workspace}/.workbuddy/skills/。
• 注意（配置文件名）： 全局 MCP 配置文件名是 mcp.json（无点前缀）；全局模型 API 配置文件为 models.json。
• 注意（API 报错排查）： 若在工作空间执行任务时报错 404 或无法调用本地文件工具，先去 设置 → 模型 检查自定义模型的「模型名称」大小写是否与服务商（如官方控制台或 4SAPI 模型列表）完全一致，并确认已勾选该模型的「工具调用（Function Calling）」能力标记。
• 说明（安全底线）： 任何销毁性操作前必须二次确认并先备份；即使让 Agent 执行「先扫描」，也必须限制其只生成只读报告，绝不直接改动源文件。

参考资料：WorkBuddy 官方文档 Overview / 创建任务 / 任务对话 / 模型配置页。官方目前没有独立的「工作空间数量限制」说明，「无数量上限」系据文档逻辑推断（工作空间=本地目录），非文档明文数字，请以官方文档最新更新为准。