HexClaw 河蟹

可自托管的个人 AI Agent，让对话连接工具、知识和自动化。

快速开始 · 第一条消息 · API · 官网 · 桌面客户端 · English

HexClaw 是用 Go 编写的 Agent 服务，可独立运行，也可作为 HexClaw Desktop 的本地 Sidecar 或云端后端。它把模型调用、工具执行、知识检索、长期记忆和定时任务集成到同一服务中，通过桌面客户端、API 和消息渠道使用。

对话之外，HexClaw 可以处理文件、生成文档和图片、执行代码、运行工作流，并把结果送到已配置的渠道。模型、工具和场景能力按配置接入，数据保存在当前使用的后端。

本 README 描述 v0.5.1 源码能力。已发布二进制、镜像与桌面安装包以所选 Release 为准。Desktop 当前仍固定后端 refs/tags/v0.5.0；发布后端 v0.5.1 Tag 后，需同步 Desktop 固定引用，再构建桌面安装包。

上图展示 HexClaw 在桌面客户端中的作业辅导场景，复用官方 K12 教程的真实界面与专属皮肤。教程适用 Desktop v0.5.0-beta.3 / HexClaw v0.5.0-beta.1，截图沿用 v0.5.0-beta 场景基线；作业素材为 AI 生成示例 · 非真实学生作业。

• 快速开始
• 核心能力
• 工作原理
• 配置
• API 与扩展
• 开发与贡献
• 文档与生态
• 许可证

文档渲染、代码执行和媒体生成按需配置可选运行依赖。

通过 HexClaw Desktop 使用本机 HexClaw 服务时，macOS 用户可使用一键安装（推荐）：

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

该命令安装桌面客户端及其本地 Sidecar。Windows、Linux 安装包与首次配置见 Desktop 安装说明。独立部署 Agent 服务使用下面的 Go、二进制或容器方式。

从 Releases 下载与你的系统和架构对应的二进制；开发者也可以使用 Go 安装：

go install github.com/hexagon-codes/hexclaw/cmd/hexclaw@latest

export DEEPSEEK_API_KEY="你的 API Key"
hexclaw serve

@latest 选择稳定版。使用预发布版时，指定 Releases 中实际存在的版本 Tag。

使用 go install 时，确保 GOBIN（默认 $(go env GOPATH)/bin）位于 PATH，才能直接运行 hexclaw。

以下命令构建当前主线代码：

git clone https://github.com/hexagon-codes/hexclaw.git
cd hexclaw
make build

export DEEPSEEK_API_KEY="你的 API Key"
./bin/hexclaw serve

也支持 OPENAI_API_KEY、ANTHROPIC_API_KEY、QWEN_API_KEY 和 GEMINI_API_KEY。自定义服务或本地 Ollama 使用配置文件接入。

默认地址为 http://127.0.0.1:16060，配置和数据位于 ~/.hexclaw/。服务可以在未配置模型时启动；聊天、图片处理和其他模型任务需要对应用途的可用 Provider。

hexclaw init 会生成并保存业务 API 令牌；直接启动独立服务时，也会为缺少令牌的配置补齐 server.api_token，已有值保持不变。在另一个终端，将该值设置为下面示例使用的环境变量：

export HEXCLAW_API_TOKEN="配置文件中的 server.api_token"

curl --fail-with-body http://127.0.0.1:16060/api/v1/chat \
  -H "Authorization: Bearer ${HEXCLAW_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"message":"你好，介绍一下你能做什么"}'

成功响应为 200 application/json，包含回答与会话 ID。下面仅示意主要字段，回复文本由模型决定：

{
  "reply": "模型生成的回答",
  "session_id": "服务返回的会话 ID"
}

收到完整回答说明该次文本对话已完成；健康检查通过只说明服务运行。将实际返回的 session_id 代入下一次请求，继续同一会话：

curl --fail-with-body http://127.0.0.1:16060/api/v1/chat \
  -H "Authorization: Bearer ${HEXCLAW_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"message":"继续刚才的话题","session_id":"上次响应的 session_id"}'

附件、结构化产物和 SSE 终态见聊天 API。

希望通过图形界面使用，安装 HexClaw Desktop。Desktop 管理本地 Sidecar 的启动和连接，也支持配置云端后端。

在源码目录构建并启动：

docker compose build hexclaw
docker compose up -d hexclaw

默认 Compose 使用本地 hexclaw:dev 镜像，把完整可写 HOME 持久化到 hexclaw-data 卷。当前镜像面向 Linux amd64，包含文档渲染、中文字体和 Python/SymPy 依赖；默认不安装 Ollama 或下载模型。

使用已发布镜像、设置模型和 API 令牌，以及 HTTPS、Kubernetes、备份和更新，见云端部署指南。

• 桌面与 API：HexClaw Desktop、HTTP API、WebSocket。
• 消息渠道：飞书、钉钉、Telegram、Discord、Slack、企业微信、微信公众号、WhatsApp、LINE、Matrix、Email。
• 自动触发：定时任务、Webhook、Heartbeat、工作流。

钉钉主要通过官方 Stream SDK 接收消息，无需为接入配置公网回调地址；同时保留 HTTP Webhook 兼容路径。各渠道的传输和展示能力不同，具体配置见安装指南。

K12 当前面向小学，覆盖数学、语文、英语、科学、信息科技和美术。家长可以在 Desktop 或已绑定的钉钉渠道发图，由同一领域任务处理作业、空白题、作文或美术作品。

通用助手也可直接调用 K12 Skill 解答、验算和讲解文字题，无需创建或关联另一位辅导助手。独立调用按当前会话保存执行回执和报告；只有当前已登记的学生身份才沉淀错题与学情，不借用其他孩子的档案。长讲解的 PDF 沿原会话返回，原请求重放复用已有结果，调用结果未知时不自动重发。

图片作业批改以带批注的原图为主要结果。无法可靠辨认的内容标注“无法识别”，可识别部分继续处理；Provider 调用失败和内容无法识别分别记录。题干清楚、学生笔迹不清时，独立参考答案与学生判分分开保存；参考答案不证明学生答对或已掌握。支持的教学图随同一冻结讲法进入现有答案和 PDF。错题、复习与周练关联当前孩子的档案、实际作答证据和任务记录。

教材能力基于真实上传教材提取目录和封面证据，支持数学教材绑定与 AI 课程进度建议。建议用于后续任务的上下文，不代表孩子已经学过或掌握；人工确认的进度不会被同范围推算覆盖。没有可用教材或课程进度时，仍可处理实际题目。

各入口进入统一执行服务，按任务使用 ReAct Agent、场景任务、脚本或工作流。模型、工具、记忆与知识库按需参与；交互任务经原入口回复，自动化任务向已配置的目标投递结果。

运行时加载会话和相关上下文，调用模型推理，按需执行工具，并把工具结果交回模型。普通会话与 K12 绑定会话的连续追问使用各自历史；当前原始输入和图片受到保护，旧工具媒体随所属调用组压缩。模型调用失败后的同次回退保留已完成工具结果与已显示文本。完成后保存会话与运行记录，返回回答和实际产物。

图示下载：架构 PNG · 任务流程 PNG。

默认配置文件为 ~/.hexclaw/hexclaw.yaml。首次使用可以生成配置模板：

hexclaw init
hexclaw serve --config ~/.hexclaw/hexclaw.yaml

已有配置时直接编辑并启动。配置文件加载时，${VAR_NAME} 按当前进程环境展开，未设置的变量为空值。一个最小的云端模型配置如下：

server:
  host: 127.0.0.1
  port: 16060

llm:
  default: deepseek
  providers:
    deepseek:
      api_key: ${DEEPSEEK_API_KEY}
      model: deepseek-chat

storage:
  driver: sqlite
  sqlite:
    path: ~/.hexclaw/data.db

独立服务会为缺少 server.api_token 的配置生成持久令牌。自定义 OpenAI 兼容服务可在 Provider 下设置 base_url 与 compatible: openai；Ollama、视觉模型、Embedding 和其他选项见安装与配置指南、配置结构和默认配置模板。

认证、限流、成本检查、输入处理、权限和审计由服务侧统一执行。无人值守默认使用 security.autonomy.profile: function_first，具体自动执行范围由 Profile、来源覆盖配置和工具权限策略决定；查看安全说明与配置定义，按实际任务调整。

业务 API 使用 Bearer 令牌；GET /health 是公开入口，不要求令牌，健康响应不证明所选模型和任务链路可用。下面是常用入口；接口是否挂载取决于相应模块和依赖是否启用。

完整的模块接口参考、调用示例、响应和失败契约见公共 API 文档，机器可读描述见 OpenAPI。内部原生桥接、条件挂载和保留兼容入口分别标明适用范围；源码入口 API 服务仅作为实现参考。K12 集成见场景 API：

• 档案整体更新：教材、进度与绑定的事务更新、版本冲突和幂等输入。
• 教材与课程进度：创建与更新的省略 / null 语义、人工优先、只读预览与 CAS 采用。
• 图片任务终态：自动推进、无法识别与技术失败，以及批注原图的实际交付。

推荐使用 code_exec 执行代码任务，输出运行信息与产物清单。旧宿主执行工具 code、shell 保留显式配置兼容，默认关闭。

make build    # 构建到 bin/hexclaw
make run      # 构建并启动开发服务
make fmt      # 格式化
make vet      # 静态检查
make test     # 执行现有测试

仓库主要模块：

贡献前阅读 CONTRIBUTING.md，其中维护开发规范、检查范围和 CI/CD 固定基线。问题与功能讨论通过 GitHub Issues提交；安全问题按 SECURITY.md中的方式报告。

HexClaw 生态从通用基础库、模型接入和 Agent 框架，延伸到服务、桌面工作台与技能市场：

• 官网：hexclaw.net
• 问题与建议：GitHub Issues
• 河蟹 AI：ai@hexclaw.net
• 河蟹支持：support@hexclaw.net

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

HexClaw 使用 Apache License 2.0。