河蟹 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.4.9）：

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

方式四：源码编译

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 桌面端采用「Chat 置顶 + 构建 / 连接 / 系统」三组侧栏导航。首次进入应用默认就是 Chat；可用 ⌘+K 命令面板或 ⌘+数字快速跳转：

页面	分区	功能
Chat	置顶	对话 / Agent / 深度思考三种模式，流式输出、Artifact 预览、文档解析、语音输入
Agent	构建	创建 / 管理智能体角色，编辑默认助理人设（SOUL）
知识库	构建	文档（RAG 向量检索）与记忆（跨会话语义记忆）两个标签页
自动化	构建	定时任务（Cron）、Webhook、线性工作流三个标签页
连接中心	连接	IM 通道与账号、邮箱，以及数据连接器（GitHub / Notion）
集成	连接	技能（ClawHub 市场）、MCP 服务器、Prompt 库三个标签页
日志	系统	实时 WebSocket 日志流，trace_id 追踪
设置	系统	模型服务商、安全策略、外观主题、通知推送

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

对话与会话 →

✏️ 在 GitHub 上编辑此页