HexClaw 河蟹

企业级安全的个人 AI Agent — 安全 · 开源 · 自托管 · 易用 · 功能全面

English | 中文

基于 Hexagon AI Agent 全能型框架构建

特性

核心能力

• ReAct Agent 引擎 — 推理 + 行动循环，支持多轮工具调用、流式输出、结构化交互消息，以及 plan-execute / reflection / tot 等 Agent 模式
• 六层安全网关 — 认证、限流、成本控制、注入检测、权限校验、审计日志
• LLM 智能路由 — 多 Provider 自动切换，故障降级，成本优化，模型 tool_call 能力探测
• Skill 系统 — 内置搜索/天气/翻译/摘要，7 阶段流水线，.pending 审批闭环，TrustLevel 与 TOCTOU 校验
• 语义缓存 — Singleflight 防击穿 + TTL 抖动防雪崩 + 空值缓存防穿透
• 知识库 — FTS5 + 向量混合检索，RAG 5 阶段 Pipeline，上下文增强

会话与数据

• 会话管理 — 创建/查询/删除会话，消息历史，会话分支 (fork)
• 全文搜索 — FTS5 驱动的消息搜索
• 上下文压缩 — LLM 驱动的旧消息摘要，防止 token 爆炸
• 文件驱动记忆 — MEMORY.md 长期记忆 + 每日日记，可审查可版本控制

自主行为

• Heartbeat 主动巡查 — Agent 定期自主检查待办事项并通知
• Cron 定时任务 — 定时报告、提醒、巡检（cron 表达式 + @every/@daily/@weekly）
• Webhooks — GitHub/GitLab/通用 JSON，HMAC-SHA256 签名验证
• 工作流引擎 — 可视化编排多步骤 Agent 工作流（Canvas Workflow）

生态扩展

• MCP 原生支持 — 兼容 3200+ MCP Server（stdio + SSE 传输）
• Markdown 技能市场 — 兼容 OpenClaw 技能格式，按需延迟加载
• 多 Agent 路由 — 一个实例托管多个 Agent，按平台/用户/群组路由
• Canvas / A2UI — Agent 生成交互式 UI（图表、表单、看板等 8 种组件）
• 安全审计 CLI — hexclaw security audit 一键安全检查 + 修复建议
• 语音交互 — STT/TTS 转写与合成，支持 MiniMax / Edge / OpenAI / Azure TTS 串联 fallback
• 桌面集成 — 系统通知、剪贴板交互（Tauri 桌面端）
• 实时日志 — WebSocket 日志流 + 统计分析

多平台接入（13 种）

WebSocket 安全：Web WebSocket 连接启用了 Origin 校验，仅允许 localhost 和 Tauri（tauri://localhost）来源，不再使用 InsecureSkipVerify。

快速开始

安装

# 从源码安装
go install github.com/hexagon-codes/hexclaw/cmd/hexclaw@latest

# 或使用预编译二进制（从 Releases 下载）
curl -sSL https://github.com/hexagon-codes/hexclaw/releases/latest/download/hexclaw-$(uname -s)-$(uname -m).tar.gz | tar xz
sudo mv hexclaw /usr/local/bin/

启动服务

# 设置 LLM API Key（任选一个）
export DEEPSEEK_API_KEY="sk-xxx"
# export OPENAI_API_KEY="sk-xxx"
# export ANTHROPIC_API_KEY="sk-xxx"

# 启动服务
hexclaw serve

Docker

docker run -d \
  --name hexclaw \
  -p 16060:16060 \
  -e DEEPSEEK_API_KEY="sk-xxx" \
  -v hexclaw-data:/data/.hexclaw \
  ghcr.io/hexagon-codes/hexclaw:latest

服务启动后：

• Web UI: http://127.0.0.1:16060
• 健康检查: GET http://127.0.0.1:16060/health
• 聊天 API: POST http://127.0.0.1:16060/api/v1/chat

使用 API

curl -X POST http://127.0.0.1:16060/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "user_id": "test-user"}'

安全审计

hexclaw security audit
hexclaw security audit --config hexclaw.yaml

配置文件

# 生成默认配置
hexclaw init

# 使用自定义配置启动
hexclaw serve --config ~/.hexclaw/hexclaw.yaml

详细的安装和部署指南请参考 docs/install.md

配置

配置文件 ~/.hexclaw/hexclaw.yaml：

server:
  host: 127.0.0.1
  port: 16060

llm:
  default: deepseek
  providers:
    deepseek:
      api_key: ${DEEPSEEK_API_KEY}
      model: deepseek-chat
    openai:
      api_key: ${OPENAI_API_KEY}
      model: gpt-4o

security:
  auth:
    enabled: true
  rate_limit:
    requests_per_minute: 20
  cost:
    budget_per_user: 10.0
    budget_global: 1000.0
  injection_detection:
    enabled: true
  pii_redaction:
    enabled: true

platforms:
  web:
    enabled: true
  telegram:
    enabled: false
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    enabled: false
    token: ${DISCORD_BOT_TOKEN}
  slack:
    enabled: false
    token: ${SLACK_BOT_TOKEN}
    signing_secret: ${SLACK_SIGNING_SECRET}

mcp:
  enabled: false
  servers:
    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@anthropic/mcp-filesystem"]

skills:
  enabled: true
  dir: ~/.hexclaw/skills/
  auto_load: true
  hub:
    repo_url: https://github.com/hexagon-codes/hexclaw-hub
    branch: v0.0.1

heartbeat:
  enabled: false
  interval_mins: 15
  quiet_start: "22:00"
  quiet_end: "08:00"

cron:
  enabled: false

webhook:
  enabled: false

file_memory:
  enabled: true
  dir: ~/.hexclaw/memory/

compaction:
  enabled: true
  max_messages: 50
  keep_recent: 10

knowledge:
  enabled: true
  chunk_size: 400
  top_k: 3

features:
  # v0.4 新能力默认按 alpha flag fail-closed，需要显式开启后才改变运行时路径。
  model.gateway.v1: false
  skill.pipeline.v1: false
  config.tx.hotload.v1: false
  events.transport.v1: false

skill:
  sandbox:
    enabled: true
    timeout: 30s

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

所有配置项支持环境变量替换（${VAR_NAME}）。

Feature Flags

v0.4 新增能力统一通过 features: 段启用。未注册的 flag 永远返回关闭，alpha
阶段即使代码默认值写 true 也会强制关闭，避免实验能力意外进入生产路径。

常见 flag：

• agent.factory.real：允许按 dispatch_role 分派到真实 hexagon.Agent
• skill.pipeline.v1：启用 Skill 7 阶段执行流水线
• interactive.render.v1：交互消息走平台原生 renderer；关闭时使用文本 fallback
• config.tx.hotload.v1：LLM 配置保存走事务热加载
• model.gateway.v1：启用 Provider middleware 链路
• events.transport.v1：启用结构化事件 Sink 投递
• rag.pipeline.v1：启用知识库 5 阶段 RAG Pipeline
• voice.tts.chain.v1：启用多 TTS Provider 串联 fallback

架构

用户 → 平台适配器(13种) → 安全网关(6层) → Agent 路由 → Agent 引擎 → LLM Provider
         │                    │              │            │            │
   Web/飞书/Telegram    认证→限流→成本    多Agent路由   ReAct 推理    DeepSeek/OpenAI
   Discord/Slack/...    →安全→权限→审计   工作流引擎    Skill/MCP    Claude/Qwen/...
   钉钉/企微/微信/...                                   知识库RAG
   WhatsApp/LINE/...                                    会话分支
   Matrix/Email

六层安全网关

第 3/4 层在服务异常时拒绝请求（fail-closed），而非静默放行。详见 SECURITY.md。

目录结构

hexclaw/
├── hexclaw.go               # 根包（版本信息 + 包文档）
├── cmd/hexclaw/             # CLI 入口 (serve/init/security audit/skill)
├── adapter/                 # 平台适配器
│   ├── web/                 #   Web WebSocket
│   ├── feishu/              #   飞书 Bot
│   ├── telegram/            #   Telegram Bot
│   ├── dingtalk/            #   钉钉 Bot
│   ├── discord/             #   Discord Bot
│   ├── slack/               #   Slack Bot
│   ├── wecom/               #   企业微信
│   ├── wechat/              #   微信公众号
│   ├── whatsapp/            #   WhatsApp
│   ├── line/                #   LINE
│   ├── matrix/              #   Matrix
│   └── email/               #   Email (IMAP/SMTP)
├── agents/                  # Agent 角色 (6 种预置角色)
├── api/                     # REST API 服务
│   ├── server.go            #   核心服务器 + 聊天 + 路由注册
│   ├── handler_config.go    #   LLM 配置查询/更新/测试/模型发现 API
│   ├── handler_capabilities.go # 模型 tool_call 能力探测 API
│   ├── handler_extended.go  #   工作流/配置/版本/统计 API
│   ├── handler_logs.go      #   日志查询/统计/实时流 API
│   ├── handler_knowledge.go #   知识库 API
│   ├── handler_webhook.go   #   Webhook API
│   ├── handler_cron.go      #   定时任务 API
│   └── handler_misc.go      #   记忆/MCP/技能/路由/Canvas/语音 API
├── audit/                   # 安全审计 (7 类检查)
├── cache/                   # LLM 响应语义缓存
├── canvas/                  # Canvas/A2UI (8 种组件)
├── config/                  # 配置管理 (YAML + 环境变量)
├── cron/                    # 定时任务调度
├── desktop/                 # 桌面集成 (通知/剪贴板)
├── engine/                  # Agent 引擎（ReAct 推理循环）
├── events/                  # 结构化事件协议与 Sink
├── eval/                    # 发版前评测套件
├── featureflag/             # Feature flag 注册与运行时查询
├── gateway/                 # 六层安全网关
├── heartbeat/               # 心跳巡查
├── knowledge/               # 知识库 (FTS5 + 向量混合检索)
├── llmrouter/               # LLM 智能路由
├── mcp/                     # MCP Client (stdio + SSE)
├── memory/                  # 文件记忆 (MEMORY.md + 日记)
├── plugin/                  # 插件 Manifest / Capability 扩展
├── release/                 # 发版门禁与 canary 状态机
├── router/                  # 多 Agent 路由
├── runtime/                 # 沙箱与 Checkpoint 回滚
├── session/                 # 会话管理 + 上下文压缩
├── skill/                   # Skill 系统
│   ├── builtin/             #   内置 Skill (搜索/天气/翻译/摘要)
│   ├── marketplace/         #   Markdown 技能市场
│   └── sandbox/             #   沙箱执行
├── storage/                 # 数据存储
│   └── sqlite/              #   SQLite 驱动
├── voice/                   # 语音交互 (STT/TTS)
├── webhook/                 # Webhook 接收
├── go.mod
└── Makefile

API 端点（常用接口摘录，完整路由按模块启用）

核心

会话管理

配置

知识库

定时任务

Webhook

记忆

MCP

技能

默认技能目录仓库：https://github.com/hexagon-codes/hexclaw-hub 的 v0.0.2 标签（index.json + skills/*.md）。
安装或卸载 Markdown 技能后，会自动同步运行时技能注册表；通常无需重启 sidecar。

Agent 路由

平台实例 / IM 通道

Canvas / 工作流

语音

桌面集成

团队协作

日志与监控

与桌面端对齐的响应语义

• POST /api/v1/config/llm/test 返回 ok、message、provider、model、latency_ms；当 provider.type=ollama 时可省略 api_key，便于测试本地 OpenAI 兼容端点。
• GET /api/v1/skills 稳定返回 enabled；PUT /api/v1/skills/{name}/status 额外返回 effective_enabled、requires_restart、message。
• POST /api/v1/skills/install 支持 clawhub://skill-name 和本地相对路径；成功时返回 requires_restart=false 与 runtime_registered=true，表示已热同步到运行引擎。
• GET /api/v1/cron/jobs/{id}/history 的历史项包含 result，可直接查看最近一次执行输出摘要。
• POST /api/v1/knowledge/search 返回结构化结果数组（result 和 results 字段均为 []SearchHit），包含文档标题、来源、chunk 位置、内容和相似度分数，适合直接在前端展示引用来源。result 不再是拼接后的纯字符串。
• GET /api/v1/knowledge/documents/{id} 返回单个文档的完整信息，包含全部内容。
• GET /api/v1/knowledge/documents 返回 status、error_message、updated_at、source_type；POST /api/v1/knowledge/upload 返回 status、source、chunk_count、warnings。
• POST /api/v1/agents/rules/test 会返回命中规则与分数，便于解释“为什么路由到这个 Agent”。
• GET /api/v1/logs 的日志项包含稳定 domain 字段，可按 chat / knowledge / integration / automation / engine 等功能域过滤。
• POST /api/v1/config/llm/models 向 Provider 的 /models 端点发起代理请求，返回标准化的模型列表（{ models: [{ id, name }] }）；支持 OpenAI 标准格式和替代格式的自动适配。
• GET /api/v1/llm/capabilities 返回 { provider_name, model_name, tool_call, tool_call_text, last_probe, probe_error }；POST /api/v1/llm/capabilities/probe?provider=X&model=Y 会实时重测并写入 SQLite 缓存。

开发

前置要求

Make 命令

手动命令

# 构建
go build ./...

# 运行测试
go test ./...

# 运行指定测试
go test -run TestName ./package/

# 代码检查
go vet ./...
golangci-lint run

# 发版前门禁 + Eval + canary dry-run
go run ./cmd/verify-release -repo . -version 0.4.0 -version-files package.json

技术栈

贡献指南

工作流程

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

Commit Message 格式

遵循 Conventional Commits 规范：

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

代码规范

• 格式化: make fmt
• 静态检查: make vet
• Lint: make lint
• 提交前请确保 make test 全部通过

相关项目

更新日志

v0.4.0

新功能

• Feature flag 基建 — features: 配置段统一控制 v0.4 新能力，未注册 flag fail-closed，alpha 默认关闭
• 模型能力探测 — 新增 /api/v1/llm/capabilities 与 /probe，缓存模型 tool_call 可靠度
• Skill 闭环 — 新增 7 阶段 Pipeline、skill_view 渐进披露、.pending 审批、TrustLevel 与 TOCTOU 防护
• 交互式回复 — Reply.Interactive 支持 buttons/select/approval/card，并在 IM 适配器中提供文本 fallback
• 运行时治理 — 新增 Provider middleware、结构化事件、权限策略、MCP 生命周期 hook、RAG Pipeline、Runtime Sandbox 与发版门禁
• 语音增强 — 新增 MiniMax TTS 与多 Provider TTS 串联 fallback

v0.3.0

新功能

• 动态模型发现 — 新增 POST /api/v1/config/llm/models 端点，代理到 Provider 的 /models API 获取可用模型列表，支持 OpenAI 格式（{ data: [...] }）和替代格式（{ models: [...] }）
• MCP 路径 ~ 展开 — MCP Server 参数中的 ~ 和 ~/subpath 自动展开为用户主目录，跨平台支持（macOS/Linux/Windows，基于 os.UserHomeDir()）

修复

• 飞书思考占位消息 — 飞书适配器收到消息后立即发送思考占位消息（如 "🤔 思考中..."），AI 处理完成后通过 patchMessage 替换为最终回复，SDK（WebSocket）和 Webhook 两条路径均已覆盖
• 流式工具调用修复 — ProcessStream 带工具时原使用 pipeStreamWithTools（不执行工具），修复为使用 processStreamToolLoop，完整执行工具 → 反馈结果 → 继续 LLM 推理循环
• Reasoning 内容持久化 — pipeStream 和 pipeStreamWithTools 将 reasoning/thinking 内容流式推送给前端但未收集用于持久化，新增 fullReasoning 收集逻辑和 SaveAssistantMessageWithMeta() 方法，将 reasoning 保存到消息元数据 JSON

联系我们

• 官网: hexclaw.net
• 河蟹 AI: [email protected]
• 河蟹支持: [email protected]
• Issues: GitHub Issues
• 安全漏洞: 请参阅 SECURITY.md

微信公众号

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

许可证

Apache License 2.0