English | 中文

HexClaw Desktop (河蟹桌面客户端)

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

Built with

Powered by

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

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

功能特性

生态链

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

架构

HexClaw.app
┌───────────────────────────────────────────────────────────────────┐
│  Tauri Shell (Rust)                                               │
│  窗口管理 · 系统托盘 · 原生菜单 · 全局快捷键 · 单实例 · 自动更新  │
│  API 代理 (CORS bypass) · Sidecar 进程管理                        │
├───────────────────────────────────────────────────────────────────┤
│  Vue 3 前端 (WebView)                                             │
│  ┌────────┬────────┬────────┬────────┬────────┬────────┬───────┐ │
│  │  Chat  │ Agents │知识中心 │ 自动化 │ IM通道 │  集成   │  日志 │ │
│  │ (默认) │        │文档|记忆│任务|Web │        │技能|MCP|P│       │ │
│  │        │        │        │ 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-*，许可证见 THIRD_PARTY.md。

Claude Code 开发实战 SOP

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

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

三条主线：

# 一次性把整套 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

技术栈

安装

一键安装 (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 用户注意：浏览器直接下载的 .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 与 src-tauri/Cargo.toml 的版本号和 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。

详细使用说明请参阅 使用指南（English Guide）。

开发

前置要求

快速开始

# 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.5.0)
make sidecar

# 本机全生态联调/装机测试：使用 ../hexclaw 和 ../go.work 中的本地最新代码
make sidecar-local

# 本机装机包：先校验本地 Go workspace，再重建 sidecar、生成 .app 和本地测试 DMG
make package-local

# 4. 启动开发模式
make dev

注意:

• make sidecar 默认会从 https://github.com/hexagon-codes/hexclaw.git 拉取 refs/tags/v0.5.0 到 /tmp/hexclaw-gith-src 并编译
• 如需切换后端版本，可显式指定：make sidecar HEXCLAW_REF=refs/tags/<tag>
• 本机装机测试使用 make sidecar-local，等价于 HEXCLAW_LOCAL_SRC=../hexclaw HEXCLAW_GOWORK=../go.work make sidecar，会让 ai-core、hexagon、toolkit 走本地 Go workspace
• 本机完整打包使用 make package-local，会先运行 verify-local-deps，如果任一核心模块未解析到 /Users/hexagon/work 下会直接失败；macOS 本地 DMG 使用稳定的 hdiutil create -srcfolder 路径，避免 Finder/AppleScript 美化流程影响装机测试
• 技能市场默认读取 https://github.com/hexagon-codes/hexclaw-hub 的 v0.0.2 标签；运行时可在 ~/.hexclaw/hexclaw.yaml 的 skills.hub 覆盖

Make 命令

项目结构

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 (飞书/钉钉/企微等)
│   │   ├── k12.ts                # K12 场景包 API 契约 (/api/k12/*)
│   │   ├── 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 等)
│   ├── contracts/                # 场景扩展契约 (ViewDescriptor/RecordSchema/VerifyResult)
│   ├── shell/                    # 领域无关 shell 扩展槽 (scenario registry/records/message badges)
│   ├── features/                 # 场景包实现
│   │   └── k12/                  # 作业辅导助手 (建档/辅导/错题本/备课卡/学情)
│   ├── 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   # 集成 (Skills + MCP + Prompts Tab)
│   │   ├── SkillsView.vue        # Skill 管理 + ClawHub 市场
│   │   ├── McpView.vue           # MCP 管理 (服务器/工具/测试)
│   │   ├── PromptsView.vue       # Prompt 库 (模板/搜索/复用)
│   │   ├── 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               # 入口
│   │   ├── lib.rs                # 应用初始化 & 插件注册
│   │   ├── commands.rs           # Tauri IPC 命令 (健康检查/API 代理/流式聊天/文件保存)
│   │   ├── sidecar.rs            # Go Sidecar 进程管理
│   │   ├── ollama.rs             # 内嵌 Ollama 进程管理
│   │   ├── tray.rs               # 系统托盘
│   │   ├── menu.rs               # macOS 原生菜单
│   │   └── window.rs             # 窗口管理 & 全局快捷键 (⌘⇧H Quick Chat)
│   ├── binaries/                 # 内嵌二进制 (hexclaw sidecar + pandoc + typst + ollama-bundle)
│   ├── render-assets/            # 文档渲染资产 (reference.docx，随包打入)
│   ├── icons/                    # 应用图标
│   ├── capabilities/             # Tauri v2 权限配置
│   ├── tauri.conf.json           # Tauri 配置
│   ├── build.rs                  # Rust 构建脚本
│   └── Cargo.toml                # Rust 依赖
├── docs/                         # 文档
│   ├── guide.md                  # 使用指南 (中文)
│   ├── guide.en.md               # 使用指南 (英文)
│   ├── updates.md                # 自动更新发布说明 (中文)
│   ├── updates.en.md             # 自动更新发布说明 (英文)
│   ├── overview.md               # 产品总览 (中文)
│   ├── overview.en.md            # 产品总览 (英文)
│   └── claude-code-practices/    # Claude Code 实战 SOP (4 手册 + 7 命令 + Hooks + DevTestOps Skill + 模板)
├── homebrew/                     # Homebrew Cask 定义 + 更新脚本
├── install.sh                    # macOS 一键安装脚本
├── scripts/                      # CI/构建脚本
├── .github/                      # GitHub CI/CD
├── Makefile                      # 开发命令
├── vite.config.ts                # Vite 配置
├── vitest.config.ts              # Vitest 测试配置
├── eslint.config.ts              # ESLint 配置
├── tsconfig.json                 # TypeScript 配置
├── package.json                  # Node 依赖
├── LICENSE                       # Apache 2.0 许可证
└── README.md

构建

生产构建

# 完整构建 (前端 + Tauri 打包)
make build

# 输出位置:
#   macOS: src-tauri/target/release/bundle/macos/HexClaw.app
#   DMG:   src-tauri/target/release/bundle/dmg/HexClaw_*.dmg

指定目标平台构建

# macOS Intel
npx @tauri-apps/cli build --target x86_64-apple-darwin

# macOS Apple Silicon
npx @tauri-apps/cli build --target aarch64-apple-darwin

Sidecar 交叉编译

# 编译所有平台
make sidecar-all

# 或单独编译指定平台
make sidecar-darwin-arm64    # macOS Apple Silicon
make sidecar-darwin-amd64    # macOS Intel
make sidecar-linux-amd64     # Linux x86_64
make sidecar-windows-amd64   # Windows x86_64

# 本机装机测试/全生态联调，优先使用本地最新 hexclaw + ai-core + hexagon + toolkit
make sidecar-all-local

Sidecar 二进制输出到 src-tauri/binaries/ 目录，Tauri 打包时会自动内嵌。构建时会注入真实的 tag / commit / built 时间，方便在已安装应用里核对后端版本。

测试

# 运行单元测试
pnpm test:unit

# 或使用 Make
make test

测试文件规范：

• 测试文件与源码同目录，命名为 *.test.ts 或 *.spec.ts
• Store 测试放在 src/stores/__tests__/ 目录
• 使用 Vitest + @vue/test-utils

常见问题

macOS 提示"无法打开"或"已损坏"

推荐使用一键安装脚本或 Homebrew 安装（自动处理 Gatekeeper）：

# 方式 1：一键安装
curl -fsSL https://raw.githubusercontent.com/hexagon-codes/hexclaw-desktop/main/install.sh | bash

# 方式 2：Homebrew
brew tap hexagon-codes/tap && brew install --cask hexclaw

如果已经手动下载了 DMG，在终端执行：

xattr -cr /Applications/HexClaw.app

侧边栏显示 "Engine stopped" 但后端已启动

1. 确认 hexclaw 进程在运行: ps aux | grep hexclaw
2. 确认端口监听正常: curl http://localhost:16060/health
3. 如果 curl 成功但前端仍显示 stopped，检查是否是旧版本应用（重新 make build 并安装最新版本）

make sidecar 编译失败

1. 确认 Go >= 1.25 已安装: go version
2. 确认能访问 GitHub 并成功拉取远程源码: git ls-remote --tags https://github.com/hexagon-codes/hexclaw.git v0.5.0
3. 确认 Rust 工具链已安装 (用于检测平台 triple): rustc -vV

make dev 启动后白屏

Sidecar 可能未编译或端口冲突。检查：

1. 确认已执行 make sidecar
2. 确认 16060 端口未被占用: lsof -i :16060

hexclaw 后端启动失败

1. 查看错误日志: ~/.hexclaw/hexclaw.log
2. 直接运行 sidecar 查看输出: ./src-tauri/binaries/hexclaw-$(rustc -vV | grep host | awk '{print $2}') serve --desktop
3. 即使未配置 LLM API Key，hexclaw 也应该能正常启动（LLM 功能降级，基础 API 仍可用）

贡献指南

工作流程

1. Fork 本仓库
2. 创建功能分支: git checkout -b feat/your-feature
3. 提交更改: git commit -m "feat: 添加新功能"
4. 推送分支: git push origin feat/your-feature
5. 创建 Pull Request

代码规范

• 格式化: make format (Prettier)
• 检查: make lint (ESLint + oxlint，只检查不修改文件)
• 类型检查: make type-check (vue-tsc)

Commit Message 格式

遵循 Conventional Commits 规范：

feat: 添加新功能
fix: 修复问题
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链

在线资源

• 🌐 官网: hexclaw.net
• 📖 中文文档: hexclaw.net/zh/docs
• 📖 English Docs: hexclaw.net/en/docs
• 🐙 GitHub: hexagon-codes/hexclaw-desktop
• 📝 Claude Code SOP: 《河蟹 AI 背后的 Claude Code SOP》 · 开源 SOP 包

联系我们

• 官网: hexclaw.net
• GitHub Issues: hexclaw-desktop/issues
• 河蟹 AI: [email protected]
• 河蟹支持: [email protected]

微信公众号

关注 HexClaw 微信公众号，获取最新动态、使用教程和版本更新：

License

Apache License 2.0