CoWork-OSS 完全指南：构建安全、本地优先的 AI 自动化工作流

在当今的数字化工作环境中，我们经常需要处理大量的文件整理、文档生成和数据分析任务。随着大语言模型（LLM）的普及，利用 AI Agent 来处理这些繁琐工作已成为趋势。然而，数据隐私、安全性和可控性始终是悬在用户头顶的达摩克利斯之剑。如果你的 AI 助手不仅能帮你干活，还能在你的本地机器上安全运行，并且所有的文件操作都在你的掌控之中，那会是一种怎样的体验？
CoWork-OSS 正是这样一款工具。它是一个开源的、本地优先的 AI Agent 工作台，专门用于在文件夹作用域内运行多步骤任务。它允许你“自带密钥”（BYOK），支持 Anthropic API、AWS Bedrock 或完全离线的 Ollama 本地模型。
本文将深入探讨 CoWork-OSS 的核心功能、安全性设计、安装配置流程以及如何利用它来提升你的工作效率。

什么是 CoWork-OSS？

CoWork-OSS 是一个运行在 macOS 上的桌面应用程序（目前支持 macOS，跨平台支持正在计划中）。它的核心设计理念是“本地优先”和“文件夹作用域”。这意味着它的任务状态、事件记录和工件索引都存储在本地的 SQLite 数据库中，而不是云端。同时，它的文件操作被严格限制在你选择的文件夹内，无法越界访问系统敏感区域。

CoWork-OSS Interface

图 1: CoWork-OSS 的终端风格用户界面

这款工具采用了终端风格的 UI 设计，使用等宽字体和状态指示符（如 `[✓]`），为熟悉命令行的用户提供了友好的键盘导航体验。它并不试图掩饰自己是一个技术工具的事实，反而通过透明化的运行机制，让用户清楚地看到 Agent 的每一个决策和操作。
## 核心特性与功能
CoWork-OSS 不仅仅是一个简单的聊天机器人，它是一个具备多任务处理能力的 Agent 系统。
### 1. 基于任务的工作流
CoWork-OSS 采用“计划-执行-观察”的循环机制。当你提出一个任务时，Agent 首先会制定一个执行计划，然后逐步执行每个步骤，并观察结果，最后产出最终的文件或报告。这种机制使得复杂任务（如“整理下载文件夹并生成报表”）变得可控且可追踪。
### 2. 强大的技能系统
这是 CoWork-OSS 最实用的部分。它内置了多种专业技能，可以直接生成专业的 Office 格式文档：
* **Excel 电子表格 (.xlsx)**：支持多个工作表、自动调整列宽、格式设置和筛选器。
* **Word 文档 (.docx)**：支持标题、段落、列表、表格和代码块。
* **PDF 文档**：支持专业格式和自定义字体。
* **PowerPoint 演示文稿 (.pptx)**：支持多种布局、主题和演讲者备注。
此外，它还具备文件夹组织技能，可以按照文件类型、日期或自定义规则对文件进行归档。
### 3. 浏览器自动化
通过集成 Playwright，CoWork-OSS 拥有了完整的网页控制能力。它可以：
* 导航至 URL 并截取屏幕截图。
* 点击按钮、填写表单、输入文本和按键。
* 提取页面内容、链接和表单数据。
* 滚动页面、等待元素加载或执行 JavaScript。
这意味着你可以让它去抓取网页数据、自动化某些网站的操作流程，并将结果保存为 PDF 或 Excel。
### 4. 远程控制集成
对于需要随时随地监控任务进度的用户，CoWork-OSS 提供了 Telegram Bot 和 Discord Bot 集成。
* **Telegram Bot**：通过简单的命令（如 `/workspaces`, `/task`），你可以远程创建任务、选择工作区并接收流式更新。
* **Discord Bot**：支持斜杠命令和直接消息，允许你在 Discord 服务器或私信中与 Agent 交互。
这两种集成都支持安全配对模式，确保只有授权的用户才能控制你的本地工作区。
### 5. 透明的运行时
在 CoWork-OSS 中，没有任何“黑盒”操作。它提供了一个实时的时间轴，显示 Agent 的每一步行动、每一个工具调用以及每一次决策。你可以清楚地看到它是如何思考的，以及它想对你的文件做什么。
## 安全性与数据保护
在使用任何具备文件操作权限的 AI 工具时，安全性都是首要考虑因素。CoWork-OSS 在这方面做出了明确的设计和警告。

CoWork-OSS Welcome Screen

图 2: 启动时的 AI 披露与安全提示

### ⚠️ 重要警告：数据丢失风险
CoWork-OSS 在正常操作——甚至由于 Bug、误用或意外的 AI 行为——中都可能修改、移动、覆盖或删除文件。因此，在使用前必须遵循以下准则：
1. **使用隔离环境**：尽可能在专用的 Mac、独立的用户账户或虚拟机中运行。
2. **仅操作非关键文件夹**：切勿将 CoWork-OSS 指向重要的个人文件、系统文件夹或生产数据。只选择你可以承受丢失的文件夹。
3. **启用并验证备份**：在使用前确保 Time Machine 或其他备份方案正在运行，并且已验证可以恢复文件。
4. **仔细审查批准请求**：Agent 在执行破坏性操作前会请求许可。请务必在点击“批准”前仔细阅读它想做什么。
5. **预期未知情况**：AI 系统的行为不可预测。文件可能会在你未预期的情况下被修改或删除。
### 工作区边界与权限模型
CoWork-OSS 通过路径遍历保护机制，将所有文件操作限制在所选的工作区文件夹内。其权限模型设计如下：
* **Read (读取)**：允许读取文件。
* **Write (写入)**：允许创建或修改文件。
* **Delete (删除)**：允许删除文件（**需要显式批准**）。
* **Network (网络)**：网络访问（未来功能）。
* **Shell (命令行)**：执行 Shell 命令（**需要显式批准**）。
以下操作始终需要用户批准：
* 文件删除
* Shell 命令执行（启用时）
* 批量重命名（超过 10 个文件）
* 超出允许列表的网络访问
* 外部服务调用
### 数据处理原则
CoWork-OSS 遵循严格的本地数据处理原则：
* **本地存储**：任务元数据、时间轴事件、工件索引和工作区配置均存储在本地的 SQLite 数据库中。
* **发送给提供方**：仅将任务提示词和你选择包含的上下文（如选定文件的内容/片段）发送给模型提供商以生成输出。
* **不发送**：你的 API 密钥仅存储在本地，绝不会发送给任何第三方。
## 模型提供方与成本
CoWork-OSS 本身是免费和开源的。要运行任务，你需要配置自己的模型凭据或使用本地模型。
| 提供方 | 配置方式 | 计费模式 |
| :— | :— | :— |
| **Anthropic API** | 在 `.env` 中设置 `ANTHROPIC_API_KEY` | 按令牌量付费 |
| **AWS Bedrock** | 在设置中配置 AWS 凭证 | 通过 AWS 按令牌量付费 |
| **Ollama (本地)** | 安装 Ollama 并拉取模型 | **免费** (在本地运行) |
**注意**：你的使用费用直接由提供商结算。CoWork-OSS 不代理或转售模型访问权。如果你使用 Ollama，所有内容都在你的机器上运行，完全免费。
## 安装与配置指南
### 前置条件
在开始之前，请确保你的环境满足以下要求：
* Node.js 18+ 和 npm
* macOS（用于 Electron 原生功能）
* 以下三者之一：Anthropic API 密钥、AWS Bedrock 访问权限，或本地安装的 Ollama。
### 安装步骤
1. **克隆仓库**
打开终端，执行以下命令：
“`bash
git clone https://github.com/mesutfelat/cowork-oss.git
cd cowork-oss
“`
2. **安装依赖**
“`bash
npm install
“`
3. **配置 API 凭证**
复制环境变量示例文件并进行编辑：
“`bash
cp .env.example .env
# 编辑 .env 文件，添加你的 ANTHROPIC_API_KEY 或其他配置
“`
4. **运行开发模式**
“`bash
npm run dev
“`
### 生产环境构建
如果你需要打包可分发的应用程序：
“`bash
npm run build
npm run package
“`
打包后的应用程序将位于 `release/` 目录中。

CoWork-OSS Task Execution

图 3: 任务执行过程中的实时时间轴与工具调用

## 如何使用 CoWork-OSS
### 1. 选择工作区
首次启动时，你需要选择一个文件夹作为 CoWork-OSS 的工作区。这个文件夹将被挂载以供读写访问，并受到权限边界的保护。
### 2. 创建任务
点击“New Task”并描述你想要完成的任务。以下是一些示例任务：
* “按文件类型整理我的 Downloads 文件夹”
* “创建一个包含 Q1-Q4 数据的季度报告电子表格”
* “生成一份关于我们产品路线图的演示文稿”
* “分析这些 CSV 文件并创建一份摘要文档”
### 3. 监控执行
在任务执行过程中，你可以通过时间轴监控 Agent 的行为：
* 创建执行计划
* 使用可用工具执行步骤
* 请求批准破坏性操作
* 产出工件（文件）
### 4. 批准请求
当 Agent 需要执行破坏性操作（如删除文件）时，会弹出批准对话框。请仔细阅读详情，然后选择批准或拒绝。

Task Completion

图 4: 任务完成界面，显示验证结果和文件追踪

高级功能详解

Web Search 集成

CoWork-OSS 内置了多提供商的网页搜索系统，支持 Tavily、Brave Search、SerpAPI 和 Google Custom Search。这对于需要实时信息、研究或事实核查的任务非常有用。
配置方法：
在 .env 文件中添加相应提供商的 API Key。例如：

TAVILY_API_KEY=tvly-...
BRAVE_API_KEY=BSA...

在应用的设置面板中，你可以选择主要提供商和备用提供商。如果主要提供商失败（如网络错误或达到速率限制），系统会自动切换到备用提供商。
Agent 如何使用搜索：
当 web_search 工具可用时，Agent 可以搜索最新信息、查找新闻文章或研究事实，以更准确地完成任务。

Ollama 本地模型集成

对于重视隐私或希望免费使用的用户，Ollama 是最佳选择。
设置步骤：

  1. 从 ollama.ai 下载并安装 Ollama。
  2. 拉取推荐模型，例如 llama3.2 或 deepseek-r1:14b。
  3. 启动 Ollama 服务 (ollama serve)。
  4. 在 CoWork-OSS 的设置中选择 Ollama 作为提供商，刷新模型列表并选择你要使用的模型。
    推荐模型：
  • llama3.2：快速，适合大多数任务。
  • qwen2.5:14b：平衡的性能和推理能力。
  • deepseek-r1:14b：强大的编码和技术任务能力。
    请注意，本地模型的速度通常比云 API 慢，但提供了完全的隐私保护。较大的模型需要更多的内存（例如 14B 模型需要约 16GB RAM）。

架构概览

理解 CoWork-OSS 的架构有助于开发者或高级用户进行定制。它分为四个主要层次：

  1. React UI (Renderer)：负责任务列表、时间轴、批准对话框和工作区选择器。
  2. Agent Daemon (Main Process)：负责任务编排、Agent 执行器、工具注册和权限管理。
  3. Execution Layer：负责文件操作、技能（文档创建）、LLM 提供商和搜索提供商。
  4. SQLite Local Database：存储任务、事件、工件和工作区数据。

开发者指南

对于希望为 CoWork-OSS 做出贡献的开发者，项目提供了良好的开发体验。

热重载

开发模式支持热重载，包括 React UI（Vite HMR）和 Electron 主进程（更改时自动重启）。

添加新工具

  1. 在 tools/registry.ts 中定义工具架构。
  2. 在 tools/file-tools.ts 中实现工具逻辑或创建新文件。
  3. 在 getTools() 方法中注册工具。
  4. 在 executeTool() 中添加执行处理程序。

添加新技能

  1. 在 skills/ 目录中创建技能实现。
  2. 在 tools/skill-tools.ts 中添加技能工具定义。
  3. 在 SkillTools 类中实现技能方法。

常见问题解答

Q: CoWork-OSS 是免费的吗？
A: 是的，CoWork-OSS 是免费开源软件（MIT 许可证）。但是，如果你使用 Anthropic API 或 AWS Bedrock，你需要向这些提供商支付模型调用费用。如果你使用 Ollama，则完全免费。

Q: 我可以在 Windows 上运行 CoWork-OSS 吗？
A: 目前 CoWork-OSS 是 macOS 桌面应用程序，但跨平台支持已在路线图中。

Q: 我的 API 密钥安全吗？
A: 安全。你的 API 密钥仅存储在本地，绝不会发送给 CoWork-OSS 的开发者或任何第三方服务器。

Q: Agent 可以访问我电脑上的任何文件吗？
A: 不可以。CoWork-OSS 采用文件夹作用域的安全模型。它只能访问你明确选择的作为工作区的文件夹，并受到路径遍历保护。

Q: 如果 Agent 犯错了怎么办？
A: 虽然系统会请求批准，但 AI 行为有时不可预测。这就是为什么强烈建议使用隔离环境、仅操作非关键文件，并在使用前确保有有效备份。

Q: 如何使用 Telegram Bot 控制它？
A: 首先在 Telegram 中通过 BotFather 创建一个 Bot，获取 Token。然后在 CoWork-OSS 的设置中添加 Token，生成配对码，最后在 Telegram 中发送配对码即可连接。

Q: 支持哪些本地模型？
A: 任何通过 Ollama 安装的模型。推荐支持函数调用的模型，如 Llama 3.2 或 Qwen 2.5。

路线图与未来计划

CoWork-OSS 正在积极开发中，以下是目前已完成和计划中的功能：
已完成：

  • 文件夹作用域工作区 + 路径遍历保护
  • 破坏性操作的批准闸门
  • 任务时间轴 + 工件输出
  • 多提供商支持
  • 真正的 Office 格式支持
  • 本地持久化
  • Telegram 和 Discord Bot 集成
  • Web 搜索和浏览器自动化
    计划中：
  • 使用 macOS Virtualization.framework 实现 VM 沙箱
  • MCP 连接器主机和注册表
  • 子 Agent 协调以处理并行任务
  • 带代理的网络出口控制
  • 技能市场/加载器

结语

CoWork-OSS 代表了一种回归本源的 AI 工具设计思路：在本地掌控数据，以透明的方式执行任务，并以严格的权限保护系统安全。无论你是需要整理大量文档的内容创作者，还是需要自动化测试的开发人员，或者是希望保护数据隐私的安全研究人员，CoWork-OSS 都提供了一个强大且灵活的 Agent 工作台。
通过遵循本文的指南，你可以安全地部署和使用这一工具，将繁琐的文件处理任务交给 AI，从而释放你的创造力。

{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "CoWork-OSS",
  "operatingSystem": "macOS",
  "applicationCategory": "BusinessApplication",
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  },
  "description": "Local-first agent workbench for folder-scoped tasks with explicit approvals for destructive actions.",
  "featureList": "Task-based workflow, Workspace management, Permission system, Skill system (Excel, Word, PDF, PPT), Telegram/Discord integration, Web search, Browser automation",
  "screenshot": "https://t1.chatglm.cn/file/69770d11b3c08f1ae76905dd.md?expired_at=1769841813&sign=4bfacf850f9eef2d87a5cab58298fe21&ext=screenshots/cowork-oss4.jpeg"
}