河蟹 AI 文档

快速上手

安装应用、连接服务与模型，发送第一条消息。

系统要求

平台	最低要求
macOS	Apple Silicon / Intel；当前源码随包的 Ollama、Pandoc 等组件需要 macOS 14 及以上
Windows	Windows 10 (1809+)，x64
Linux	x64；发布构建使用 Ubuntu 22.04，运行环境需要 WebKitGTK 4.1 等 Tauri 依赖

应用外壳配置的 macOS 11 下限不代表随包组件的兼容范围。安装包以所选 Release 的实际资产与说明为准；下文源码步骤对应当前主线。

安装

方式一：一键安装（macOS，推荐）

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

方式二：Homebrew 安装（macOS）

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

方式三：下载安装包

前往 GitHub Releases 下载对应平台安装包（当前版本 v0.5.0）：

macOS：.dmg — 拖入 Applications 即可
Windows：.exe（NSIS 安装包）— 双击安装
Linux：.deb、.AppImage 或 .rpm

方式四：源码编译

以下快速路径适用于 macOS。先安装 Node.js ^20.19.0 || >=22.12.0、pnpm 10.30.3、Rust 1.94.0、Go 1.25.13+、Git、Make、Python 3 和 curl；其他平台按 Tauri 2 前置要求准备系统依赖。

git clone https://github.com/hexagon-codes/hexclaw-desktop.git
cd hexclaw-desktop
pnpm install --frozen-lockfile
make sidecar
make render-bundle
make ollama
make dev

提示：make sidecar 使用 Makefile 的 HEXCLAW_REF，不会自动选择最新后端；使用当前后端主分支时运行 make sidecar HEXCLAW_REF=origin/main。指定其他版本时，以其 go.mod 为准。Windows / Linux 随包组件准备见 Release 工作流。

首次启动向导

首次配置向导包含 2 步，先连接服务，再检查是否已经有可用模型：

选择服务 — 使用应用管理的本机服务，或填写自行部署的云端 HexClaw 服务地址和访问令牌
检查并开始 — 检查服务连接和默认模型；模型已就绪时继续原任务，尚未就绪时进入模型设置

模型设置完成后返回原任务，已填写的内容会保留。后续可在 设置 → 模型服务 中修改当前服务的配置；需要切换本机或云端服务时，点击侧栏底部的服务状态入口。

服务模式：本机服务由应用管理启动与停止；云端服务由服务器管理，服务器、模型与已绑定 IM 持续可用时，电脑关机不会停止云端任务。

首次配置

1. 配置 AI 服务商

先连接所选服务，再进入 设置 → 模型服务，为该服务配置至少一个可用模型；云端服务已有默认模型时可直接开始任务：

OpenAI — 填入 API Key（sk-...），可接入 GPT-4o、o 系列等模型
DeepSeek — 填入 API Key，可接入 DeepSeek 系列模型
Anthropic — 可接入 Claude 系列模型
Google Gemini — 可接入 Gemini 系列模型，部分模型支持视频/音频能力
阿里 Qwen — 可接入通义千问系列，含视觉模型
字节 Ark（豆包） — 可接入豆包及火山方舟兼容模型，含视觉模型
Ollama（本地） — 无需 API Key，支持 Llama / Qwen / Mistral / DeepSeek 等本地模型
自定义 — 任何兼容 OpenAI API 格式的服务

配置文件示例

本机服务也支持通过 YAML 配置文件初始化；云端服务应在服务器配置，不使用桌面本机的配置文件：

# ~/.hexclaw/hexclaw.yaml
server:
  host: 127.0.0.1
  port: 16060

llm:
  default: openai
  providers:
    openai:
      api_key: sk-your-key-here
      base_url: https://api.openai.com/v1
      model: gpt-4o

platforms:
  feishu:
    enabled: false
    app_id: ""
    app_secret: ""

2. 选择默认模型

在服务商配置中，勾选一个模型作为默认聊天模型。

3. 发送第一条消息

进入 「会话」 页面，在同一个输入框中输入“请用三句话介绍你能帮助我完成的任务”，按回车发送。模型选择和思考设置在输入框内底部工具栏中，按当前模型支持的能力显示。应看到流式内容逐步出现并最终成为完整回答；仅连接测试成功不能证明任务已经完成。

需要比较运行方式与数据保存位置，可继续阅读本机与云端怎么选。

首次排障入口

如果安装完成后仍无法正常聊天，建议先检查下面三项：

打开 设置 → 模型服务，对当前 Provider 执行一次测试连接
本机模式打开日志页面，确认 Engine 已启动且默认端口 16060 未被占用；云端模式检查服务地址、访问令牌与服务器状态
如果仍有空白页、401/403、MCP 连接失败等问题，直接查看常见问题

应用架构

河蟹 AI 桌面端采用 Tauri v2 + Vue 3 + Go Sidecar 架构：

前端：Vue 3 + TypeScript + Pinia + TailwindCSS
桌面壳：Tauri v2（Rust），负责窗口管理、系统托盘、全局快捷键
AI 引擎：本机 Go Sidecar（hexclaw）或自行部署的云端 HexClaw，负责模型调用、工作流执行、知识库、记忆等核心逻辑
数据库：所选 HexClaw 服务使用 SQLite 保存会话和消息；本机与云端数据分别管理

数据归属：会话、学习记录、模型配置与连接保存在所选服务，切换不会自动迁移或合并数据。在线模型会接收任务中发送给它的内容，处理方式取决于所选 Provider。云端工具访问的是服务器环境，不会自动获得本机文件系统。

界面概览

河蟹 AI 桌面端采用「会话置顶 + 构建 / 连接 / 系统」三组侧栏导航。首次进入应用默认就是 「会话」；可用 ⌘+K 命令面板或 ⌘+数字快速跳转：

页面	分区	功能
会话	置顶	单一输入框、当前智能体上下文、模型与思考设置，流式输出、Artifact 预览、文档解析、语音输入
智能体	构建	创建 / 管理智能体角色，编辑默认助理人设（SOUL）
知识库	构建	文档（RAG 向量检索）与记忆（跨会话语义记忆）两个标签页
自动化	构建	定时任务（Cron）、Webhook、线性工作流三个标签页
连接	连接	IM 通道与账号、邮箱，以及文档平台、数据库与文件连接器（如 GitHub、MySQL、本地文件）
能力	连接	技能（ClawHub 市场）、MCP 服务器、Prompt 库三个标签页
日志	系统	实时 WebSocket 日志流，trace_id 追踪
设置	系统	模型服务商、自动化权限、系统设置（外观、通知等）

提示：另有全局快速对话悬浮窗，按 ⌘+⇧+H 可在任意位置随时唤起。

对话与会话 →

✏️ 在 GitHub 上编辑此页