@hybridaione/hybridclaw 0.9.8 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,108 @@
 
 ## [Coming up]
 
+## [0.11.0](https://github.com/HybridAIOne/hybridclaw/tree/v0.11.0)
+
+### Added
+
+- **OpenAI-compatible gateway API**: Added loopback-scoped `/v1/models` and
+  `/v1/chat/completions` endpoints so local tools can talk to HybridClaw
+  through an OpenAI-compatible surface with streaming responses and usage
+  reporting.
+- **Workspace approval allowlist controls**: Added a workspace-scoped approval
+  allowlist plus `/approve always` handling so operators can persist trusted
+  approvals more deliberately across chat, TUI, and gateway flows.
+- **Dark-mode console and richer web controls**: Added console dark mode, a
+  reusable dropdown component, extracted icon set, and slash-command
+  suggestions in the web chat UI for faster local operator workflows.
+- **Channel setup how-to documentation**: Added step-by-step channel setup
+  guides for Discord, email, WhatsApp, iMessage, and Microsoft Teams in the
+  maintainer docs.
+- **Release publishing automation**: Added npm publish-on-release automation
+  and switched trusted publishing over to npm OIDC for release workflows.
+
+### Changed
+
+- **Gateway lifecycle behavior**: Improved gateway start, restart, and
+  container replacement flow so runtime refreshes are cleaner, container swap
+  logging is less noisy, and packaged installs prefer public runtime image
+  pulls.
+- **Approval and web chat UX**: Tightened approval wording, aliases, and
+  replay handling while improving mobile chat layout, approval interactions,
+  ordered-list rendering, and keyboard accessibility in the web surfaces.
+- **ClawHub and operator docs surfaces**: Added `CLAWHUB_API_BASE_URL`
+  overrides for skill imports, refreshed docs and setup guidance, and aligned
+  console dark-theme styling with the public documentation shell.
+
+### Fixed
+
+- **Gateway startup and update guidance**: Fixed startup diagnostics, provider
+  auth/model guidance, and post-update restart reminders so operators get more
+  accurate local recovery steps.
+- **Browser and host runtime cleanup**: Fixed browser daemon shutdown handling
+  and host-browser runtime availability so cleanup failures are treated as
+  best-effort instead of breaking the session.
+- **Runtime config and health edge cases**: Fixed config revision
+  synchronization, gateway health payload regressions, favicon fallbacks, and
+  skill import retries under HTTP 429/503 responses.
+
+## [0.10.0](https://github.com/HybridAIOne/hybridclaw/tree/v0.10.0)
+
+### Added
+
+- **OpenClaw and Hermes Agent migration commands**: Added
+  `hybridclaw migrate openclaw` and `hybridclaw migrate hermes` to import
+  compatible workspace files, agent/home config, model settings, and optional
+  secrets into a target HybridClaw agent with `--dry-run`, `--overwrite`,
+  `--agent`, and per-run migration reports under `~/.hybridclaw/migration/`.
+- **Encrypted runtime secret store**: Runtime credentials in
+  `~/.hybridclaw/credentials.json` now use per-secret AES-256-GCM encryption
+  with owner-only permissions, separate master-key sourcing via
+  `HYBRIDCLAW_MASTER_KEY`, `/run/secrets/hybridclaw_master_key`, or a local
+  owner-only `credentials.master.key`, and automatic migration from legacy
+  plaintext secret files.
+- **SecretRefs and named secrets**: Selected runtime config fields can now
+  resolve secret-bearing values from `env` or encrypted `store` references,
+  local TUI and web sessions expose `/secret list|set|unset|show|route ...`,
+  and generic named secrets can be stored without adding new top-level env
+  variables.
+- **Secret-backed HTTP requests**: Added the `http_request` tool plus
+  gateway-side auth injection for direct API calls. Requests can use
+  `bearerSecretName`, `secretHeaders`, strict `<secret:NAME>` placeholders, or
+  URL-based auth rules so models can call authenticated APIs without seeing the
+  plaintext credential.
+- **`llama.cpp` local backend**: Added `llamacpp` as a first-class local
+  provider across `auth login local`, provider discovery, reachability checks,
+  model selection surfaces, doctor output, and container/runtime routing.
+
+### Changed
+
+- **Local-provider onboarding flow**: `hybridclaw auth login local` now accepts
+  an optional model id so operators can enable LM Studio, llama.cpp, Ollama,
+  or vLLM first and choose a model later, and interactive onboarding can skip
+  remote-provider auth entirely when the planned setup is local-only.
+- **Secret access model**: Runtime secret reads now prefer explicit environment
+  overrides and otherwise resolve secrets from the encrypted store on demand
+  instead of broadly mirroring decrypted values into ambient `process.env` at
+  startup.
+- **Secret persistence boundaries**: Reserved non-secret runtime config names
+  such as `CONTAINER_IMAGE`, `CONTAINER_MEMORY`, `DISCORD_PREFIX`, `DB_PATH`,
+  and related operational settings are now excluded from encrypted secret
+  migration and rejected by the local `/secret` command surface.
+- **Security documentation and comparison copy**: Updated the README, public
+  docs, comparison tables, and runtime/internal docs to reflect encrypted
+  secret storage, master-key separation, SecretRef-backed API auth injection,
+  trust-first onboarding, and current runtime security principles.
+
+### Fixed
+
+- **Startup onboarding loops**: Gateway and TUI startup no longer keep
+  re-triggering onboarding once trust acceptance, local-provider setup, or
+  existing credentials already satisfy the runtime prerequisites.
+- **TUI model guidance for local backends**: Model-selection prompts now give
+  clearer next steps when a local backend is enabled without a selected model,
+  reducing dead-end startup guidance around local-only setups.
+
 ## [0.9.8](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.8)
 
 ### Added

package/README.md

@@ -9,18 +9,88 @@
 [![Powered by HybridAI](https://img.shields.io/badge/powered%20by-HybridAI-blueviolet)](https://hybridai.one)
 [![Discord](https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/jsVW4vJw27)
 
-<img width="540" height="511" alt="image" src="docs/hero.png" />
+<img width="540" height="511" alt="HybridClaw - One AI brain across every channel" src="docs/hero.png" />
 
-Personal AI assistant for Discord, Microsoft Teams, iMessage, WhatsApp, email,
-web, and terminal, powered by [HybridAI](https://hybridai.one).
+**One AI brain across every channel.**
+Discord → Teams → WhatsApp → iMessage → Email → Web → Terminal.  
+Same memory, same skills, same intelligence — fully local, encrypted, and GDPR-compliant powered by [HybridAI](https://hybridai.one).
+
+> “Finally an assistant that actually follows you everywhere — without having to explain everything again every time.”
+
+## 🚀 Quick Start (2 minutes)
+
+```bash
+# 1. Global installation
+npm install -g @hybridaione/hybridclaw
+
+# 2. Onboarding (sets up LLM, channels, secrets, everything)
+hybridclaw onboarding
+
+# 3. Start using it
+hybridclaw gateway      # Start the backend
+hybridclaw tui          # Terminal interface (optional)
+```
+
+After that open:
+
+Web Chat: http://127.0.0.1:9090/chat
+Admin Console: http://127.0.0.1:9090/admin
+Agent Dashboard: http://127.0.0.1:9090/agents
+
+Requirement: Node.js 22 (Docker recommended for sandbox)
+
+Release notes live in [CHANGELOG.md](./CHANGELOG.md), and the browsable
+operator and maintainer manual lives under
+[docs/development/README.md](./docs/development/README.md).
+
+## Coming from OpenClaw or Hermes?
+
+```bash
+# Migration in under 2 minutes — preview first
+hybridclaw migrate openclaw --preview
+hybridclaw migrate openclaw          # real migration
+```
+
+All skills, memory, config and secrets are transferred. Zero data loss.
+
+## See it in Action
+
+Once the gateway is running, open HybridClaw locally:
+
+- Web Chat: `http://127.0.0.1:9090/chat`
+- Admin Console: `http://127.0.0.1:9090/admin`
+- Agent Dashboard: `http://127.0.0.1:9090/agents`
+
+## Why HybridClaw instead of OpenClaw, Hermes Agent, LangChain, or n8n?
+
+| Feature | HybridClaw | OpenClaw | Hermes Agent | LangChain | n8n |
+| --- | --- | --- | --- | --- | --- |
+| **One brain across channels** | ✅ Native (Discord, Teams, WhatsApp, iMessage, Email, Web, Terminal) | ✅ 20+ channels | ✅ 7 channels | ❌ Framework only | ⚠️ Via workflows (not native) |
+| **Shared memory & context** | ✅ Persistent across all channels | ✅ Memory-wiki + embeddings | ✅ Self-improving + Honcho model | ✅ (you build it) | ✅ RAG / vector DBs |
+| **Local LLM support** | ✅ Deep integration (Ollama, LM Studio, llama.cpp, vLLM) | ✅ Multiple providers | ✅ Ollama native | ✅ Excellent | ✅ Ollama + others |
+| **Encrypted secrets + SecretRefs** | ✅ Full encrypted store + gateway injection | Partial | Partial | ❌ Manual | Partial |
+| **GDPR / Enterprise-ready** | ✅ Audit trails, sandbox, approvals, config versioning | Limited | Limited | ❌ No | ✅ Strong (workflows) |
+| **Portable `.claw` agent packages** | ✅ Snapshot + backup + install | ❌ | ❌ | ❌ | ❌ |
+| **1-command migration** | ✅ From OpenClaw & Hermes | — | — | — | — |
+| **Multiple UIs** | ✅ TUI + Web Chat + Admin Console + Agent Dashboard | ✅ TUI + WebChat + Control UI | ✅ Full TUI only | ❌ None | ✅ Visual workflow builder |
+| **Self-improving / adaptive skills** | ✅ Adaptive skill loop + health | ✅ ClawHub skills | ✅ Strongest learning loop | ✅ (you code it) | ✅ Via AI nodes |
+| **No-code workflow building** | ✅ CLI + skills + kanban | ⚠️ Skills + ClawHub | ⚠️ Skills Hub | ❌ Code-first | ✅ Best-in-class no-code |
+| **Setup & onboarding** | ✅ `npm install -g` + `onboarding` (2 min) | ✅ Onboard CLI | ✅ One-line curl install | ❌ Requires coding | ✅ Visual + templates |
 
 HybridClaw keeps one assistant brain across team chat, inbox, browser, and
 document workflows with shared memory, approvals, scheduling, and bundled
 skills for office docs, GitHub, Notion, Stripe, WordPress, Google Workspace,
 and Apple apps.
+Runtime secrets live in an encrypted local store with separate master-key
+sourcing, SecretRefs can keep config values out of plaintext JSON, and
+gateway-side auth injection lets the agent call authenticated APIs without
+seeing the raw credential.
 Portable `.claw` packages can snapshot an agent workspace plus bundled skills
 and plugins for transfer or backup, and persistent browser profiles let the
 agent reuse authenticated web sessions for later browser automation.
+OpenClaw and Hermes Agent homes can also be imported into HybridClaw agent
+workspaces with migration commands that preview compatible files, config, and
+optional secrets before writing anything.
 Local plugins can extend the gateway with typed manifests, plugin tools,
 memory layers, prompt hooks, lifecycle hooks, and fixed plugin-owned inbound
 webhook routes, including the installable QMD-backed memory layer shipped in
@@ -38,24 +108,6 @@ config changes auditable and reversible.
 For turn-level debugging, gateway start/restart can also persist best-effort
 redacted prompts, responses, and tool payloads with `--log-requests`.
 
-## Install from npm
-
-```bash
-npm install -g @hybridaione/hybridclaw
-hybridclaw onboarding
-```
-
-Prerequisites: Node.js 22. Docker is recommended when you want the default
-container sandbox. The published install bootstraps the packaged container
-runtime dependencies during `npm install -g`.
-The current release tag is
-[v0.9.8](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.9.8).
-This release adds concierge routing, tracked config revisions, plugin inbound
-webhooks, expanded agent install sources, and the bundled `sokosumi` skill.
-Release notes live in [CHANGELOG.md](./CHANGELOG.md), and the browsable
-operator and maintainer manual lives under
-[docs/development/README.md](./docs/development/README.md).
-
 ## HybridAI Advantage
 
 - Security-focused foundation
@@ -74,56 +126,6 @@ operator and maintainer manual lives under
 - **Container** (Docker, ephemeral) — HybridAI API client, sandboxed tool executor, and preinstalled browser automation runtime with cursor-aware snapshots for JS-heavy custom UI
 - Communication via file-based IPC (input.json / output.json)
 
-## Quick start
-
-```bash
-# Install dependencies
-npm install
-
-# Run onboarding (also auto-runs on first `gateway`/`tui` start if API key is missing)
-hybridclaw onboarding
-
-# Onboarding flow:
-# 1) explicitly accept TRUST_MODEL.md (required)
-# 2) choose whether to create a new account
-# 3) open /register in browser (optional) and confirm in terminal
-# 4) open /login?next=/admin_api_keys in browser and get an API key
-# 5) paste API key (or URL containing it) back into the CLI
-# 6) choose the default bot (saved to ~/.hybridclaw/config.json) and save secrets to ~/.hybridclaw/credentials.json
-
-# Start gateway backend (default)
-hybridclaw gateway
-
-# Or run gateway in foreground in this terminal
-hybridclaw gateway start --foreground
-
-# For stdio MCP servers that rely on host tools like `docker` or `npx`
-hybridclaw gateway start --foreground --sandbox=host
-
-# If msteams.enabled=true and MSTEAMS_APP_PASSWORD is configured, gateway auto-connects to Microsoft Teams.
-# If DISCORD_TOKEN is set, gateway auto-connects to Discord.
-# If imessage.enabled=true, gateway auto-connects to iMessage using the configured backend.
-# If email.enabled=true and EMAIL_PASSWORD is configured, gateway auto-connects to Email.
-# If linked WhatsApp auth exists, gateway auto-connects to WhatsApp.
-
-# Start terminal adapter (optional, in a second terminal)
-hybridclaw tui
-
-# Web chat UI (built into gateway)
-# open http://127.0.0.1:9090/chat
-
-# Agent and session dashboard
-# open http://127.0.0.1:9090/agents
-
-# Embedded admin console
-# open http://127.0.0.1:9090/admin
-# Browser terminal page
-# open http://127.0.0.1:9090/admin/terminal
-# Includes Dashboard, Terminal, Gateway, Sessions, Jobs, Bindings, Models, Scheduler, MCP, Audit, Skills, Plugins, Tools, and Config
-# If WEB_API_TOKEN is unset, localhost access opens without a login prompt
-# If WEB_API_TOKEN is set, /chat, /agents, and /admin all prompt for the same token
-```
-
 ## Authentication
 
 HybridClaw uses a unified provider setup surface:
@@ -135,6 +137,7 @@ hybridclaw auth login codex --import
 hybridclaw auth login openrouter anthropic/claude-sonnet-4 --api-key sk-or-...
 hybridclaw auth login mistral mistral-large-latest --api-key mistral_...
 hybridclaw auth login huggingface meta-llama/Llama-3.1-8B-Instruct --api-key hf_...
+hybridclaw auth login local lmstudio --base-url http://127.0.0.1:1234
 hybridclaw auth login local ollama llama3.2
 hybridclaw auth login msteams --app-id 00000000-0000-0000-0000-000000000000 --tenant-id 11111111-1111-1111-1111-111111111111 --app-password secret
 hybridclaw auth status hybridai
@@ -163,40 +166,78 @@ hybridclaw local configure ollama llama3.2
 ```
 
 - `hybridclaw auth login` without a provider runs the normal onboarding flow.
-- `hybridclaw auth login hybridai` auto-selects browser login on local GUI machines and a manual/headless API-key flow on SSH, CI, and container shells. `--import` copies the current `HYBRIDAI_API_KEY` from your shell into `~/.hybridclaw/credentials.json`, and `--base-url` updates `hybridai.baseUrl` before login.
+- `hybridclaw auth login hybridai` auto-selects browser login on local GUI machines and a manual/headless API-key flow on SSH, CI, and container shells. `--import` copies the current `HYBRIDAI_API_KEY` from your shell into the encrypted `~/.hybridclaw/credentials.json` store, and `--base-url` updates `hybridai.baseUrl` before login.
 - `hybridclaw auth login codex` auto-selects browser PKCE on local GUI machines and device code on headless or remote shells.
 - `hybridclaw auth login openrouter` accepts `--api-key`, falls back to `OPENROUTER_API_KEY`, or prompts you to paste the key, then enables the provider and can set the global default model.
 - `hybridclaw auth login mistral` accepts `--api-key`, falls back to `MISTRAL_API_KEY`, or prompts you to paste the key, then enables the provider and can set the global default model.
 - `hybridclaw auth login huggingface` accepts `--api-key`, falls back to `HF_TOKEN`, or prompts you to paste the token, then enables the provider and can set the global default model.
-- `hybridclaw auth login local` configures Ollama, LM Studio, or vLLM in `~/.hybridclaw/config.json`.
-- `hybridclaw auth login msteams` enables Microsoft Teams, stores `MSTEAMS_APP_PASSWORD` in `~/.hybridclaw/credentials.json`, and can prompt for the app id, app password, and optional tenant id.
+- `hybridclaw auth login local` configures Ollama, LM Studio, llama.cpp, or vLLM in `~/.hybridclaw/config.json`.
+- The local backend model id is optional. If omitted, HybridClaw enables the backend and you can choose a model later with `/model list <backend>`.
+- Interactive onboarding can skip remote-provider auth entirely when you plan to run on a local backend.
+- `hybridclaw auth login msteams` enables Microsoft Teams, stores `MSTEAMS_APP_PASSWORD` in the encrypted `~/.hybridclaw/credentials.json` store, and can prompt for the app id, app password, and optional tenant id.
 - `hybridclaw auth status hybridai` reports the local auth source, masked API key, active config file, base URL, and default model without printing the credentials file path.
 - `hybridclaw auth logout local` disables configured local backends and clears any saved vLLM API key.
 - `hybridclaw auth logout msteams` clears the stored Teams app password and disables the Teams integration in config.
 - `hybridclaw auth whatsapp reset` clears linked WhatsApp Web auth without starting a new pairing session.
-- HybridAI, OpenRouter, Mistral, Hugging Face, Discord, email, Teams, and BlueBubbles iMessage secrets are stored in `~/.hybridclaw/credentials.json`. Codex OAuth credentials are stored separately in `~/.hybridclaw/codex-auth.json`.
+- HybridAI, OpenRouter, Mistral, Hugging Face, Discord, email, Teams, and BlueBubbles iMessage secrets are stored encrypted in `~/.hybridclaw/credentials.json`. The encryption key is sourced from `HYBRIDCLAW_MASTER_KEY`, `/run/secrets/hybridclaw_master_key`, or the local owner-only `~/.hybridclaw/credentials.master.key`. Codex OAuth credentials are stored separately in `~/.hybridclaw/codex-auth.json`.
+- Local TUI and web sessions can also manage encrypted named secrets with `/secret list`, `/secret set <name> <value>`, `/secret unset <name>`, `/secret show <name>`, and `/secret route add <url-prefix> <secret-name> [header] [prefix|none]`.
 - Only one running HybridClaw process should own `~/.hybridclaw/credentials/whatsapp` at a time. If WhatsApp Web shows duplicate Chrome/Ubuntu linked devices or reconnect/auth drift starts, stop the extra process, run `hybridclaw auth whatsapp reset`, then pair again with `hybridclaw channels whatsapp setup`.
 - Use `hybridclaw help`, `hybridclaw help auth`, `hybridclaw help openrouter`, `hybridclaw help mistral`, `hybridclaw help huggingface`, or `hybridclaw help local` for CLI-specific reference output.
 
-## Setting Up MS Teams
+## Secrets And Authenticated API Calls
 
-See [docs/msteams.md](./docs/msteams.md) for the full setup flow, including:
+HybridClaw can keep API keys out of model-visible prompts and tool arguments.
 
-- Azure app registration and bot credentials
-- Azure Bot webhook and Teams channel configuration
-- `hybridclaw auth login msteams`
-- local tunnel setup
-- DM and channel smoke tests
+```text
+/secret set STAGING_HYBRIDAI_API_KEY demo_key_2024
+/secret route add https://staging.hybridai.one/api/v1/ STAGING_HYBRIDAI_API_KEY X-API-Key none
+```
 
-## Setting Up iMessage
+After that, the model can just ask for the API call in natural language:
 
-See [docs/imessage.md](./docs/imessage.md) for the full setup flow, including:
+```text
+POST to https://staging.hybridai.one/api/v1/virtual-bots/survey with JSON:
+{
+  "question": "Climate change is the biggest threat to humanity.",
+  "sample_size": 10,
+  "survey": "eurobarometer",
+  "gender": "Man",
+  "min_age": 25,
+  "max_age": 65
+}
+```
+
+Or you can use an explicit placeholder:
+
+```text
+POST to https://staging.hybridai.one/api/v1/virtual-bots/survey with header X-API-Key: <secret:STAGING_HYBRIDAI_API_KEY> and the same JSON body.
+```
+
+- The model only sees the secret name or placeholder, never the real token.
+- The gateway injects the real header at request time via `http_request`.
+- Tool-call audit records redact injected secret values before persistence.
+- Selected config fields such as `ops.webApiToken`, `ops.gatewayApiToken`,
+  `imessage.password`, and `local.backends.vllm.apiKey` can also use
+  SecretRefs like `{ "source": "store", "id": "IMESSAGE_PASSWORD" }` or
+  `${ENV_VAR}` instead of plaintext config values.
+
+## Setting Up Channels
+
+See [docs/development/getting-started/channels.md](./docs/development/getting-started/channels.md)
+for the setup commands and step-by-step flows for:
+
+- Discord
+- Email
+- WhatsApp
+- iMessage
+- Microsoft Teams
 
-- local macOS mode with `imsg` and Messages `chat.db`
-- remote/cloud mode with BlueBubbles webhooks + REST sends
-- `imessage.*` config examples for both backends
-- `IMESSAGE_PASSWORD` secret handling for BlueBubbles
-- DM/group policy notes and smoke-test steps
+For transport-specific deep dives:
+
+- [docs/imessage.md](./docs/imessage.md) covers local macOS and BlueBubbles
+  remote setup in detail
+- [docs/msteams.md](./docs/msteams.md) covers the Azure app, bot resource, and
+  webhook registration flow
 
 ## Model Selection
 
@@ -266,8 +307,8 @@ Runtime model:
 HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most runtime settings.
 
 - Start from `config.example.json` (reference).
-- Runtime state lives under `~/.hybridclaw/` (`config.json`, `credentials.json`, `data/hybridclaw.db`, audit/session files). Set `HYBRIDCLAW_DATA_DIR` to an absolute path to relocate the full runtime home, including browser profiles and agent workspaces.
-- HybridClaw does not keep runtime state in the current working directory. If `./.env` exists, supported secrets are migrated once into `~/.hybridclaw/credentials.json`.
+- Runtime state lives under `~/.hybridclaw/` (`config.json`, encrypted `credentials.json`, `credentials.master.key`, `data/hybridclaw.db`, audit/session files). Set `HYBRIDCLAW_DATA_DIR` to an absolute path to relocate the full runtime home, including browser profiles and agent workspaces.
+- HybridClaw does not keep runtime state in the current working directory. If `./.env` exists, supported secrets are migrated once into the encrypted `~/.hybridclaw/credentials.json` store.
 - `container.*` controls execution isolation, including `sandboxMode`, `memory`, `memorySwap`, `cpus`, `network`, `binds`, and additional mounts.
 - `hybridclaw config` prints the active runtime config path and current config, `config check` validates only the config file itself, `config reload` performs an immediate in-process hot reload, and `config set <key> <value>` updates one existing dotted key path and re-validates the result.
 - Use `container.binds` for explicit host-to-container mounts in `host:container[:ro|rw]` format. Mounted paths appear inside the sandbox under `/workspace/extra/<container>`.
@@ -281,14 +322,15 @@ HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most
 - `plugins.list[]` controls plugin overrides such as `enabled`, custom `path`, and top-level `config` values. Use `hybridclaw plugin config <plugin-id> [key] [value|--unset]` for focused edits without rewriting the full config file.
 - `observability.*` controls HybridAI observability ingest, including the target base URL, bot and agent ids, flush interval, and batch size for structured audit event forwarding.
 - `adaptiveSkills.*` controls observation, inspection, amendment staging, and rollback for the self-improving skill loop. See [docs/development/extensibility/adaptive-skills.md](./docs/development/extensibility/adaptive-skills.md) for the operator workflow.
-- `imessage.*` controls the dual-backend iMessage transport. Use `backend: "local"` on macOS with `imsg` + `chat.db`, or `backend: "bluebubbles"` for a remote Mac relay via BlueBubbles. Prefer storing the BlueBubbles password in `~/.hybridclaw/credentials.json` as `IMESSAGE_PASSWORD` instead of plaintext config.
+- `imessage.*` controls the dual-backend iMessage transport. Use `backend: "local"` on macOS with `imsg` + `chat.db`, or `backend: "bluebubbles"` for a remote Mac relay via BlueBubbles. Prefer storing the BlueBubbles password in the encrypted `~/.hybridclaw/credentials.json` store as `IMESSAGE_PASSWORD` instead of plaintext config.
 - `email.pollIntervalMs` defaults to `30000` (30 seconds) and is clamped to a minimum of `1000`.
 - `ops.webApiToken` (or `WEB_API_TOKEN`) gates the built-in `/chat`, `/agents`, and `/admin` surfaces plus the admin API. When unset, localhost browser access stays open without a login prompt.
+- `tools.httpRequest.authRules[]` configures gateway-side URL-based auth injection for `http_request`, for example mapping `https://staging.hybridai.one/api/v1/` to `X-API-Key` plus a stored secret ref.
 - `mcpServers.*.env` and `mcpServers.*.headers` are currently written to `~/.hybridclaw/config.json` as plain text. Use low-privilege tokens only, set `chmod 700 ~/.hybridclaw && chmod 600 ~/.hybridclaw/config.json`, and prefer `host` sandbox mode for stdio MCP servers that depend on host-installed tools.
 - `media.audio` controls shared inbound audio transcription. By default it auto-detects local CLIs first (`sherpa-onnx-offline`, `whisper-cli`, `whisper`), then `gemini`, then provider keys (`openai`, `groq`, `deepgram`, `google`).
 - `whisper-cli` auto-detect also needs a whisper.cpp model file. If the binary exists but HybridClaw still skips local transcription, set `WHISPER_CPP_MODEL` to a local `ggml-*.bin` model path.
 - If no transcript backend is available, the container tries native model audio input before tool-use fallback for supported local providers. Today that fallback is enabled for `vllm` sessions and uses the original current-turn audio attachment.
-- Keep runtime secrets in `~/.hybridclaw/credentials.json` (`HYBRIDAI_API_KEY`, `OPENROUTER_API_KEY`, `HF_TOKEN`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `DEEPGRAM_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `DISCORD_TOKEN`, `EMAIL_PASSWORD`, `IMESSAGE_PASSWORD`, `MSTEAMS_APP_PASSWORD`). Codex OAuth sessions are stored separately in `~/.hybridclaw/codex-auth.json`.
+- Keep runtime secrets in the encrypted `~/.hybridclaw/credentials.json` store (`HYBRIDAI_API_KEY`, `OPENROUTER_API_KEY`, `HF_TOKEN`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `DEEPGRAM_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `DISCORD_TOKEN`, `EMAIL_PASSWORD`, `IMESSAGE_PASSWORD`, `MSTEAMS_APP_PASSWORD`). The master key should come from `HYBRIDCLAW_MASTER_KEY` or `/run/secrets/hybridclaw_master_key` on headless hosts; otherwise HybridClaw creates an owner-only `~/.hybridclaw/credentials.master.key`. Codex OAuth sessions are stored separately in `~/.hybridclaw/codex-auth.json`.
 - Trust-model acceptance is stored in `~/.hybridclaw/config.json` under `security.*` and is required before runtime starts. In headless environments, set `HYBRIDCLAW_ACCEPT_TRUST=true` to persist acceptance automatically before credential checks run.
 - See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
 - For contributor workflow, see [CONTRIBUTING.md](./CONTRIBUTING.md). For deeper runtime, skills, release, voice/TTS, and maintainer reference docs, see [docs/development/README.md](./docs/development/README.md).
@@ -383,6 +425,26 @@ hybridclaw agent activate demo-agent
 - See [docs/development/extensibility/agent-packages.md](./docs/development/extensibility/agent-packages.md)
   for the archive layout, manifest fields, and security rules.
 
+## Migrate From OpenClaw Or Hermes Agent
+
+HybridClaw can import compatible state from an existing `~/.openclaw` or
+`~/.hermes` home into a target HybridClaw agent workspace.
+
+```bash
+hybridclaw migrate openclaw --dry-run
+hybridclaw migrate hermes --dry-run
+```
+
+Notes:
+
+- Use `--agent <id>` to import into an agent other than `main`.
+- Use `--overwrite` to replace existing HybridClaw files or config values when
+  the preview shows conflicts.
+- Use `--migrate-secrets` to import compatible secret material into the
+  encrypted `~/.hybridclaw/credentials.json` store.
+- Execute-mode runs write a report under `~/.hybridclaw/migration/openclaw/`
+  or `~/.hybridclaw/migration/hermes/`.
+
 ## Local Provider Quickstart (LM Studio Example)
 
 If LM Studio is running locally and serving `qwen/qwen3.5-9b` on
@@ -453,6 +515,8 @@ Other backends use the same flow:
 
 ```bash
 hybridclaw auth login local ollama llama3.2
+hybridclaw auth login local llamacpp --base-url http://127.0.0.1:8081
+hybridclaw auth login local llamacpp Meta-Llama-3-8B-Instruct --base-url http://127.0.0.1:8081
 hybridclaw auth login local vllm mistralai/Mistral-7B-Instruct-v0.3 --base-url http://127.0.0.1:8000 --api-key secret
 ```
 
@@ -586,6 +650,7 @@ CLI runtime commands:
 - `hybridclaw gateway agent [list|switch <id>|create <id> [--model <model>]|model [name]]` — Inspect or change the current session-to-agent binding and persistent agent model
 - `hybridclaw gateway compact` — Archive older session history into semantic memory while preserving a recent active context tail
 - `hybridclaw gateway reset [yes|no]` — Clear session history, reset per-session model/chatbot/RAG settings, and remove the current agent workspace (confirmation required)
+- `hybridclaw migrate openclaw [options]`, `hybridclaw migrate hermes [options]` — Preview or import compatible OpenClaw or Hermes Agent home state into a HybridClaw agent workspace, with optional secret migration and per-run reports
 - `hybridclaw agent list` — Show registered agents in a script-friendly tab-separated format
 - `hybridclaw agent export [agent-id] [-o <path>]`, `inspect <file.claw>`, `install <file.claw|https://.../*.claw|official:<agent-dir>|github:owner/repo[/<ref>]/<agent-dir>> [--id <id>] [--force] [--skip-skill-scan] [--skip-externals] [--skip-import-errors] [--yes]`, `uninstall <agent-id> [--yes]` — Manage portable `.claw` agent archives (legacy `pack` / `unpack` aliases still work)
 - `hybridclaw tui` — Start terminal client connected to gateway
@@ -603,7 +668,7 @@ CLI runtime commands:
 - `hybridclaw channels whatsapp setup [--reset] [--allow-from <+E164>]...` — Prepare private-by-default WhatsApp config, enable the default `👀` ack reaction, optionally wipe stale auth, open a temporary pairing session, and print the QR code
 - `hybridclaw browser login [--url <url>]`, `status`, `reset` — Manage the persistent browser profile used for authenticated web automation
 - `hybridclaw local status` — Show current local backend config and default model
-- `hybridclaw local configure <backend> <model-id> [--base-url <url>] [--api-key <key>] [--no-default]` — Enable and configure a local backend
+- `hybridclaw local configure <backend> [model-id] [--base-url <url>] [--api-key <key>] [--no-default]` — Enable and configure a local backend
 - `hybridclaw hybridai ...`, `hybridclaw codex ...`, and `hybridclaw local ...` — Legacy aliases for the older provider-specific command surface
 - `hybridclaw help` / `hybridclaw help auth` / `hybridclaw help openrouter` / `hybridclaw help mistral` — Print CLI reference for the unified provider commands
 - `hybridclaw doctor [--fix|--json|<component>]` — Diagnose runtime, gateway, config, credentials, database, providers, local backends, Docker, channels, skills, security, and disk state

package/config.example.json

@@ -211,6 +211,10 @@
         "enabled": false,
         "baseUrl": "http://127.0.0.1:1234/v1"
       },
+      "llamacpp": {
+        "enabled": false,
+        "baseUrl": "http://127.0.0.1:8081/v1"
+      },
       "vllm": {
         "enabled": false,
         "baseUrl": "http://127.0.0.1:8000/v1",