Hexclaw Desktop

[English](README.en.md) | 中文

HexClaw Desktop (河蟹桌面客户端)

企业级安全的个人 AI Agent 一体化桌面客户端

[](https://github.com/hexagon-codes/hexclaw-desktop/actions) [](https://github.com/hexagon-codes/hexclaw-desktop/releases) [](https://github.com/hexagon-codes/hexclaw-desktop/blob/main/LICENSE) [](https://github.com/hexagon-codes/hexclaw-desktop/releases) [](https://github.com/hexagon-codes/hexclaw-desktop)

Built with

[](https://v2.tauri.app) [](https://vuejs.org) [](https://www.typescriptlang.org) [](https://www.rust-lang.org) [](https://go.dev)

Powered by

🌐 官网 hexclaw.net · 📖 在线文档 · ⬇️ 下载

macOS / Windows / Linux 原生运行 · Sidecar 架构本地部署 · 零云端依赖 · 数据完全私有

---

功能特性

| 功能 | 说明 | |------|------| | AI 对话 | 多模型支持: OpenAI / DeepSeek / Anthropic / Gemini / Qwen / Ollama，流式输出，Markdown 渲染，代码高亮，深度思考 | | 图片/视频生成 | 智谱 CogView-4 图片生成 + CogVideoX-2 视频生成，统一文本对话框入口（无独立 mode 按钮），生成结果落盘到 {DataDir}/generated/ 后以 /api/v1/files/generated/... URL 引用（永不过期、不撑爆 SQLite），气泡内联预览 + 一直可见的下载按钮 | | 本地模型 (Ollama) | 一键检测/关联本地 Ollama，自动发现已下载模型，状态机管理（检测→运行→关联），LM Studio/llama.cpp 走 OpenAI 兼容接入 | | Agent 编排 | 自定义 Agent 角色/目标/背景，多 Agent 协作 (Handoff + Orchestrate + Spawn)，Agent 会议模式，角色模板库 | | 自主 Agent | Budget 三维预算兜底 (token/时间/金额)，代码执行沙箱 (macOS Seatbelt/Linux Namespace/Windows 5 层隔离)，Checkpoint 长任务恢复 | | 工具审批 | 危险工具 WebSocket 实时审批 (ToolApprovalCard)，safe/sensitive/dangerous 三级风险分类，"始终允许"记忆 | | Skill 系统 | 技能市场 + 自定义技能 + LLM 创建新 Skill (SkillWriter + 安全扫描)，Skill Chain 链式调用，依赖管理，Tool 注册与 Per-tool 权限 | | MCP 协议 | Model Context Protocol 工具集成 (stdio/SSE/Streamable HTTP)，OAuth 2.0+PKCE 认证，命令白名单安全校验，一键安装+持久化，工具注解解析 | | 工作流画布 | 可视化拖拽编排 Agent 工作流，DAG 图执行引擎 | | 知识库 (RAG) | 文档上传/解析/向量检索，支持 PDF / Markdown / TXT 等格式；Auto-RAG 自动检索知识库注入上下文 (score >= 0.35) | | 记忆系统 | 长期记忆 + 短期记忆 + 语义搜索，跨会话记忆持久化，VectorMemory 向量语义回忆 | | 工具智能 | 工具结果缓存 (LRU+TTL)，Per-tool 超时+指数退避重试，工具执行指标收集 (JSONL)，MCP 结构化日志+轮转 | | 安全网关 | Prompt 注入检测 / 工具输出清洗 (HTML/Unicode/LLM 分隔符) / PII 过滤 / 内容过滤 / RBAC 权限控制 / SSRF 防护 | | 文件操作 | Agent 可读/写/编辑 workspace 文件 (ReadSkill/WriteSkill/EditSkill)，路径校验+symlink 防护 | | 定时任务 | Cron 调度，周期性执行 Agent 任务 | | IM 通道 | 飞书 / 钉钉 / 企微 / 微信 / Slack / Discord / Telegram，通过 IM 远程与 AI 对话 | | 深度研究 | 4 阶段自主调研（搜索→分析→综合→报告），基于 Hexagon Plan-and-Execute 引擎 | | 文档解析 | 聊天中直接上传 PDF / Word / Excel / CSV，自动提取文本作为上下文 | | Webhook 通知 | 企微 / 飞书 / 钉钉机器人 Webhook 推送，任务完成自动通知 | | ClawHub 技能市场 | 浏览、语义搜索 (TF-IDF)、安装社区 Skill/MCP，Hub 依赖自动解析 | | 首次引导 | 3 步 Welcome 向导（选 Provider → 选模型 → 测试连接），零配置门槛 | | 实时日志 | WebSocket 流式日志，Agent 执行链路全程追踪 | | 多语言 | 中文 / English / 维吾尔语 (ug-CN，含 RTL 从右到左排版)，vue-i18n 国际化 | | 系统托盘 | 最小化到托盘，托盘菜单快捷操作 | | 全局快捷键 | ⌘+Shift+H 随时唤起 Quick Chat 窗口 | | 自动更新 | Tauri Updater，应用内一键升级 |

生态链

toolkit → ai-core → hexagon → hexclaw → hexclaw-desktop
                                       → hexclaw-ui
                                       → hexagon-ui

| 项目 | 定位 | 语言 | |------|------|------| | toolkit | 通用工具箱 — 基础设施库 (日志/配置/HTTP/并发/错误链) | Go | | ai-core | AI 能力底座 — LLM Provider/Embedding/向量/记忆 | Go | | hexagon | 全能 AI Agent 框架 — ReAct/Plan-and-Execute/Tool 调度 | Go | | hexclaw | 河蟹后端 — Sidecar 服务 (RESTful API/RAG/Cron/安全网关) | Go | | hexclaw-hub | 技能市场数据 — 在线技能目录 (index.json + Markdown 技能) | 数据仓库 | | hexclaw-desktop | 河蟹桌面客户端 (本仓库) | Rust + Vue 3 | | hexclaw-ui | 河蟹 Web 端 — Web 客户端 (同时作为桌面端 UI 渲染层复用) | Vue 3 | | hexagon-ui | Agent 观测台 — 可观测性面板 (链路追踪/推理回放/性能分析) | Vue 3 |

架构

HexClaw.app
┌───────────────────────────────────────────────────────────────────┐
│  Tauri Shell (Rust)                                               │
│  窗口管理 · 系统托盘 · 原生菜单 · 全局快捷键 · 单实例 · 自动更新  │
│  API 代理 (CORS bypass) · Sidecar 进程管理                        │
├───────────────────────────────────────────────────────────────────┤
│  Vue 3 前端 (WebView)                                             │
│  ┌────────┬────────┬────────┬────────┬────────┬────────┬───────┐ │
│  │  Chat  │ Agents │知识中心 │ 自动化 │ IM通道 │  集成   │  日志 │ │
│  │ (默认) │        │文档|记忆│任务|Web │        │技能|MCP │       │ │
│  │        │        │        │ hook    │        │         │ 设置  │ │
│  └───┬────┴───┬────┴───┬────┴───┬────┴───┬────┴───┬────┴───────┘ │
│      │  Pinia Store    │  Vue Router      │  Tauri invoke (IPC)   │
├──────┴─────────────────┴──────────────────┴───────────────────────┤
│  Tauri Commands (Rust → Go)                                       │
│  check_engine_health · proxy_api_request · get_sidecar_status     │
│  backend_chat · stream_chat · restart_sidecar · get_platform_info │
├───────────────────────────────────────────────────────────────────┤
│  HTTP / WebSocket  ←→  localhost:16060                            │
├───────────────────────────────────────────────────────────────────┤
│  hexclaw serve (Go Sidecar)                                       │
│  Agent 引擎 · LLM 路由 · RAG · MCP · CORS · 安全网关 · Cron      │
│  ┌────────────────────────────────────────────────────────────┐   │
│  │  Hexagon Framework  ←  ai-core (LLM/Tool/Memory)          │   │
│  │                     ←  toolkit (Log/Config/HTTP/Concurrency)│   │
│  └────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────────┘

设计模式与 Docker Desktop 管理 Docker Engine 一致 — Tauri 壳管理 Go Sidecar 进程。 前后端通过 Tauri IPC 代理通信（解决 WebView CORS 限制），完全解耦。

> Go Sidecar 默认监听 localhost:16060，可通过 hexclaw 配置文件修改端口。

> 安装包内还内嵌了若干随包二进制：Ollama（本地模型推理）、Pandoc + Typst（文档渲染：Markdown → docx/pdf 等）。它们作为独立子进程被调用，对应 src-tauri/binaries/ 下的 ollama-bundle/、pandoc-*、typst-*，许可证见 [THIRDPARTY.md](THIRDPARTY.md)。

Claude Code 开发实战 SOP

这个仓库同时是"用 Claude Code 做出一个能跑的产品"的工作流实录。业余时间 × 一个人 × 6 核心仓库 × 68 万行代码背后的完整 SOP，已全部开源。

• 📝 公众号文章：《河蟹 AI 背后的 Claude Code SOP：设计驱动 × 测试闭环 × 多 Agent 协作》 — 完整叙事 + 三条主线的具体做法
• 📂 开源 SOP 包：[docs/claude-code-practices/](docs/claude-code-practices/) — 4 份实战手册 + 7 个可直接复制的 Claude Code 命令 + 3 个开箱即用 Hooks + DevTestOps Skill + CLAUDE.md 模板

三条主线：

| 主线 | 核心做法 | |------|---------| | ✏️ 设计驱动 | Plan 模式 → 多方案对比 → ADR 决策，不做"一句话 + 秒出代码" | | ✅ 测试闭环 | 不接受 "should pass" / "probably OK"——测试跑过、grep 扫过残留才算完成 | | 🤖 多 Agent 协作 | Claude 写代码 / Codex 审代码 / 人类决策，交叉审查消除单模型盲区 |

# 一次性把整套 SOP 装进 Claude Code
mkdir -p ~/.claude/commands ~/.claude/data ~/.claude/skills ~/.claude/hooks
cp docs/claude-code-practices/command/*.md ~/.claude/commands/
cp docs/claude-code-practices/data/*.md ~/.claude/data/
cp -r docs/claude-code-practices/skill/devtestops ~/.claude/skills/
cp docs/claude-code-practices/hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh

技术栈

| 层 | 技术 | 版本 | |----|------|------| | 桌面框架 | Tauri | v2 | | 前端框架 | Vue 3 (Composition API) | 3.5+ | | 语言 | TypeScript | 5.9+ | | 状态管理 | Pinia | 3.x | | UI 组件库 | Naive UI + 自定义设计系统 | - | | 样式 | Tailwind CSS | 4.x | | 路由 | Vue Router | 5.x | | 国际化 | vue-i18n (中文 / English / 维吾尔语 RTL) | 11.x | | 图标 | Lucide Vue | - | | Markdown | markdown-it + Shiki (代码高亮) | - | | 文档解析 | pdfjs-dist + mammoth + xlsx | - | | 数据存储 | Tauri Store (plugin-store) + localStorage (Pinia 持久化插件)；会话/消息由后端 sidecar 持久化 | - | | HTTP 客户端 | ofetch (前端) / reqwest (Rust 代理) | - | | 构建工具 | Vite | 7.x | | 测试 | Vitest + @vue/test-utils | - | | Lint | ESLint + oxlint + Prettier | - | | 后端 Sidecar | hexclaw serve (Go) | Go 1.25+ | | Agent 框架 | Hexagon | - | | Rust 层 | Tauri Shell + 插件生态 | Rust 2021 edition |

安装

一键安装 (macOS)

curl -fsSL https://raw.githubusercontent.com/hexagon-codes/hexclaw-desktop/main/install.sh | bash

自动检测 CPU 架构（Apple Silicon / Intel），下载最新版并安装到 /Applications，无需手动处理 Gatekeeper 拦截。

Homebrew (macOS)

brew tap hexagon-codes/tap
brew install --cask hexclaw

后续升级：brew upgrade --cask hexclaw

GitHub Releases

前往 Releases 下载对应平台安装包：

| 平台 | 格式 | |------|------| | macOS (Apple Silicon) | .dmg | | macOS (Intel) | .dmg | | Windows | .msi / .exe (NSIS) | | Linux | .deb / .AppImage |

> macOS 用户注意：浏览器直接下载的 .dmg 可能被 Gatekeeper 拦截。推荐使用上方的一键安装脚本或 Homebrew 安装，它们会自动处理 Gatekeeper 问题。 > 如果手动下载安装，在终端执行 xattr -cr /Applications/HexClaw.app 即可解除拦截。

CI / 打包 / Release 流程

• push / PR -> CI: 自动运行 lint、type-check、test、web build
• Actions -> Package -> Run workflow: 手动构建各平台测试安装包，产物保存在 workflow artifacts
• git tag vX.Y.Z && git push origin vX.Y.Z -> Release: 构建并发布正式 GitHub Release 安装包
• 正式版发布后自动更新 Homebrew Tap（计算 DMG SHA256 → 推送 Cask 更新）

正式发布前需要满足：

• package.json 与 src-tauri/tauri.conf.json 的版本号和 tag 一致
• src-tauri/tauri.conf.json 中已写入 Tauri updater 公钥 plugins.updater.pubkey
• GitHub Actions secrets 已配置 TAURI_SIGNING_PRIVATE_KEY（可选，用于 Tauri 自动更新签名）

> macOS 产物为 unsigned DMG，用户通过 curl | bash 一键安装脚本或 Homebrew 安装，自动处理 Gatekeeper。

详细使用说明请参阅 [使用指南](docs/guide.md)（[English Guide](docs/guide.en.md)）。

开发

前置要求

| 工具 | 版本要求 | 说明 | |------|---------|------| | Node.js | >= 20.19 或 >= 22.12 | JavaScript 运行时 | | pnpm | 10.x (仓库锁定 pnpm@10.30.3) | 包管理器 | | Rust | stable (2021 edition) | Tauri 编译 | | Go | >= 1.25 | Sidecar 编译 |

快速开始

# 1. 克隆仓库
git clone https://github.com/hexagon-codes/hexclaw-desktop.git
cd hexclaw-desktop

# 2. 安装依赖
make install
# 等价于: pnpm install && cd src-tauri && cargo fetch

# 3. 编译 Go sidecar (首次需要，默认拉取远程 GitHub hexclaw v0.4.3)
make sidecar

# 4. 启动开发模式
make dev

> 注意: > - make sidecar 默认会从 https://github.com/hexagon-codes/hexclaw.git 拉取 refs/tags/v0.4.3 到 /tmp/hexclaw-gith-src 并编译 > - 如需切换后端版本，可显式指定：make sidecar HEXCLAW_REF=refs/tags/ > - 技能市场默认读取 https://github.com/hexagon-codes/hexclaw-hub 的 v0.0.2 标签；运行时可在 ~/.hexclaw/hexclaw.yaml 的 skills.hub 覆盖

Make 命令

| 命令 | 说明 | |------|------| | make dev | 开发模式 (Vite HMR + Tauri 窗口) | | make build | 构建生产版本 | | make build-web | 仅构建前端 | | make sidecar | 编译 Go sidecar (当前平台) | | make sidecar-all | 交叉编译所有平台 sidecar | | make lint | 代码检查 (oxlint + ESLint) | | make lint-fix | 代码检查并自动修复 | | make format | 代码格式化 (Prettier) | | make type-check | TypeScript 类型检查 | | make test | 运行单元测试 | | make clean | 清理构建产物 | | make install | 安装所有依赖 |

项目结构

hexclaw-desktop/
├── src/                          # Vue 3 前端源码
│   ├── api/                      # API 客户端 (Tauri IPC + HTTP fallback)
│   │   ├── client.ts             # HTTP/WS/IPC 基础客户端
│   │   ├── chat.ts               # 聊天 API (WebSocket + HTTP 回退)
│   │   ├── agents.ts             # Agent 管理 API
│   │   ├── skills.ts             # Skill + ClawHub 市场 API
│   │   ├── canvas.ts             # 工作流画布 API
│   │   ├── mcp.ts                # MCP 协议 API
│   │   ├── knowledge.ts          # 知识库 API
│   │   ├── memory.ts             # 记忆系统 API
│   │   ├── tasks.ts              # 定时任务 API
│   │   ├── config.ts             # LLM 配置 API (Tauri 代理)
│   │   ├── desktop.ts            # 桌面功能 API (通知/剪贴板)
│   │   ├── im-channels.ts        # IM 通道 API (飞书/钉钉/企微等)
│   │   ├── team.ts               # 团队协作 API
│   │   ├── voice.ts              # 语音 API (TTS/STT)
│   │   ├── webhook.ts            # Webhook 通知 API
│   │   ├── websocket.ts          # 聊天 WebSocket 客户端
│   │   ├── logs.ts               # 日志 API + WebSocket 流
│   │   ├── settings.ts           # 设置 API
│   │   └── system.ts             # 系统信息 API
│   ├── components/               # 组件
│   │   ├── layout/               # 布局 (AppLayout/Sidebar/TitleBar/ContextBar/DetailPanel)
│   │   ├── chat/                 # 聊天 (ChatInput/SessionList/MarkdownRenderer/ToolApprovalCard/BudgetPanel/AgentBadge/Interactive* 等)
│   │   ├── settings/             # 设置 (OllamaCard/ModelManagerModal/SettingsNotification/SettingsSecurity)
│   │   ├── artifacts/            # 产物 (ArtifactsPanel/ArtifactPreview/ArtifactCodeView/ArtifactDiffView)
│   │   ├── inspector/            # 右侧详情 (InspectorContext/ContextCard/KeyValueRow/TimelineItem)
│   │   ├── canvas/               # 画布 (TemplateGallery)
│   │   ├── channels/             # IM 通道 (AgentRoutingRules)
│   │   ├── automation/           # 自动化 (WebhookPanel)
│   │   ├── cron/                 # 定时任务 (CronJobConfirmCard)
│   │   ├── logs/                 # 日志 (LogEntry/LogStats)
│   │   └── common/               # 通用 (CommandPalette/ConfirmDialog/ToastProvider/ErrorBoundary 等)
│   ├── views/                    # 页面视图
│   │   ├── ChatView.vue          # AI 对话 (默认首页 · 会话/附件/Artifacts/模型切换)
│   │   ├── AgentsView.vue        # Agent 管理 (模板/运行中/规则/会议)
│   │   ├── KnowledgeCenterView.vue # 知识中心 (文档 + 记忆 Tab)
│   │   ├── KnowledgeView.vue     # 知识库 (文档 CRUD/上传/搜索)
│   │   ├── MemoryView.vue        # 记忆管理 (编辑/搜索/清空)
│   │   ├── AutomationView.vue    # 自动化 (任务 + Webhook Tab)
│   │   ├── TasksView.vue         # 定时任务 (Cron 管理)
│   │   ├── CanvasView.vue        # 工作流画布 (DAG 编排)
│   │   ├── IntegrationView.vue   # 集成 (技能 + MCP Tab)
│   │   ├── SkillsView.vue        # Skill 管理 + ClawHub 市场
│   │   ├── McpView.vue           # MCP 管理 (服务器/工具/测试)
│   │   ├── IMChannelsView.vue    # IM 通道管理 (飞书/钉钉/企微等)
│   │   ├── LogsView.vue          # 日志查看 (实时流/过滤/统计)
│   │   ├── SettingsView.vue      # 设置 (LLM/安全/通知/Webhook/主题/语言)
│   │   ├── AboutView.vue         # 关于 (独立窗口)
│   │   ├── QuickChatView.vue     # 快捷聊天 (独立窗口)
│   │   └── WelcomeView.vue       # 首次引导 (Provider → 模型 → 测试)
│   ├── stores/                   # Pinia 状态管理 (thin store，业务逻辑委托 services/controllers)
│   │   ├── app.ts                # 全局状态 (连接/侧边栏/详情面板)
│   │   ├── chat.ts               # 聊天 (会话/消息/流式/Artifacts；消息由后端 sidecar 持久化)
│   │   ├── agents.ts             # Agent 角色
│   │   ├── canvas.ts             # 画布 (节点/边/工作流/运行)
│   │   ├── logs.ts               # 日志 (WebSocket 流/过滤/统计)
│   │   ├── settings.ts           # 设置 (LLM + 安全 + 通知, Tauri Store 持久化)
│   │   └── plugins/persist.ts    # Pinia 持久化插件 (localStorage + 版本迁移)
│   ├── composables/              # 组合式函数
│   │   ├── useHexclaw.ts         # hexclaw 连接状态 + 健康检查轮询
│   │   ├── useWebSocket.ts       # WebSocket 封装 (自动重连)
│   │   ├── useSSE.ts             # SSE 流式请求
│   │   ├── useShortcuts.ts       # 应用内快捷键 (⌘1~N 切页面)
│   │   ├── useTheme.ts           # 主题 (深色/浅色/跟随系统)
│   │   ├── useAutoUpdate.ts      # 自动更新 (Tauri updater)
│   │   ├── useVoice.ts           # 语音 (TTS/STT/语音对话)
│   │   ├── useValidation.ts      # 表单校验
│   │   ├── useKeyboardNav.ts     # 键盘导航 + 焦点陷阱
│   │   ├── usePlatform.ts        # 平台检测 (macOS/Windows/Linux)
│   │   ├── useChatSend.ts        # 发送消息 + Auto-RAG 知识库检索
│   │   ├── useChatActions.ts     # 聊天操作 (重发/编辑/删除等)
│   │   ├── useCron*.ts           # Cron 解析/编译/常驻挂件
│   │   └── useConversationAutomation.ts # 会话自动化 (自动标题等)
│   ├── services/                 # 业务逻辑服务层
│   │   ├── chatService.ts        # 聊天服务 (WebSocket/HTTP 发送)
│   │   └── messageService.ts     # 消息服务 (消息构建/后端持久化)
│   ├── i18n/                     # 国际化 (中文 zh-CN / 英文 en / 维吾尔语 ug-CN RTL)
│   ├── router/                   # 路由 (基于 navigation.ts 动态生成，默认重定向 /chat)
│   ├── types/                    # TypeScript 类型定义
│   ├── utils/                    # 工具函数
│   │   └── file-parser.ts        # 文档解析器 (PDF/Word/Excel/CSV)
│   ├── config/                   # 前端配置
│   │   ├── env.ts                # 环境配置
│   │   ├── navigation.ts         # 导航注册表 (四组: home/build/connections/system)
│   │   ├── llm-providers.ts      # LLM Provider 配置
│   │   └── providers.ts          # Provider 元数据
│   └── assets/                   # 静态资源 (Logo/图标/IM Logo)
├── src-tauri/                    # Tauri (Rust) 层
│   ├── src/
│   │   ├── main.rs

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hexagon-codes](https://github.com/hexagon-codes)
- **Source:** [hexagon-codes/hexclaw-desktop](https://github.com/hexagon-codes/hexclaw-desktop)
- **License:** Apache-2.0
- **Homepage:** https://hexclaw.net

Install and usage instructions live in the source repository linked above.