Skip to content

README.md

Latest commit

 

History

History
332 lines (323 loc) · 20.6 KB

README.md

File metadata and controls

332 lines (323 loc) · 20.6 KB
Raw
title HybridClaw Docs
description User, operator, and developer documentation for HybridClaw installation, channels, workflows, extensibility, and runtime internals.
sidebar_position 1

HybridClaw Docs

Welcome to the HybridClaw handbook — the operator, contributor, and advanced-user manual for running, extending, and understanding HybridClaw. The chapters are organized around what you are trying to do rather than how the repository is laid out. Getting Started walks through installation, onboarding, and your first run. Channels is the transport reference across Discord, Slack, Telegram, Signal, Threema, email, WhatsApp, iMessage, and Microsoft Teams. Guides collects task-focused walkthroughs for everyday operational work, Tutorials provides practical owner, GTM, marketing, sales, and community workflows, Extensibility covers tools, skills, plugins, and the extension architecture, and the Developer Guide goes deeper into architecture and maintainer-facing internals. When you just need a fact — a command, a config key, a diagnostic — Reference is the place to land.

Every page in the browser docs shell keeps its raw .md source one click away: open it directly from the header, or copy the full page markdown for sharing and quoting. If you prefer a single markdown index that links every doc at once, start from For Agents.

Latest Highlights

  • HybridClaw v0.28.4 keeps conversation prefixes cache-stable across turns and tool loops by separating static instructions, workspace memory, skills, and turn-local context while preserving complete retained messages.
  • The console shows a short What's New dialog once per release, makes grouped admin tabs searchable from the command palette, and applies shared components and visual contracts consistently across admin workflows.
  • Microsoft Teams setup in Channels includes encrypted app-password storage, complete readiness status, end-to-end Entra and tunnel guidance, and a manifest icon that remains visible in the Teams app rail.
  • Security hardening pins policy-checked browser proxy addresses, validates filesystem and hostname boundaries, avoids leaking internal channel errors, and strengthens non-secret fingerprints. Shell approvals preserve heredoc boundaries, web fetches enforce a shared deadline, and inline PDF previews work under the console CSP.
  • Age-eligible dependency updates refresh pinned packages, remove stale workspace lock entries, scope Electron's newer HTTP client override, and keep third-party notices and signature audits aligned with every component.
  • HybridClaw v0.28.3 adds deterministic model-tier routing for unpinned turns: agents can start on a configured rung, system work starts at the lowest rung, retry-safe provider and output failures escalate with audit telemetry, successful escalation stays sticky, and /escalate raises one upcoming turn without overriding explicit model pins. Named local endpoints can also declare privacy zones and EUR-denominated input/output pricing.
  • The admin console groups related work into Activity, Agents, Automation, Federation, Credentials, and Extensions tabs. Page and setting search opens from the sidebar or Cmd/Ctrl+K, links each result to its exact field or canonical owner, and keeps provider configuration with provider health.
  • Paired HybridClaw gateways pin X25519 keys and protect A2A envelopes with signed, compact JWE payloads. Operators can also require encryption for every trust entry to prevent plaintext interoperability fallbacks.
  • Direct openai/... models use the OpenAI Responses API with encrypted key storage, streaming, tools, and encrypted reasoning replay, while Codex OAuth remains under openai-codex/... and recognises the 5.6 Sol, Terra, and Luna model line.
  • The model latency benchmark compares gateway, HybridAI, and direct Anthropic or OpenAI paths with streaming on and off, connection timing, prompt-cache visibility, multi-provider gateway arms, long prompt files, and optional raw JSON output.
  • WhatsApp is released from a separate GPL repository and installed only on demand, keeping Baileys and its GPL dependency outside core distributions. The core dependency tree is AGPL-free, and dependency policy rejects unapproved GPL, AGPL, and SSPL packages.
  • Release artifacts include MIT package metadata, comprehensive third-party notices, per-component CycloneDX and SPDX SBOMs, DCO enforcement, and a public code-provenance statement covering authorship and the project's independent relationship to OpenClaw.
  • Cloud gateway and standalone sandbox images carry the Python and XLSX tools needed for spreadsheet work. Version-related prompts reach the agent, agent archive migrations avoid the schema-52 collision, generated settings use portable home paths, and release metadata generators ignore dot-directory worktrees.
  • Secret existence checks use secret status rather than the misleading secret show spelling and continue to return metadata without decrypting or displaying stored values.
  • HybridClaw v0.28.2 adds A2A local mode for keeping peer Agent Card and delivery routes reachable while disabling unrelated external chat, APIs, webhooks, channel runtimes, and channel delivery; tunnel configuration and lifecycle controls move to a dedicated admin surface.
  • Google Workspace authorization from a local console or the desktop app uses the Desktop-client loopback flow, while LAN, tunnel, and public consoles use a Web client and display the exact server-computed callback URI to register.
  • Provider replies stream live to clients without replaying final text or retrying after visible partial output, and HybridAI cumulative/delta chunks no longer duplicate content.
  • Turns for the same session are serialized across gateway, host, and container execution while interactive input preempts active full-auto work before the queue; WhatsApp also records outbound chunks early enough to stop self-chat echoes from starting new turns.
  • In-loop compaction keeps tool calls paired with every result, direct Anthropic and Ollama client-tool requests use their correct compatible payloads and endpoints, and direct Anthropic streams have no fixed total-duration cap.
  • Trace exports bind completed audit turns to their exact stored assistant messages, local providers stay disabled until configured, and unused Codex health warnings no longer clutter gateway status.
  • Microsoft Teams credentials set or rotated in /admin/credentials?tab=secrets refresh the running adapter without a restart, and Chrome can render inline PDF artifact previews without relaxing the blob's fixed PDF content type.
  • Internal architecture docs specify a configurable model-tier ladder, deterministic escalation, privacy zones, quality/speed targeting, auditable savings, phased delivery gates, and a sovereign HybridRouter fine-tuning roadmap. The SSO and per-user identity design covers trusted-proxy and OIDC login, IdP group-to-role mapping, per-user sessions, and per-agent ACLs.
  • HybridClaw v0.28.1 adds an explicitly warned unofficial LINE personal-account channel scoped to Keep Memo self-chat, with QR/PIN setup, persistent encrypted-message state, self-only inbound and outbound checks, and admin-console pairing status.
  • Anthropic thinking blocks survive direct and HybridAI-routed streaming tool continuations so web chat can render complete activity traces.
  • Channel replies enforce hard character and line limits while preserving Unicode and fenced code, and duplicate Discord updates, Slack event twins, and WhatsApp LID sender aliases no longer start duplicate or misidentified turns.
  • First-run onboarding openers remain visible through assistant-only session cleanup and retry after temporary provider failures, while auxiliary calls retain explicit output-token caps and npm self-updates install production dependencies with quieter output.
  • HybridClaw v0.28.0 dispatches trusted inbound A2A messages to local agents, sends replies back across reverse trust, and shows delivery status in the origin chat until the remote reply is stored.
  • Scoped gateway API tokens can be managed from hybridclaw token or /admin/credentials?tab=api-tokens, with one-time reveal, expiry timestamps, explicit actions/scopes/roles, metadata-only listing, revocation, and audit events.
  • Delegated OpenAI-compatible chat completions expose delegation metadata and can be polled at GET /v1/chat/completions/{completion-id} until queued work completes, fails, or is cancelled.
  • Apps can be published as scoped sharing links, optional password-protected links, or Microsoft Teams tabs with Entra SSO viewer validation and revocation controls.
  • Public docs include an A2A peer-pairing walkthrough and local two-instance smoke test for trusted remote-agent chat and reply delivery.
  • Runtime config watching is scoped to the gateway process and falls back to descriptor-free stat polling when fs.watch cannot be maintained.
  • HybridClaw v0.27.1 records first-run hatching as structured onboarding audit events, including start/continue, quick messages, user and assistant turns, welcome mail, workspace file updates, completion, and abort paths.
  • /admin/activity?tab=audit treats onboarding as a first-class event category so operators can search and filter bootstrap hatching activity without reading raw audit files.
  • Web chat keeps interim assistant and tool-turn activity visible while a run is active, collapses completed tool turns into the activity trace, and keeps non-final assistant drafts out of persisted chat history.
  • Tool progress traces retain complete progress output for activity rendering while masking and capping retained previews, and email mailbox polling refreshes status before searching so stale UID state does not block new mail.
  • Web chat renders thinking and tool calls as a light-grey, collapsible activity trace above each answer, streams it while a run is active, and persists the ordered trace so reloads keep the same activity history.
  • The Apps gallery at /apps stores generated HTML apps, websites, documents, games, quizzes, and productivity tools from app-build chat sessions, with category filtering, search, previews, new-tab links, and deletion.
  • Web chat /app <description> starts a plan-first app-building conversation and captures the resulting file-backed or inline HTML artifact into the Apps gallery.
  • Live apps can refresh connector data inside the Apps viewer through a sandbox bridge for read-only MCP connector tool calls while keeping an embedded snapshot fallback.
  • OpenAI Codex streams use an idle timeout so a stalled SSE connection fails cleanly instead of hanging a turn indefinitely.
  • HybridClaw v0.25.8 uses configured public deployment URLs for cloud MCP OAuth callbacks, admin origin checks, and mobile chat QR links when requests arrive through internal hosts.
  • HybridClaw v0.25.8 autosaves default email allowed-sender additions as soon as admins click Add.
  • Email channel advanced settings are collapsed by default so additional mailboxes stay easier to scan while lower-frequency options remain available.
  • HybridClaw v0.25.7 uses a conversational first-run hatching flow with a natural email ask for the welcome note and shorter setup prompts.
  • Web chat keeps new no-user drafts concrete, prunes older empty or assistant-only drafts, and preserves sessions that already have user messages.
  • Admin channel settings expose sender allowlist editors for WhatsApp, Telegram, Threema, Signal, email, Microsoft Teams, Slack, and iMessage, with wildcard confirmation for all-sender entries.
  • Gateway session timestamps render in the local timezone without seconds or a UTC suffix.
  • Doctor resource hygiene reports stale histories with no user messages as unstarted sessions and can clean up those empty or assistant-only rows.
  • The bundled Langfuse skill covers LLM observability and evaluation workflows through guarded gateway-proxied tools.
  • The Apple desktop wrapper records gateway startup logs and recent child output so packaged app launch failures are easier to diagnose.
  • A2A Agent Cards advertise the configured public deployment URL and fail closed when that URL is invalid.
  • Dependency maintenance remediates npm audit findings, upgrades Nodemailer to 9.0.0, and documents the lockfile update workflow.
  • MCP startup tolerates one failing server without aborting the whole chat turn, and workspace bootstrap skips empty heartbeat defaults.
  • First-run hatching can use a dedicated model, keeps setup links visible in chat, records first-job ideas, sends the welcome email when an email route is available, and avoids duplicate bootstrap starts.
  • Remote MCP servers can use gateway-managed OAuth 2.1 with guided setup in the TUI and web console, encrypted token storage, automatic refresh, and /mcp login|logout|status commands.
  • Admin skill detail pages show docs, prompts, dependencies, logos, credential status, recent invocations, enable controls, example prompt launchers, and a guarded package text-file editor.
  • Built-in email supports per-agent mailboxes through email.accounts[], so inbound threads and outbound replies stay tied to the right agent address.
  • The agent-risk eval gate covers top-level NIST AI RMF, NIST AI 600-1, and OWASP LLM Top 10 2025 scenarios with redacted evidence artifacts.
  • Admin RBAC role bundles, route-level scoped action enforcement, ISO/IEC 27001 evidence docs, ISO/IEC 42001 readiness docs, SBOM/provenance attestations, CodeQL, and secret scanning improve governance evidence.
  • The bundled posthog business skill covers guarded event capture, person-property updates, feature flag reads/tests, and HogQL reads.
  • sessions prune --older-than <duration> gives operators an auditable, dry-run-first way to clean old persisted session history.
  • HybridAI Cloud launches hosted HybridClaw environments from hybridclaw.io when teams want the fastest managed path instead of preparing local infrastructure first.
  • Multi-agent workflows span local agents, hosted HybridAI proxy agents, and trusted peer HybridClaw instances through explicit addressing, A2A pairing, inbound envelopes, and admin-visible trust.
  • Encrypted runtime secrets and SecretRefs keep raw credentials out of model context; tools receive scoped credential material at execution time instead of asking the LLM to handle API keys or passwords.
  • Native image_generate and video_generate tools produce managed media artifacts through configured image and video providers.
  • Bundled skills cover Airtable, FastBill, Firecrawl, Fronius, HeyGen, Homematic, Google Ads, and SearXNG-backed web/news/image search workflows.
  • Threema Gateway Basic mode is available for outbound operator messaging in DACH-regulated or privacy-sensitive deployments.
  • A2A federation includes JSON-RPC Agent Card inbound delivery, signed delegation bearer tokens, operator pairing, and a public-key trust ledger.
  • Human distillation turns consented source material into cited coworker-agent personas with reversible merges, leakage/fidelity evals, and multi-host export bundles.
  • Named local endpoints let operators run multiple Ollama, LM Studio, llama.cpp, or vLLM servers side by side, including Qwen and Gemma behavior hints for local models.
  • HybridAI proxy agents forward selected agents to hosted HybridAI chatbots while keeping gateway channel routing and SecretRef-backed upstream auth.
  • Browser automation supports local Playwright profiles, Camofox profiles, and Browser Use Cloud sessions with SecretRef-gated credential fills.
  • Trace-judge eval gates and behavioral anomaly reranking give tool-call and skill-trace review a deterministic test path.
  • Harness evolution runs eval-driven coworker workspace improvement loops with F12 manifests, seed-delta reporting, and admin inspection.
  • /second-opinion compares or validates answers with a stronger configured model while honoring confidentiality, context, and agent-budget limits.
  • Web chat renders slash-command results distinctly and records persisted thumbs-up/down response ratings for observability and Adaptive Skills.
  • npm run desktop launches a native macOS wrapper around the local chat UI, with gateway reuse/startup and admin access from the app menu.
  • Canonical user and agent identity helpers now include DNS-style discovery for mapping remote identities to peer URLs and public keys.
  • Approval policy evaluation runs through a hook-fed rule pipeline that keeps built-in trust behavior while allowing explicit policy ordering and plugin visibility.
  • Web chat session history and active-agent switching are more stable across route changes and resumed sessions.
  • The download-platform-invoices skill harvests official monthly SaaS invoice PDFs and normalized records across billing APIs, browser-backed portals, Google Ads, cloud providers, and DATEV handoff flows.
  • The warehouse-sql skill reviews and runs read-only natural-language SQL against cached warehouse schemas.
  • The mailchimp skill covers Mailchimp Marketing audiences, campaigns, reports, automations, journeys, and Transactional/Mandrill sends with approval-gated writes.
  • Signal joins the channel catalog with a full signal-cli daemon setup guide, private-by-default DM policy, group controls, and admin QR linking.
  • .confidential.yml rules can redact NDA-class business data before model calls, while hybridclaw audit scan-leaks scans historical audit logs for possible leaks.
  • Web chat shows live context-window usage, supports /context, searches recent sessions, and can switch the active agent from the composer.
  • The admin console includes statistics and agent-scoreboard pages for sessions, messages, tokens, cost trends, skill scores, reliability, timing, and CV links.
  • Packaged business skills can declare manifests, capabilities, required credentials, supported channels, lifecycle snapshots, and rollback history.
  • Deployment config can describe cloud/local mode and tunnel provider intent; the built-in ngrok, Tailscale, and Cloudflare providers read runtime auth secrets from encrypted storage.
  • HYBRIDAI_FALLBACK_CHAIN can route auth and rate-limit provider failures to alternate models/providers with primary-provider cooldowns.
  • Model info, usage summaries, and the admin Models page surface discovered context windows, output limits, capabilities, pricing, and monthly spend where providers expose the metadata.
  • Installation options include npm, source checkout, a multi-arch Nix flake, a NixOS module, and a preview Homebrew formula for --HEAD builds.

Browse By Section

  • Manifesto — the product principles HybridClaw is built around: what we will and will not ship
  • Getting Started for installation, onboarding, provider authentication, and connecting the first transport
  • Channels for the full supported channel catalog and transport-specific setup details
  • Guides for generated apps, local providers, MCP, bundled skills, remote access, voice/TTS, and optional office tooling
  • Tutorials for practical owner, GTM, marketing, sales, and community workflows
  • Extensibility for tools, skills, plugins, agent packages, and extension-specific operator workflows
  • Developer Guide for architecture, runtime behavior, session routing, testing, and release mechanics
  • Reference for model selection, configuration, diagnostics, commands, and FAQ

Fast Paths

  • Want the fastest managed launch? Start at hybridclaw.io.
  • Need to install HybridClaw quickly? Go to Installation.
  • Need the shortest path to a running gateway and chat UI? Go to Quick Start.
  • Need to connect one transport without reading the full channel manual? Go to Connect Your First Channel.
  • Need to build a generated app, dashboard, game, or live connector-backed view? Go to Apps Gallery.
  • Need command lookup or troubleshooting help? Go to Commands and Diagnostics.
  • Need setup answers before deploying? Go to FAQ.
  • Need to reach /chat, /apps, /agents, or /admin from another machine? Go to Remote Access.
  • Need one markdown page that links the whole docs tree? Go to For Agents.