{"id":47611445,"url":"https://github.com/hexagon-codes/hexclaw","last_synced_at":"2026-07-04T02:02:34.230Z","repository":{"id":344091150,"uuid":"1177624184","full_name":"hexagon-codes/hexclaw","owner":"hexagon-codes","description":"HexClaw — 企业级 AI Agent 后端。多模型对话，RAG 知识库，Tool Call 代理，Skill 系统，MCP 协议，代码沙箱，飞书/钉钉/Telegram 等多平台 IM 接入。Hexagon 生态 L3。","archived":false,"fork":false,"pushed_at":"2026-07-03T19:32:34.000Z","size":11209,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T21:07:13.445Z","etag":null,"topics":["ai-agent","chatbot","discord","feishu","golang","mcp","rag","sandbox","telegram","tool-calling"],"latest_commit_sha":null,"homepage":"https://hexclaw.net","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hexagon-codes.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit/audit.go","citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T07:53:58.000Z","updated_at":"2026-07-03T19:32:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hexagon-codes/hexclaw","commit_stats":null,"previous_names":["everyday-items/hexclaw","hexagon-codes/hexclaw"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/hexagon-codes/hexclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagon-codes%2Fhexclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagon-codes%2Fhexclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagon-codes%2Fhexclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagon-codes%2Fhexclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexagon-codes","download_url":"https://codeload.github.com/hexagon-codes/hexclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagon-codes%2Fhexclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35107464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","chatbot","discord","feishu","golang","mcp","rag","sandbox","telegram","tool-calling"],"created_at":"2026-04-01T20:24:58.907Z","updated_at":"2026-07-04T02:02:34.216Z","avatar_url":"https://github.com/hexagon-codes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\".github/assets/logo.jpg\" alt=\"HexClaw Logo\" width=\"180\" /\u003e\n  \u003ch1\u003eHexClaw\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eEnterprise-Grade Personal AI Agent\u003c/strong\u003e — Secure · Open Source · Self-Hosted · Easy to Use · Feature-Rich\u003c/p\u003e\n\n  [![CI](https://github.com/hexagon-codes/hexclaw/workflows/CI/badge.svg)](https://github.com/hexagon-codes/hexclaw/actions)\n  [![Release](https://img.shields.io/github/v/release/hexagon-codes/hexclaw?include_prereleases)](https://github.com/hexagon-codes/hexclaw/releases)\n  [![License](https://img.shields.io/github/license/hexagon-codes/hexclaw)](https://github.com/hexagon-codes/hexclaw/blob/main/LICENSE)\n  [![Go Report Card](https://goreportcard.com/badge/github.com/hexagon-codes/hexclaw)](https://goreportcard.com/report/github.com/hexagon-codes/hexclaw)\n\n  **English | [中文](README.md)**\n\n  \u003e Built on [Hexagon](https://github.com/hexagon-codes/hexagon) — the all-in-one AI Agent framework\n\u003c/div\u003e\n\n## Features\n\n### Core Capabilities\n- **ReAct Agent Engine** — Reasoning + Action loop with multi-turn tool calls, streaming output, structured interactive replies, and Agent modes such as `plan-execute`, `reflection`, and `tot`\n- **6-Layer Security Gateway** — Auth, rate limiting, cost control, injection detection, permission check, audit logging\n- **LLM Smart Router** — Multi-provider auto-switching, failover, cost optimization, and model tool-call capability probing\n- **Skill System** — Built-in search/weather/translation/summary/media-generation/messaging/document-export and more, 7-phase pipeline, `.pending` approval flow, TrustLevel filtering, and TOCTOU checks\n- **Semantic Cache** — Singleflight anti-stampede + TTL jitter anti-avalanche + empty-value anti-penetration\n- **Knowledge Base** — FTS5 + vector hybrid retrieval, 5-stage RAG pipeline, and context augmentation\n\n### Built-in Skills\n\nReady-to-use built-in skills (no install required, invoked via LLM tool_call):\n\n| Skill | Function |\n|-------|----------|\n| `search` | Web search to find information on the internet |\n| `weather` | Look up city weather |\n| `translate` | Translate text (Chinese ↔ English) |\n| `summary` | Summarize text content |\n| `browser` | Fetch web pages, extract content, and submit forms |\n| `code` / `code_exec` | Execute code snippets (Go/Python/JavaScript) inside the HexClaw Sandbox and return output |\n| `shell` | Run shell commands and return output |\n| `file_ops` / `file_edit` | Read, write, and edit files in the workspace |\n| `grep` / `glob` | Search file contents by text/regex; find files by name pattern |\n| `knowledge_ingest` | Write text content into the local knowledge base for later retrieval |\n| `knowledge_ingest_path` | Read each file under a path (directory or glob) and ingest its content into the knowledge base (sandboxed against `..`/symlink escape; capped at 200 files / 2 MiB per file) |\n| `media_generate` | Generate an image (default) or video from a text prompt, persist it, and return a stable file path reusable by export/send/ingest |\n| `export_document` | Render Markdown into a downloadable document (md/html/docx/pdf/epub/odt/rtf/txt) and return its file path |\n| `send_message` | Send a message to a configured channel (feishu/Discord/WeChat/email/Slack/...); interactive sessions use confirmation, while unattended automation follows the `security.autonomy` matrix |\n| `cron_task` | Create/list/pause/resume/remove app-managed scheduled tasks |\n| `manage_skill` / `manage_mcp` | Search, install, or remove skills / MCP servers from HexClaw Hub; unattended dispatch does not auto-run these by default unless `capability` is explicitly enabled |\n\n\u003e Unattended automation (cron/webhook/spawn/heartbeat/workflow) uses a function-first profile plus an explicit switch matrix. The default `function_first` profile auto-approves core work such as `code_exec`, shell, file edits, browsing, knowledge ingest, and delivery. Skill/MCP management, publishing, and forgeable `solve` sources are not auto-approved by default; enable them through `security.autonomy.system_dispatch` or the explicit `full_access` profile. Explicit `PermissionPolicy` deny rules remain authoritative.\n\u003e `system_dispatch.\u003csource\u003e` replaces that source's profile default; it does not merge with it. Use `profile: full_access` when you want a global explicit open mode.\n\n### Session \u0026 Data\n- **Session Management** — Create/query/delete sessions, message history, session forking\n- **Full-Text Search** — FTS5-powered message search\n- **Context Compaction** — LLM-driven summarization of old messages to prevent token overflow\n- **File-Driven Memory** — MEMORY.md long-term memory + daily journal, auditable and version-controlled\n\n### Autonomous Behavior\n- **Heartbeat Patrol** — Agent periodically checks todos and sends notifications autonomously\n- **Cron Jobs** — Scheduled reports, reminders, inspections (cron expressions + @every/@daily/@weekly)\n- **Webhooks** — GitHub/GitLab/generic JSON with HMAC-SHA256 signature verification\n- **Workflow Engine** — Visual orchestration of multi-step Agent workflows (Canvas Workflow)\n\n### Ecosystem \u0026 Extensions\n- **Native MCP Support** — Compatible with 3200+ MCP Servers (stdio + SSE transport)\n- **Markdown Skill Marketplace** — Compatible with OpenClaw skill format, lazy-loaded on demand\n- **Multi-Agent Routing** — Host multiple agents in one instance, route by platform/user/group\n- **Canvas / A2UI** — Agent-generated interactive UIs (charts, forms, kanban, and 8+ component types)\n- **Security Audit CLI** — `hexclaw security audit` one-click security check + remediation suggestions\n- **Voice Interaction** — STT/TTS transcription and synthesis with chained MiniMax / Edge / OpenAI / Azure TTS fallback\n- **Desktop Integration** — System notifications, clipboard interaction (Tauri desktop client)\n- **Real-Time Logs** — WebSocket log streaming + analytics\n\n### Multi-Platform Support (13 platforms)\n\n| Platform | Method | Status |\n|----------|--------|:------:|\n| Web UI | WebSocket | ✅ |\n| Feishu | SDK WebSocket + HTTP Webhook | ✅ |\n| Telegram | Long polling | ✅ |\n| DingTalk | HTTP Webhook | ✅ |\n| Discord | Gateway WebSocket | ✅ |\n| Slack | Events API | ✅ |\n| WeCom | HTTP Callback + AES | ✅ |\n| WeChat Official Account | XML + passive/customer reply | ✅ |\n| WhatsApp | Cloud API Webhook | ✅ |\n| LINE | Messaging API Webhook | ✅ |\n| Matrix | Client-Server API | ✅ |\n| Email | IMAP/SMTP | ✅ |\n| REST API | HTTP | ✅ |\n\n\u003e **WebSocket Security**: The Web WebSocket endpoint now validates the Origin header, allowing only localhost and Tauri (`tauri://localhost`) origins. `InsecureSkipVerify` is no longer used.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install from source\ngo install github.com/hexagon-codes/hexclaw/cmd/hexclaw@latest\n\n# Or use a pre-built binary (download from Releases)\ncurl -sSL https://github.com/hexagon-codes/hexclaw/releases/latest/download/hexclaw-$(uname -s)-$(uname -m).tar.gz | tar xz\nsudo mv hexclaw /usr/local/bin/\n```\n\n### Start the Service\n\n```bash\n# Set LLM API Key (choose one)\nexport DEEPSEEK_API_KEY=\"sk-xxx\"\n# export OPENAI_API_KEY=\"sk-xxx\"\n# export ANTHROPIC_API_KEY=\"sk-xxx\"\n\n# Start the service\nhexclaw serve\n```\n\n### Docker\n\n```bash\ndocker run -d \\\n  --name hexclaw \\\n  -p 16060:16060 \\\n  -e DEEPSEEK_API_KEY=\"sk-xxx\" \\\n  -v hexclaw-data:/data/.hexclaw \\\n  ghcr.io/hexagon-codes/hexclaw:latest\n```\n\nAfter startup:\n- Web UI: `http://127.0.0.1:16060`\n- Health check: `GET http://127.0.0.1:16060/health`\n- Chat API: `POST http://127.0.0.1:16060/api/v1/chat`\n\n### Use the API\n\n```bash\ncurl -X POST http://127.0.0.1:16060/api/v1/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Hello\", \"user_id\": \"test-user\"}'\n```\n\n### Security Audit\n\n```bash\nhexclaw security audit\nhexclaw security audit --config hexclaw.yaml\n```\n\n### Configuration File\n\n```bash\n# Generate default config\nhexclaw init\n\n# Start with custom config\nhexclaw serve --config ~/.hexclaw/hexclaw.yaml\n```\n\n\u003e For detailed installation and deployment guide, see [docs/install.en.md](docs/install.en.md)\n\n## Configuration\n\nConfiguration file `~/.hexclaw/hexclaw.yaml`:\n\n```yaml\nserver:\n  host: 127.0.0.1\n  port: 16060\n\nllm:\n  default: deepseek\n  providers:\n    deepseek:\n      api_key: ${DEEPSEEK_API_KEY}\n      model: deepseek-chat\n    openai:\n      api_key: ${OPENAI_API_KEY}\n      model: gpt-4o\n\nsecurity:\n  auth:\n    enabled: true\n  rate_limit:\n    requests_per_minute: 20\n  cost:\n    budget_per_user: 10.0\n    budget_global: 1000.0\n  injection_detection:\n    enabled: true\n  pii_redaction:\n    enabled: true\n  autonomy:\n    # function_first(default) / balanced / strict / full_access\n    profile: function_first\n    # Optional explicit overrides. Values support categories, exact tool names,\n    # glob patterns, or \"*\". Categories:\n    # read,browser,exec,files,automation,delivery,media,heal,capability,publish\n    # system_dispatch:\n    #   webhook: [read, browser, exec, files, delivery, media, capability]\n    #   workflow: [read, browser, exec, files, automation, delivery, media, heal]\n\nplatforms:\n  web:\n    enabled: true\n  telegram:\n    enabled: false\n    token: ${TELEGRAM_BOT_TOKEN}\n  discord:\n    enabled: false\n    token: ${DISCORD_BOT_TOKEN}\n  slack:\n    enabled: false\n    token: ${SLACK_BOT_TOKEN}\n    signing_secret: ${SLACK_SIGNING_SECRET}\n\nmcp:\n  enabled: false\n  servers:\n    - name: filesystem\n      transport: stdio\n      command: npx\n      args: [\"-y\", \"@anthropic/mcp-filesystem\"]\n\nskills:\n  enabled: true\n  dir: ~/.hexclaw/skills/\n  auto_load: true\n  hub:\n    repo_url: https://github.com/hexagon-codes/hexclaw-hub\n    branch: v0.0.2\n\nheartbeat:\n  enabled: false\n  interval_mins: 15\n  quiet_start: \"22:00\"\n  quiet_end: \"08:00\"\n\ncron:\n  enabled: false\n\nwebhook:\n  enabled: false\n\nfile_memory:\n  enabled: true\n  dir: ~/.hexclaw/memory/\n\ncompaction:\n  enabled: true\n  max_messages: 50\n  keep_recent: 10\n\nknowledge:\n  enabled: true\n  chunk_size: 400\n  top_k: 3\n\nfeatures:\n  # Product capabilities are function-first and enabled by default; override only for rollback/rollout.\n  model.gateway.v1: true\n  skill.pipeline.v1: true\n  config.tx.hotload.v1: true\n  rag.pipeline.v1: true\n  runtime.sandbox.v1: true\n  plugin.extension.v1: true\n  agent.factory.real: true\n\nskill:\n  sandbox:\n    enabled: true\n    timeout: 30s\n\nstorage:\n  driver: sqlite\n  sqlite:\n    path: ~/.hexclaw/data.db\n```\n\nAll config values support environment variable substitution (`${VAR_NAME}`).\n\n### Feature Flags\n\nv0.4 capabilities are enabled through the `features:` section. Unknown flags always\nresolve to disabled, and `alpha` flags are forced off by default even when their\nregistered default is true.\n\nCommon flags:\n- `agent.factory.real`: allow `dispatch_role` to invoke a real `hexagon.Agent`\n- `skill.pipeline.v1`: enable the 7-phase Skill execution pipeline\n- `interactive.render.v1`: use native platform renderers for interactive replies; disabled uses text fallback\n- `config.tx.hotload.v1`: update LLM config through transactional hot reload\n- `model.gateway.v1`: enable the Provider middleware chain\n- `events.transport.v1`: enable structured event sink delivery\n- `rag.pipeline.v1`: enable the 5-stage knowledge RAG pipeline\n- `voice.tts.chain.v1`: enable chained TTS provider fallback\n\n## Architecture\n\n```\nUser → Platform Adapters (13) → Security Gateway (6 layers) → Agent Router → Agent Engine → LLM Provider\n        │                          │                              │              │               │\n  Web/Feishu/Telegram         Auth→RateLimit→Cost          Multi-Agent       ReAct Loop     DeepSeek/OpenAI\n  Discord/Slack/...           →Safety→RBAC→Audit           Workflow Engine   Skill/MCP      Claude/Qwen/...\n  DingTalk/WeCom/WeChat                                                       Knowledge RAG\n  WhatsApp/LINE/...                                                            Session Fork\n  Matrix/Email\n```\n\n### 6-Layer Security Gateway\n\n| Layer | Name | Function | Failure Policy |\n|:-----:|------|----------|---------------|\n| 1 | Auth | Token/API Key auth with constant-time comparison | Reject |\n| 2 | RateLimit | Sliding window per user/hour (100K window max) | Reject |\n| 3 | CostCheck | User/global monthly budget enforcement | **Fail-closed** |\n| 4 | InputSafety | Prompt injection detection + PII redaction | **Fail-closed** |\n| 5 | Permission | RBAC access control | Reject |\n| 6 | Audit | Request audit logging | Pass (log only) |\n\n\u003e Layers 3/4 reject requests on service errors (fail-closed), rather than silently allowing through. See [SECURITY.md](SECURITY.md).\n\n### Directory Structure\n\n```\nhexclaw/\n├── hexclaw.go               # Root package (version info + package docs)\n├── cmd/\n│   ├── hexclaw/             # CLI entry (serve/init/version/security audit/skill)\n│   └── verify-release/      # Release gate / Eval / canary dry-run verifier\n├── acp/                     # Agent Client Protocol bridge\n├── adapter/                 # Platform adapters\n│   ├── web/                 #   Web WebSocket\n│   ├── feishu/              #   Feishu Bot\n│   ├── telegram/            #   Telegram Bot\n│   ├── dingtalk/            #   DingTalk Bot\n│   ├── discord/             #   Discord Bot\n│   ├── slack/               #   Slack Bot\n│   ├── wecom/               #   WeCom (Enterprise WeChat)\n│   ├── wechat/              #   WeChat Official Account\n│   ├── whatsapp/            #   WhatsApp\n│   ├── whauth/              #   WhatsApp signature helper\n│   ├── line/                #   LINE\n│   ├── matrix/              #   Matrix\n│   └── email/               #   Email (IMAP/SMTP)\n├── agents/                  # Agent roles (6 preset roles) + dispatcher/factory/team\n├── api/                     # REST API server\n│   ├── server.go            #   Core server + chat + route registration\n│   ├── handler_config.go    #   LLM config query/update/test/model discovery API\n│   ├── handler_capabilities.go # Model tool-call capability probe API\n│   ├── handler_extended.go  #   Workflow/config/version/stats API\n│   ├── handler_logs.go      #   Log query/stats/stream API\n│   ├── handler_knowledge.go #   Knowledge base API\n│   ├── handler_webhook.go   #   Webhook API\n│   ├── handler_cron.go      #   Cron job API\n│   ├── handler_cronjob_unified.go # Unified cron entrypoint (POST /cronjob)\n│   ├── handler_voicechat.go #   Voice STT/TTS + voicechat API\n│   └── handler_misc.go      #   Memory/MCP/skill/router/canvas API\n├── audit/                   # Security audit (7 check categories)\n├── canvas/                  # Canvas/A2UI (8 component types)\n├── config/                  # Configuration management (YAML + env vars)\n├── cron/                    # Cron job scheduler\n├── desktop/                 # Desktop integration (notifications/clipboard)\n├── engine/                  # Agent engine (ReAct loop)\n├── eval/                    # Pre-release eval suites\n├── featureflag/             # Feature flag registry and runtime lookup\n├── gateway/                 # 6-layer security gateway\n│   └── llmcall/             #   LLM call gateway (middleware chain)\n├── heartbeat/               # Heartbeat patrol\n├── instances/               # Platform instance lifecycle manager\n├── internal/                # Internal utils (sqliteutil / upstreamerr / testutil)\n├── knowledge/               # Knowledge base (FTS5 + vector hybrid)\n├── llmrouter/               # LLM smart router\n├── mcp/                     # MCP client (stdio + SSE)\n├── memory/                  # File memory (MEMORY.md + journal)\n├── plugin/                  # Plugin Manifest / Capability extensions\n├── release/                 # Release gates and canary state machine\n├── render/                  # Markdown/document rendering (pandoc + LRU cache)\n├── router/                  # Multi-agent router\n├── runtime/                 # Runtime sandbox and checkpoint rollback\n├── security/                # Injection scan / content sanitize / skill scanner\n├── session/                 # Session management + context compaction\n├── skill/                   # Skill system\n│   ├── builtin/             #   Built-in skills (search/weather/translate/summary/media-gen/messaging/export, ...)\n│   ├── chain/               #   Skill pipeline chain\n│   ├── hub/                 #   Online skill catalog (hexclaw-hub)\n│   ├── marketplace/         #   Markdown skill marketplace\n│   └── sandbox/             #   Skill sandboxed execution\n├── storage/                 # Data storage\n│   ├── migrate/             #   Migrations\n│   └── sqlite/              #   SQLite driver\n├── streamstate/             # Streaming state registry\n├── webhook/                 # Webhook receiver\n├── go.mod\n└── Makefile\n```\n\n\u003e Base capabilities such as media generation/genstore/SSRF/cache/trace/events have been pushed down into ai-core / toolkit / hexagon; hexclaw no longer keeps local equivalents. Voice STT/TTS is handled inline by `api/` and `gateway/`, with no standalone `voice/` package.\n\n## API Endpoints (selected endpoints; full routing is module-dependent)\n\n### Core\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/health` | Health check |\n| POST | `/api/v1/chat` | Chat (streaming/sync, role selection) |\n| GET | `/api/v1/roles` | Role list |\n| GET | `/api/v1/version` | Version info |\n| GET | `/api/v1/stats` | System statistics |\n| GET | `/api/v1/models` | Configured LLM models |\n\n### Session Management\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/sessions` | Session list |\n| GET | `/api/v1/sessions/{id}` | Session details |\n| DELETE | `/api/v1/sessions/{id}` | Delete session |\n| GET | `/api/v1/sessions/{id}/messages` | Message history |\n| GET | `/api/v1/sessions/{id}/branches` | Session branch list |\n| POST | `/api/v1/sessions/{id}/fork` | Fork conversation |\n| GET | `/api/v1/messages/search` | Full-text message search |\n\n### Configuration\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/config` | Get full config (API keys masked) |\n| PUT | `/api/v1/config` | Update config |\n| GET | `/api/v1/config/llm` | Get LLM config |\n| PUT | `/api/v1/config/llm` | Update LLM config |\n| POST | `/api/v1/config/llm/test` | Test one provider config without persisting it; local Ollama may omit the key |\n| POST | `/api/v1/config/llm/models` | Dynamically fetch available models from a provider (proxies to provider `/models` API) |\n| GET | `/api/v1/llm/capabilities` | List cached model tool-call capability probe results |\n| POST | `/api/v1/llm/capabilities/probe` | Probe the tool-call reliability for a given `provider` + `model` |\n\n### Knowledge Base\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | `/api/v1/knowledge/documents` | Upload document |\n| POST | `/api/v1/knowledge/upload` | Upload file and return indexing result |\n| GET | `/api/v1/knowledge/documents` | Document list |\n| GET | `/api/v1/knowledge/documents/{id}` | Single document detail with full content |\n| DELETE | `/api/v1/knowledge/documents/{id}` | Delete document |\n| POST | `/api/v1/knowledge/documents/{id}/reindex` | Reindex/retry one document |\n| POST | `/api/v1/knowledge/search` | Structured search — both `result` and `results` return `[]SearchHit` with chunks, sources, and scores |\n\n### Cron Jobs\nThe unified entrypoint `POST /api/v1/cronjob` dispatches on the request body's `action` field (`create` / `update` / `remove` / `pause` / `resume` / `run` / `list` / `history`) and supports `idempotency_key` replay.\n\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | `/api/v1/cronjob` | Unified cron entrypoint (dispatches CRUD / pause-resume / manual trigger / list / history by `action`) |\n| POST | `/api/v1/cron/jobs/stream` | Create job (SSE streaming compile, pushes progress/done/error) |\n| POST | `/api/v1/cron/parse` | Parse/validate a cron expression and return the next run time |\n| GET | `/api/v1/cron/jobs/{id}/history` | Execution history (each entry includes a `result` summary) |\n\n### Webhooks\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | `/api/v1/webhooks/{name}` | Receive webhook event |\n| GET | `/api/v1/webhooks` | List webhooks |\n| POST | `/api/v1/webhooks` | Register webhook |\n| DELETE | `/api/v1/webhooks/{name}` | Delete webhook |\n\n### Memory\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/memory` | Get memory |\n| POST | `/api/v1/memory` | Create memory |\n| PUT | `/api/v1/memory` | Update memory (allows clearing) |\n| DELETE | `/api/v1/memory` | Clear all memory |\n| DELETE | `/api/v1/memory/{id}` | Delete specific memory |\n| GET | `/api/v1/memory/search` | Search memory |\n\n### MCP\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/mcp/tools` | Tool list |\n| GET | `/api/v1/mcp/servers` | Server list |\n| GET | `/api/v1/mcp/status` | Connection status snapshot |\n| POST | `/api/v1/mcp/tools/call` | Call tool |\n\n### Skills\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/skills` | Installed skills |\n| PUT | `/api/v1/skills/{name}/status` | Enable/disable a skill with runtime status fields |\n| POST | `/api/v1/skills/install` | Install skill from `clawhub://name` or a local relative path |\n| DELETE | `/api/v1/skills/{name}` | Uninstall skill |\n| GET | `/api/v1/clawhub/search` | ClawHub skill search with `q` / `category` filters |\n\nDefault skill catalog repo: `https://github.com/hexagon-codes/hexclaw-hub` (`index.json` + `skills/*.md`).\nInstalling or uninstalling Markdown skills automatically syncs the runtime skill registry; a sidecar restart is usually unnecessary.\n\n### Agent Routing\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/agents` | Agent list |\n| POST | `/api/v1/agents` | Register agent |\n| PUT | `/api/v1/agents/{name}` | Update agent |\n| DELETE | `/api/v1/agents/{name}` | Delete agent |\n| POST | `/api/v1/agents/default` | Set default agent |\n| GET | `/api/v1/agents/rules` | List routing rules |\n| POST | `/api/v1/agents/rules` | Create routing rule |\n| POST | `/api/v1/agents/rules/test` | Test routing and return matched rules |\n| DELETE | `/api/v1/agents/rules/{id}` | Delete routing rule |\n\n### Platform Instances / IM Channels\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/platforms/instances` | Platform instance list |\n| GET | `/api/v1/platforms/instances/health` | Health of all instances |\n| POST | `/api/v1/platforms/instances` | Create instance |\n| PUT | `/api/v1/platforms/instances/{name}` | Update instance |\n| DELETE | `/api/v1/platforms/instances/{name}` | Delete instance |\n| GET | `/api/v1/platforms/instances/{name}/health` | Health of one instance |\n| POST | `/api/v1/platforms/instances/{name}/test` | Test instance config |\n| POST | `/api/v1/platforms/instances/{name}/start` | Start instance |\n| POST | `/api/v1/platforms/instances/{name}/stop` | Stop instance |\n| POST | `/api/v1/im/channels/{provider}/test` | Test IM channel config |\n\n### Canvas / Workflow\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/canvas/panels` | Panel list |\n| GET | `/api/v1/canvas/panels/{id}` | Panel details |\n| POST | `/api/v1/canvas/events` | Push event |\n| GET | `/api/v1/canvas/workflows` | Workflow list |\n| POST | `/api/v1/canvas/workflows` | Save workflow |\n| DELETE | `/api/v1/canvas/workflows/{id}` | Delete workflow |\n| POST | `/api/v1/canvas/workflows/{id}/run` | Run workflow async |\n| GET | `/api/v1/canvas/runs/{id}` | Query run result |\n\n### Voice\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/voice/status` | Voice service status |\n| POST | `/api/v1/voice/transcribe` | Speech-to-text (STT) |\n| POST | `/api/v1/voice/synthesize` | Text-to-speech (TTS) |\n\n### Desktop Integration\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/desktop/info` | Desktop environment info |\n| GET | `/api/v1/desktop/notifications` | Notification list |\n| POST | `/api/v1/desktop/notifications` | Send notification |\n| DELETE | `/api/v1/desktop/notifications` | Clear notifications |\n| GET | `/api/v1/desktop/clipboard` | Read clipboard |\n| POST | `/api/v1/desktop/clipboard` | Write clipboard |\n\n### Team Collaboration\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/team/agents` | List shared team agents |\n| POST | `/api/v1/team/agents` | Share an agent with the team |\n| DELETE | `/api/v1/team/agents/{id}` | Delete shared agent |\n| GET | `/api/v1/team/members` | Team member list |\n| POST | `/api/v1/team/members` | Invite member |\n| DELETE | `/api/v1/team/members/{id}` | Remove member |\n\n### Logs \u0026 Monitoring\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/logs` | Query logs (level/source/domain/keyword filter + pagination) |\n| GET | `/api/v1/logs/stats` | Log statistics (count by level/source) |\n| GET | `/api/v1/logs/stream` | Real-time log stream (WebSocket, requires token auth) |\n\n### Desktop-Aligned Response Semantics\n\n- `POST /api/v1/config/llm/test` returns `ok`, `message`, `provider`, `model`, and `latency_ms`; when `provider.type=ollama`, `api_key` may be empty for local OpenAI-compatible connectivity checks.\n- `GET /api/v1/skills` always returns `enabled`; `PUT /api/v1/skills/{name}/status` additionally returns `effective_enabled`, `requires_restart`, and `message`.\n- `POST /api/v1/skills/install` accepts `clawhub://skill-name` and local relative paths; on success it returns `requires_restart=false` and `runtime_registered=true`, meaning the runtime engine has already hot-synced.\n- `GET /api/v1/cron/jobs/{id}/history` includes `result` in each history entry so the latest execution output summary can be shown directly.\n- `POST /api/v1/knowledge/search` returns structured chunk results (both `result` and `results` fields are now `[]SearchHit`) with document title, source, chunk position, content, and similarity score so the UI can show citations directly. `result` is no longer a concatenated plain string.\n- `GET /api/v1/knowledge/documents/{id}` returns a single document with its full content.\n- `GET /api/v1/knowledge/documents` includes `status`, `error_message`, `updated_at`, and `source_type`; `POST /api/v1/knowledge/upload` returns `status`, `source`, `chunk_count`, and `warnings`.\n- `POST /api/v1/agents/rules/test` returns matched rules and scores so the UI can explain why a request was routed to a given agent.\n- Log entries returned by `GET /api/v1/logs` include a stable `domain` field for filtering by functional area such as `chat`, `knowledge`, `integration`, `automation`, or `engine`.\n- `POST /api/v1/config/llm/models` proxies to a provider's `/models` endpoint and returns a normalized model list (`{ models: [{ id, name }] }`); auto-adapts between OpenAI standard format and alternative formats.\n- `GET /api/v1/llm/capabilities` returns `{ provider_name, model_name, tool_call, tool_call_text, last_probe, probe_error }`; `POST /api/v1/llm/capabilities/probe?provider=X\u0026model=Y` probes immediately and writes the SQLite cache.\n\n## Development\n\n### Prerequisites\n\n| Tool | Version |\n|------|---------|\n| Go | \u003e= 1.25.7 |\n| golangci-lint | Latest (optional) |\n\n### Make Commands\n\n| Command | Description |\n|---------|-------------|\n| `make build` | Build binary to `bin/` |\n| `make run` | Build and start service |\n| `make test` | Run all tests |\n| `make test-cover` | Run tests with coverage |\n| `make fmt` | Format code |\n| `make vet` | Static analysis |\n| `make lint` | golangci-lint check |\n| `make clean` | Clean build artifacts |\n| `make init` | Initialize default config |\n\n### Manual Commands\n\n```bash\n# Release/CI-mode compile check (prevents local go.work from masking unpublished dependency APIs)\nGOWORK=off go test ./... -run '^$'\n\n# Build\ngo build ./...\n\n# Run tests (the runner-integrity probe is skipped by default; set HEXCLAW_RUNNER_PROBE=1 for manual proof)\ngo test ./...\n\n# Run specific test\ngo test -run TestName ./package/\n\n# Code check\ngo vet ./...\ngolangci-lint run\n\n# Release gate + Eval + canary dry-run\ngo run ./cmd/verify-release -repo . -version 0.4.4 -version-files package.json\n```\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|-----------|\n| Language | Go 1.25.7+ |\n| Agent Framework | [Hexagon](https://github.com/hexagon-codes/hexagon) v0.5.8 |\n| AI Core Library | [ai-core](https://github.com/hexagon-codes/ai-core) v0.2.0 |\n| Utility Library | [toolkit](https://github.com/hexagon-codes/toolkit) v0.2.6 |\n| CLI | [Cobra](https://github.com/spf13/cobra) |\n| Configuration | YAML + environment variables |\n| Storage | SQLite (modernc.org/sqlite) |\n| WebSocket | nhooyr.io/websocket + gorilla/websocket |\n| MCP | modelcontextprotocol/go-sdk v1.5.0 |\n| Security | Hexagon Guard Chain |\n\n## Contributing\n\n### Workflow\n\n1. Fork this repository\n2. Create a feature branch: `git checkout -b feat/your-feature`\n3. Commit your changes: `git commit -m \"feat: add new feature\"`\n4. Push the branch: `git push origin feat/your-feature`\n5. Create a Pull Request\n\n### Commit Message Format\n\nFollow [Conventional Commits](https://www.conventionalcommits.org/):\n\n```\nfeat: add new feature\nfix: fix a bug\ndocs: update documentation\nrefactor: code refactoring\ntest: add tests\nchore: build/toolchain updates\n```\n\n### Code Standards\n\n- Format: `make fmt`\n- Static check: `make vet`\n- Lint: `make lint`\n- Ensure `make test` passes before committing; the intentionally failing runner-integrity probe must be default-skipped or run only in a dedicated/manual workflow before default full-suite CI can be green.\n\n## Related Projects\n\n| Project | Description | Repository |\n|---------|-------------|------------|\n| **Hexagon** | Go AI Agent framework (core engine) v0.5.8 | [hexagon](https://github.com/hexagon-codes/hexagon) |\n| **ai-core** | AI core library (LLM/Tool/Memory) v0.2.0 | [ai-core](https://github.com/hexagon-codes/ai-core) |\n| **toolkit** | Go utility library v0.2.6 | [toolkit](https://github.com/hexagon-codes/toolkit) |\n| **hexagon-ui** | Hexagon Dev UI dashboard (Vue 3) | [hexagon-ui](https://github.com/hexagon-codes/hexagon-ui) |\n| **hexclaw-desktop** | HexClaw desktop client (Tauri + Vue 3) | [hexclaw-desktop](https://github.com/hexagon-codes/hexclaw-desktop) |\n| **hexclaw-ui** | HexClaw web frontend (Vue 3) | [hexclaw-ui](https://github.com/hexagon-codes/hexclaw-ui) |\n\n## Changelog\n\n### Unreleased\n\n**Dependencies \u0026 CI/CD**\n- **Framework dependency upgrade** — `go.mod` now targets hexagon v0.5.8 / ai-core v0.2.0 / toolkit v0.2.6 and Go 1.25.7. `GOWORK=off go test ./... -run '^$'` passes, so release/CI-mode compilation no longer depends on local workspace-only dependency APIs.\n- **CI/CD verification notes** — Recent GitHub Actions runs are green, and this branch currently has no PR/run. The new `sandbox-code-exec.yml` workflow is not registered until it lands on the default branch. The runner-integrity probe is skipped by default and only runs when `HEXCLAW_RUNNER_PROBE=1`; `GOWORK=off go test ./... -count=1` passes.\n\n### v0.4.4\n\n**New Features**\n- **At-rest credential encryption** — Platform credentials are sealed on disk with AES-256-GCM (`enc:v1:` envelope, 0600 master key); legacy plaintext rows read back transparently and are backfilled on next write\n- **Prompt-injection scan** — Defense-in-depth scanner at cron-create (strict) and exec assembly time; exfiltration/obfuscation families always strict, instruction-override relaxed only when skills/RAG data are present\n- **Unified permission gate (GA)** — Declarative `PermissionPolicy` is now the single tool-authorization gate; unattended dispatch uses the `security.autonomy` profile + explicit matrix\n- **Skill tool palette** — New `export_document` / `knowledge_ingest` / `media_generate` / `send_message` builtin skills\n- **Library memory** — Lightweight prompt/memory store injected per turn\n\n**Dependencies \u0026 Architecture**\n- **Framework upgrade** — Upgraded to hexagon v0.5.1 / ai-core v0.1.6 / toolkit v0.2.0 (go.mod toolchain line removed, Go 1.25.5); upstream bug fixes (lossless `streamx` timeout, `runtime/runner` tool-call pairing, `failover` classification). The toolkit `crypto/sign` `APISigner` wire-format BREAKING change does not affect hexclaw (only `HMACSHA256` primitives are used)\n- **Capability push-down** — Media generation/genstore/SSRF/cache/trace/events migrated into ai-core/toolkit/hexagon; gateway HMAC now uses `toolkit/crypto/sign`\n- **Failover push-down** — LLM failover logic moved into ai-core/llm; hexclaw removed its local equivalent and call sites now use `llm.*`\n- **Sandbox migration** — The Skill sandbox package moved from the top-level `sandbox/` to `skill/sandbox/`\n\n**Bug Fixes**\n- **Matrix adapter** — Idempotent Stop, eliminating the double close(closed channel) panic\n- **Knowledge time decay** — Zero-value CreatedAt is no longer decayed to zero (fixes chunks without timestamps never being recalled)\n- **Cron multi-replica** — Atomic DB claim + fencing prevents double-running jobs across replicas; fail-open preserves pure in-memory behavior\n- **Security hardening** — SSRF allows loopback only (blocks metadata and intranet addresses); file-op symlink boundary protection; WhatsApp webhook signature verification + constant-time comparison for WeChat/WeCom; shell now follows the function-first execution model\n- **Function-first unattended automation matrix** — Default `function_first` auto-approves core automation such as `code_exec`, shell, file edits, browsing, knowledge ingest, and delivery. Skill/MCP management, publishing, and forgeable `solve` sources are not auto-approved by default; enable them explicitly through `security.autonomy` or `full_access`. Explicit `PermissionPolicy` deny rules still enforce operator hard limits\n- **SSRF reserved ranges (BUG-F4)** — cron Starlark `http_*` now also blocks RFC6598 CGNAT `100.64.0.0/10`, `192.0.0.0/24`, `198.18.0.0/15` (incl. IPv4-mapped IPv6 forms)\n\n### v0.4.0\n\n**New Features**\n- **Feature flag foundation** — The `features:` config section controls rollout-capable features; product features default on, while unknown flags are treated as config mistakes and stay off\n- **Model capability probing** — New `/api/v1/llm/capabilities` and `/probe` endpoints cache model tool-call reliability\n- **Skill lifecycle loop** — Adds the 7-phase Pipeline, `skill_view` progressive disclosure, `.pending` approvals, TrustLevel filtering, and TOCTOU protection\n- **Interactive replies** — `Reply.Interactive` supports buttons/select/approval/card with IM text fallback\n- **Runtime governance** — Adds Provider middleware, structured events, permission policies, MCP lifecycle hooks, RAG Pipeline, Runtime Sandbox, and release gates\n- **Voice improvements** — Adds MiniMax TTS and chained multi-provider TTS fallback\n\n### v0.3.0\n\n**New Features**\n- **Dynamic Model Discovery** — New `POST /api/v1/config/llm/models` endpoint that proxies to a provider's `/models` API for dynamic model listing. Supports both OpenAI format (`{ data: [...] }`) and alternative format (`{ models: [...] }`)\n- **MCP `~` Path Expansion** — `~` and `~/subpath` in MCP server args are now automatically expanded to the user's home directory, cross-platform via `os.UserHomeDir()` (macOS/Linux/Windows)\n\n**Bug Fixes**\n- **Feishu Thinking Placeholder** — The Feishu adapter now sends a thinking placeholder message (e.g., \"🤔 Thinking...\") immediately upon receiving a message, then replaces it with the final reply via `patchMessage`. Both SDK (WebSocket) and Webhook paths are covered\n- **Streaming Tool Execution Fix** — `ProcessStream` with tools previously used `pipeStreamWithTools` which did not execute tools. Fixed to use `processStreamToolLoop` which performs full tool execution → feed results → continue LLM reasoning loop\n- **Reasoning Content Persistence** — `pipeStream` and `pipeStreamWithTools` streamed reasoning/thinking content to the frontend but did not collect it for persistence. Added `fullReasoning` collection and new `SaveAssistantMessageWithMeta()` method that saves reasoning to message metadata JSON\n\n## Contact\n\n- HexClaw AI: ai@hexclaw.net\n- HexClaw Support: support@hexclaw.net\n- Issues: [GitHub Issues](https://github.com/hexagon-codes/hexclaw/issues)\n- Security vulnerabilities: see [SECURITY.md](SECURITY.md)\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexagon-codes%2Fhexclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexagon-codes%2Fhexclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexagon-codes%2Fhexclaw/lists"}