随着 AI 技术的爆发，数据隐私和本地算力掌控权成了开发者关注的焦点。如果你正在寻找一个能够完全在本地运行、且具备 Claude Cowork 级体验的开源方案，Openwork（基于 different-ai/openwork）无疑是当下的最优选之一。

作为一个基于 OpenCode 构建的开源 AI 协作平台，Openwork 允许你在自己的硬件上运行代理（Agents）、技能（Skills）和 MCP 协议。但在实际部署过程中，不少开发者会遇到各种配置上的“暗坑”。本文将为你梳理出一份详尽的本地运行指南，助你绕过雷区，实现极致私有化。

---

一、 核心架构简述：Openwork 到底是什么？

在开始部署前，理解其架构能帮你更好地排查问题：

1. Openwork: 桌面应用/UI 层，提供类似 Claude 的交互界面。

2. OpenCode: 核心引擎，负责执行代码、管理文件和调用工具。

3. MCP (Model Context Protocol): 负责连接外部工具（如数据库、GitHub、Google Drive）的标准协议。

---

二、 本地部署实战：从 0 到 1

1. 快速上手（桌面端）

对于大多数用户，直接下载 DMG（macOS）或 Installer（Windows 正在适配中）是最快的方式。

• 避坑点：macOS 用户可能会遇到“应用已损坏”或“开发者无法验证”的提示。

• 对策：在终端运行 sudo xattr -rd com.apple.quarantine /Applications/Openwork.app 即可绕过系统签名限制。

2. 开发者模式（源码构建）

如果你需要深度定制或使用 CLI 工具，源码部署是必须的：

Bash

git clone https://github.com/different-ai/openwork.git
cd openwork
git submodule update --init --recursive  # 关键一步！
pnpm install
pnpm dev

---

三、 避坑指南：那些藏在文档里的“大坑”

1. 致命的子模块（Submodules）

很多人克隆仓库后直接执行 pnpm install，结果报错找不到 opencode 依赖。

• 真相：Openwork 强依赖于多个子项目。

• 解决方案：务必运行 git submodule update --init --recursive。如果网络环境不佳，建议配置 Git 代理或使用镜像源。

2. Linux / Wayland 的图形渲染报错

在一些 Linux 发行版（如 Arch 或 Ubuntu 配合 Wayland）上启动时，可能会遇到 Failed to create GBM buffer 或 WebKitGTK 崩溃。

• 解决方案：在启动前注入环境变量：

  Bash

  WEBKIT_DISABLE_DMABUF_RENDERER=1 openwork
  

3. 权限与工作区范围（Scope）

Openwork 极其重视安全，默认情况下 AI 无法访问任何文件夹。

• 坑位：给 AI 指令后，它反复提示“无法找到文件”或“权限拒绝”。

• 对策：在应用设置中手动添加 Allowed Folders。建议仅添加项目根目录，避免授予全局根目录权限，以实现真正的安全隔离。

4. 环境隔离问题

开发模式下，Openwork 可能会与你本地已有的 OpenCode 配置冲突。

• 建议：使用 pnpm dev 时，系统会自动开启 OPENWORK_DEV_MODE=1，这会使用隔离的状态存储。如果你通过 CLI 运行，请手动加上该变量以防止生产数据被污染。

---

四、 极致私有化：Openwork + Ollama

要实现真正的“不联网”，你不仅需要本地的 Openwork，还需要本地的 LLM。

1. 安装 Ollama: 下载并运行 ollama serve。

2. 配置 Openwork: 在 Provider 设置中选择 Custom/Ollama。

3. 模型推荐:

   • 编写代码：deepseek-coder-v2 或 codestral。

   • 通用任务：llama3.1 或 qwen2.5。

---

五、 结语

Openwork 不仅仅是一个工具，它代表了“AI 归于个人”的一种理念。通过本地化部署，你不仅能获得极低延迟的响应，更能彻底消除敏感代码外泄的后顾之忧。