河蟹 AI 文档

快速上手

5 分钟完成安装、配置，发送第一条消息。

系统要求

平台	最低要求
macOS	12 Monterey 及以上，Apple Silicon / Intel
Windows	Windows 10 (1809+)，x64
Linux	Ubuntu 20.04+ / Fedora 36+，x64

安装

方式一：一行脚本安装（macOS 推荐）

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

方式二：Homebrew 安装（macOS）

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

方式三：下载安装包

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

macOS：.dmg — 拖入 Applications 即可
Windows：.exe — 双击安装
Linux：.AppImage 或 .deb

方式四：源码编译

git clone https://github.com/hexagon-codes/hexclaw-desktop.git
cd hexclaw-desktop
pnpm install
pnpm tauri dev

提示：源码编译需要 Node.js 20.19+、pnpm、Rust stable (2021 edition) 和 Go 1.23+（用于 Sidecar 引擎）。

首次启动向导

首次打开河蟹 AI 时，会自动进入 3 步设置向导：

配置 AI 服务商 — 选择 Provider、填入 API Key，并完成模型连接测试
选择默认角色 — 选择进入应用后默认使用的智能体角色
确认工作上下文 — 核对服务商、模型、默认角色后开始使用

完成向导后自动进入聊天页。后续可在 设置 → 模型服务商 中修改配置。

提示：如果跳过了向导，下次打开应用仍会提示配置（直到至少添加一个 Provider）。

河蟹 AI 首次启动向导第一步：配置 AI 服务商 — 第一步：选择服务商、填写 API Key，并在进入主界面前先完成一次连接测试。

河蟹 AI 首次启动向导第二步：选择默认角色 — 第二步：选择默认智能体角色，确定进入系统后的首个工作模式。

河蟹 AI 首次启动向导第三步：确认工作上下文 — 第三步：确认服务商、模型和默认角色，随后直接进入第一条真实会话。

首次配置

1. 配置 AI 服务商

打开应用后进入 设置 → 模型服务商，添加至少一个 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 格式的服务

配置文件示例

河蟹 AI 也支持通过 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. 发送第一条消息

进入对话页面，在输入框输入任意内容，按回车发送。支持流式输出，实时显示 AI 回复。

首次排障入口

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

打开 设置 → 模型服务商，对当前 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），负责模型调用、工作流执行、知识库、记忆等核心逻辑
数据库：SQLite，本地存储会话和消息

数据隐私：所有数据存储在本地，不经过任何第三方服务器（除你配置的 AI API 外）。

界面概览

河蟹 AI 提供 14 个功能页面：

页面	功能
仪表盘	全局统计：会话数、消息数、Agent 数、知识库、引擎状态
对话	多模型聊天、流式输出、Artifact 预览、消息导出
Agent	创建/管理 AI 角色，多 Agent 会议模式
工作流画布	可视化拖拽编排，DAG 执行引擎
定时任务	Cron 定时调度 Agent 自动执行
技能市场	安装/管理技能插件
知识库	文档上传、RAG 向量检索
记忆	跨会话语义记忆管理
MCP	Model Context Protocol 服务器注册和工具发现
日志	实时 WebSocket 日志流
团队	共享 Agent、成员协作
设置	服务商配置、安全策略、外观主题、通知

河蟹 AI 概览页界面 — 建议第一次进入应用后先看概览页，确认系统状态、当前入口和可用能力，再进入聊天、智能体或自动化页面。

对话与会话 →

✏️ 在 GitHub 上编辑此页