From 93e5383cb2f17134e6c024a9248ced2ac266b39c Mon Sep 17 00:00:00 2001 From: Chummy Date: Wed, 18 Feb 2026 16:53:26 +0800 Subject: [PATCH] docs: overhaul docs IA and multilingual navigation --- NOTICE | 19 ++ README.ja.md | 161 +++++++++++ README.md | 154 +++++++--- README.ru.md | 161 +++++++++++ README.zh-CN.md | 166 +++++++++++ bootstrap.sh | 5 + docs/README.ja.md | 82 ++++++ docs/README.md | 78 +++++ docs/README.ru.md | 82 ++++++ docs/README.zh-CN.md | 82 ++++++ docs/SUMMARY.md | 72 +++++ docs/adding-boards-and-tools.md | 2 +- docs/agnostic-security.md | 5 + docs/arduino-uno-q-setup.md | 8 +- docs/audit-logging.md | 5 + docs/channels-reference.md | 105 +++++++ docs/commands-reference.md | 121 ++++++++ docs/config-reference.md | 72 +++++ docs/contributing/README.md | 18 ++ docs/docs-inventory.md | 95 +++++++ docs/frictionless-security.md | 5 + docs/getting-started/README.md | 20 ++ docs/hardware/README.md | 14 + docs/mattermost-setup.md | 4 +- docs/network-deployment.md | 16 +- docs/nucleo-setup.md | 4 +- docs/one-click-bootstrap.md | 92 ++++++ docs/operations-runbook.md | 128 +++++++++ docs/operations/README.md | 23 ++ docs/project-triage-snapshot-2026-02-18.md | 94 ++++++ docs/project/README.md | 13 + docs/providers-reference.md | 89 ++++++ docs/reference/README.md | 14 + docs/resource-limits.md | 5 + docs/sandboxing.md | 5 + docs/security-roadmap.md | 5 + docs/security/README.md | 22 ++ docs/troubleshooting.md | 154 ++++++++++ scripts/bootstrap.sh | 314 +++++++++++++++++++++ scripts/install.sh | 179 +++--------- 40 files changed, 2495 insertions(+), 198 deletions(-) create mode 100644 NOTICE create mode 100644 README.ja.md create mode 100644 README.ru.md create mode 100644 README.zh-CN.md create mode 100755 bootstrap.sh create mode 100644 docs/README.ja.md create mode 100644 docs/README.md create mode 100644 docs/README.ru.md create mode 100644 docs/README.zh-CN.md create mode 100644 docs/SUMMARY.md create mode 100644 docs/channels-reference.md create mode 100644 docs/commands-reference.md create mode 100644 docs/config-reference.md create mode 100644 docs/contributing/README.md create mode 100644 docs/docs-inventory.md create mode 100644 docs/getting-started/README.md create mode 100644 docs/hardware/README.md create mode 100644 docs/one-click-bootstrap.md create mode 100644 docs/operations-runbook.md create mode 100644 docs/operations/README.md create mode 100644 docs/project-triage-snapshot-2026-02-18.md create mode 100644 docs/project/README.md create mode 100644 docs/providers-reference.md create mode 100644 docs/reference/README.md create mode 100644 docs/security/README.md create mode 100644 docs/troubleshooting.md create mode 100755 scripts/bootstrap.sh mode change 100644 => 100755 scripts/install.sh diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..f2e824c --- /dev/null +++ b/NOTICE @@ -0,0 +1,19 @@ +ZeroClaw +Copyright 2025 ZeroClaw Labs + +This product includes software developed at ZeroClaw Labs (https://github.com/zeroclaw-labs). + +Contributors +============ + +This NOTICE file is maintained by repository automation. +For the latest contributor list, see the repository contributors page: +https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors + +Third-Party Dependencies +======================== + +This project uses third-party libraries and components, +each licensed under their respective terms. + +See Cargo.lock for a complete dependency list. diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..88008a9 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,161 @@ +

+ ZeroClaw +

+ +

ZeroClaw 🦀（日本語）

+ +

+ Zero overhead. Zero compromise. 100% Rust. 100% Agnostic. +

+ +

+ 🌐 言語: English · 简体中文 · 日本語 · Русский +

+ +

+ ワンクリック導入 | + ドキュメントハブ | + Docs TOC | + コマンド | + 設定リファレンス | + Provider 参考 | + Channel 参考 | + 運用ガイド | + トラブル対応 | + 貢献ガイド +

+ +

+ クイック分流： + 導入 · + 参照 · + 運用 · + 障害対応 · + セキュリティ · + ハードウェア · + 貢献・CI +

+ +> この文書は `README.md` の内容を、正確性と可読性を重視して日本語に整えた版です（逐語訳ではありません）。 +> +> コマンド名、設定キー、API パス、Trait 名などの技術識別子は英語のまま維持しています。 +> +> 最終同期日: **2026-02-18**。 + +## 概要 + +ZeroClaw は、高速・省リソース・高拡張性を重視した自律エージェント実行基盤です。 + +- Rust ネイティブ実装、単一バイナリで配布可能 +- Trait ベース設計（`Provider` / `Channel` / `Tool` / `Memory` など） +- セキュアデフォルト（ペアリング、明示 allowlist、サンドボックス、スコープ制御） + +## ZeroClaw が選ばれる理由 + +- **軽量**: 小さいバイナリ、低メモリ、速い起動 +- **拡張性**: 28+ の built-in provider（エイリアス含む）+ custom endpoint +- **運用性**: `daemon` / `doctor` / `status` / `service` で保守しやすい +- **統合性**: 多チャネル + 70+ integrations + +## 再現可能な計測（例） + +README のサンプル値（macOS arm64, 2026-02-18）: + +- Release バイナリ: `8.8M` +- `zeroclaw --help`: 約 `0.02s`、ピークメモリ 約 `3.9MB` +- `zeroclaw status`: 約 `0.01s`、ピークメモリ 約 `4.1MB` + +環境差があるため、必ず自身の環境で再計測してください。 + +```bash +cargo build --release +ls -lh target/release/zeroclaw + +/usr/bin/time -l target/release/zeroclaw --help +/usr/bin/time -l target/release/zeroclaw status +``` + +## ワンクリック導入 + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +./bootstrap.sh +``` + +環境ごと初期化する場合: `./bootstrap.sh --install-system-deps --install-rust`（システムパッケージで `sudo` が必要な場合があります）。 + +詳細は [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md) を参照してください。 + +## クイックスタート + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +cargo build --release --locked +cargo install --path . --force --locked + +zeroclaw onboard --api-key sk-... --provider openrouter +zeroclaw onboard --interactive + +zeroclaw agent -m "Hello, ZeroClaw!" + +# default: 127.0.0.1:3000 +zeroclaw gateway + +zeroclaw daemon +``` + +## セキュリティのデフォルト + +- Gateway の既定バインド: `127.0.0.1:3000` +- 既定でペアリング必須: `require_pairing = true` +- 既定で公開バインド禁止: `allow_public_bind = false` +- Channel allowlist: + - `[]` は deny-by-default + - `["*"]` は allow all（意図的に使う場合のみ） + +## 設定例 + +```toml +api_key = "sk-..." +default_provider = "openrouter" +default_model = "anthropic/claude-sonnet-4" +default_temperature = 0.7 + +[memory] +backend = "sqlite" +auto_save = true +embedding_provider = "none" + +[gateway] +host = "127.0.0.1" +port = 3000 +require_pairing = true +allow_public_bind = false +``` + +## ドキュメント入口 + +- ドキュメントハブ（英語）: [`docs/README.md`](docs/README.md) +- 統合 TOC: [`docs/SUMMARY.md`](docs/SUMMARY.md) +- ドキュメントハブ（日本語）: [`docs/README.ja.md`](docs/README.ja.md) +- コマンドリファレンス: [`docs/commands-reference.md`](docs/commands-reference.md) +- 設定リファレンス: [`docs/config-reference.md`](docs/config-reference.md) +- Provider リファレンス: [`docs/providers-reference.md`](docs/providers-reference.md) +- Channel リファレンス: [`docs/channels-reference.md`](docs/channels-reference.md) +- 運用ガイド（Runbook）: [`docs/operations-runbook.md`](docs/operations-runbook.md) +- トラブルシューティング: [`docs/troubleshooting.md`](docs/troubleshooting.md) +- ドキュメント一覧 / 分類: [`docs/docs-inventory.md`](docs/docs-inventory.md) +- プロジェクト triage スナップショット: [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md) + +## コントリビュート / ライセンス + +- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md) +- PR Workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md) +- Reviewer Playbook: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md) +- License: MIT（[`LICENSE`](LICENSE), [`NOTICE`](NOTICE)） + +--- + +詳細仕様（全コマンド、アーキテクチャ、API 仕様、開発フロー）は英語版の [`README.md`](README.md) を参照してください。 diff --git a/README.md b/README.md index 2fc9ffb..ce2cce9 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,42 @@ Built by students and members of the Harvard, MIT, and Sundai.Club communities.

+

+ 🌐 Languages: English · 简体中文 · 日本語 · Русский +

+ +

+ Getting Started | + One-Click Setup | + Documentation | + Docs TOC | + Commands | + Config | + Providers | + Channels | + Runbook | + Troubleshooting | + Contributing | + Security +

+ +

+ Quick Routes: + Setup · + Reference · + Operations · + Troubleshoot · + Security · + Hardware · + Contribute +

+

Fast, small, and fully autonomous AI assistant infrastructure
Deploy anywhere. Swap anything.

-

~3.4MB binary · <10ms startup · 1,017 tests · 23+ providers · 8 traits · Pluggable everything

+

Trait-driven architecture · secure-by-default runtime · provider/channel/tool swappable · pluggable everything

### ✨ Features @@ -39,25 +69,11 @@ Built by students and members of the Harvard, MIT, and Sundai.Club communities. - **Fully swappable:** core systems are traits (providers, channels, tools, memory, tunnels). - **No lock-in:** OpenAI-compatible provider support + pluggable custom endpoints. -## Benchmark Snapshot (ZeroClaw vs OpenClaw) +## Benchmark Snapshot (Reproducible) -Local machine quick benchmark (macOS arm64, Feb 2026) normalized for 0.8GHz edge hardware. +Benchmark claims can drift as code and toolchains evolve, so this section focuses on reproducible local measurement. -| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 | -|---|---|---|---|---| -| **Language** | TypeScript | Python | Go | **Rust** | -| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** | -| **Startup (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** | -| **Binary Size** | ~28MB (dist) | N/A (Scripts) | ~8MB | **3.4 MB** | -| **Cost** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Any hardware $10** | - -> Notes: ZeroClaw results measured with `/usr/bin/time -l` on release builds. OpenClaw requires Node.js runtime (~390MB overhead). PicoClaw and ZeroClaw are static binaries. - -

- ZeroClaw vs OpenClaw Comparison -

- -Reproduce ZeroClaw numbers locally: +Measure your current build locally: ```bash cargo build --release @@ -67,6 +83,12 @@ ls -lh target/release/zeroclaw /usr/bin/time -l target/release/zeroclaw status ``` +Example sample (macOS arm64, measured on February 18, 2026): + +- Release binary size: `8.8M` +- `zeroclaw --help`: about `0.02s` real time, ~`3.9MB` peak memory footprint +- `zeroclaw status`: about `0.01s` real time, ~`4.1MB` peak memory footprint + ## Prerequisites
@@ -139,6 +161,29 @@ curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts ## Quick Start +### One-click bootstrap + +```bash +# Recommended: clone then run local bootstrap script +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +./bootstrap.sh + +# Optional: bootstrap dependencies + Rust on fresh machines +./bootstrap.sh --install-system-deps --install-rust + +# Optional: run onboarding in the same flow +./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter +``` + +Remote one-liner (review first in security-sensitive environments): + +```bash +curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash +``` + +Details: [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md) (toolchain mode may request `sudo` for system packages). + ```bash git clone https://github.com/zeroclaw-labs/zeroclaw.git cd zeroclaw @@ -164,7 +209,7 @@ zeroclaw agent -m "Hello, ZeroClaw!" zeroclaw agent # Start the gateway (webhook server) -zeroclaw gateway # default: 127.0.0.1:8080 +zeroclaw gateway # default: 127.0.0.1:3000 zeroclaw gateway --port 0 # random port (security hardened) # Start full autonomous runtime @@ -255,18 +300,18 @@ Every subsystem is a **trait** — swap implementations with a config change, ze | Subsystem | Trait | Ships with | Extend | |-----------|-------|------------|--------| -| **AI Models** | `Provider` | 23+ providers (OpenRouter, Anthropic, OpenAI, Ollama, Venice, Groq, Mistral, xAI, DeepSeek, Together, Fireworks, Perplexity, Cohere, Bedrock, Astrai, etc.) | `custom:https://your-api.com` — any OpenAI-compatible API | -| **Channels** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, WhatsApp, Webhook | Any messaging API | -| **Memory** | `Memory` | SQLite with hybrid search (FTS5 + vector cosine similarity), Lucid bridge (CLI sync + SQLite fallback), Markdown | Any persistence backend | -| **Tools** | `Tool` | shell, file_read, file_write, memory_store, memory_recall, memory_forget, browser_open (Brave + allowlist), browser (agent-browser / rust-native), composio (optional) | Any capability | +| **AI Models** | `Provider` | Provider catalog via `zeroclaw providers` (currently 28 built-ins + aliases, plus custom endpoints) | `custom:https://your-api.com` (OpenAI-compatible) or `anthropic-custom:https://your-api.com` | +| **Channels** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp, Email, IRC, Lark, DingTalk, QQ, Webhook | Any messaging API | +| **Memory** | `Memory` | SQLite hybrid search, Lucid bridge, Markdown files, explicit `none` backend, snapshot/hydrate, optional response cache | Any persistence backend | +| **Tools** | `Tool` | shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, hardware tools | Any capability | | **Observability** | `Observer` | Noop, Log, Multi | Prometheus, OTel | -| **Runtime** | `RuntimeAdapter` | Native, Docker (sandboxed) | WASM (planned; unsupported kinds fail fast) | +| **Runtime** | `RuntimeAdapter` | Native, Docker (sandboxed) | Additional runtimes can be added via adapter; unsupported kinds fail fast | | **Security** | `SecurityPolicy` | Gateway pairing, sandbox, allowlists, rate limits, filesystem scoping, encrypted secrets | — | | **Identity** | `IdentityConfig` | OpenClaw (markdown), AIEOS v1.1 (JSON) | Any identity format | | **Tunnel** | `Tunnel` | None, Cloudflare, Tailscale, ngrok, Custom | Any tunnel binary | | **Heartbeat** | Engine | HEARTBEAT.md periodic tasks | — | | **Skills** | Loader | TOML manifests + SKILL.md instructions | Community skill packs | -| **Integrations** | Registry | 50+ integrations across 9 categories | Plugin system | +| **Integrations** | Registry | 70+ integrations across 9 categories | Plugin system | ### Runtime support (current) @@ -295,7 +340,7 @@ The agent automatically recalls, saves, and manages memory via tools. [memory] backend = "sqlite" # "sqlite", "lucid", "markdown", "none" auto_save = true -embedding_provider = "openai" +embedding_provider = "none" # "none", "openai", "custom:https://..." vector_weight = 0.7 keyword_weight = 0.3 @@ -328,7 +373,7 @@ ZeroClaw enforces security at **every layer** — not just the sandbox. It passe > **Run your own nmap:** `nmap -p 1-65535 ` — ZeroClaw binds to localhost only, so nothing is exposed unless you explicitly configure a tunnel. -### Channel allowlists (Telegram / Discord / Slack / Mattermost) +### Channel allowlists (deny-by-default) Inbound sender policy is now consistent: @@ -412,7 +457,7 @@ WhatsApp uses Meta's Cloud API with webhooks (push-based, not polling): 4. **Start the gateway with a tunnel:** ```bash - zeroclaw gateway --port 8080 + zeroclaw gateway --port 3000 ``` WhatsApp requires HTTPS, so use a tunnel (ngrok, Cloudflare, Tailscale Funnel). @@ -431,7 +476,7 @@ Config: `~/.zeroclaw/config.toml` (created by `onboard`) ```toml api_key = "sk-..." default_provider = "openrouter" -default_model = "anthropic/claude-sonnet-4-20250514" +default_model = "anthropic/claude-sonnet-4" default_temperature = 0.7 # Custom OpenAI-compatible endpoint @@ -443,13 +488,15 @@ default_temperature = 0.7 [memory] backend = "sqlite" # "sqlite", "lucid", "markdown", "none" auto_save = true -embedding_provider = "openai" # "openai", "noop" +embedding_provider = "none" # "none", "openai", "custom:https://..." vector_weight = 0.7 keyword_weight = 0.3 # backend = "none" disables persistent memory via no-op backend [gateway] +port = 3000 # default +host = "127.0.0.1" # default require_pairing = true # require pairing code on first connect allow_public_bind = false # refuse 0.0.0.0 without tunnel @@ -652,28 +699,32 @@ See [aieos.org](https://aieos.org) for the full schema and live examples. |----------|--------|------|-------------| | `/health` | GET | None | Health check (always public, no secrets leaked) | | `/pair` | POST | `X-Pairing-Code` header | Exchange one-time code for bearer token | -| `/webhook` | POST | `Authorization: Bearer ` | Send message: `{"message": "your prompt"}` | +| `/webhook` | POST | `Authorization: Bearer ` | Send message: `{"message": "your prompt"}`; optional `X-Idempotency-Key` | | `/whatsapp` | GET | Query params | Meta webhook verification (hub.mode, hub.verify_token, hub.challenge) | -| `/whatsapp` | POST | None (Meta signature) | WhatsApp incoming message webhook | +| `/whatsapp` | POST | Meta signature (`X-Hub-Signature-256`) when app secret is configured | WhatsApp incoming message webhook | ## Commands | Command | Description | |---------|-------------| | `onboard` | Quick setup (default) | -| `onboard --interactive` | Full interactive 7-step wizard | -| `onboard --channels-only` | Reconfigure channels/allowlists only (fast repair flow) | -| `agent -m "..."` | Single message mode | -| `agent` | Interactive chat mode | -| `gateway` | Start webhook server (default: `127.0.0.1:8080`) | -| `gateway --port 0` | Random port mode | +| `agent` | Interactive or single-message chat mode | +| `gateway` | Start webhook server (default: `127.0.0.1:3000`) | | `daemon` | Start long-running autonomous runtime | -| `service install/start/stop/status/uninstall` | Manage user-level background service | +| `service` | Manage user-level background service | | `doctor` | Diagnose daemon/scheduler/channel freshness | | `status` | Show full system status | -| `channel doctor` | Run health checks for configured channels | -| `channel bind-telegram ` | Add one Telegram username/user ID to allowlist | -| `integrations info ` | Show setup/status details for one integration | +| `cron` | Manage scheduled tasks (`list/add/add-at/add-every/once/remove/pause/resume`) | +| `models` | Refresh provider model catalogs (`models refresh`) | +| `providers` | List supported providers and aliases | +| `channel` | List/start/doctor channels and bind Telegram identities | +| `integrations` | Inspect integration setup details | +| `skills` | List/install/remove skills | +| `migrate` | Import data from other runtimes (`migrate openclaw`) | +| `hardware` | USB discover/introspect/info commands | +| `peripheral` | Manage and flash hardware peripherals | + +For a task-oriented command guide, see [`docs/commands-reference.md`](docs/commands-reference.md). ## Development @@ -681,8 +732,8 @@ See [aieos.org](https://aieos.org) for the full schema and live examples. cargo build # Dev build cargo build --release # Release build (codegen-units=1, works on all devices including Raspberry Pi) cargo build --profile release-fast # Faster build (codegen-units=8, requires 16GB+ RAM) -cargo test # 1,017 tests -cargo clippy # Lint (0 warnings) +cargo test # Run full test suite +cargo clippy --locked --all-targets -- -D clippy::correctness cargo fmt # Format # Run the SQLite vs Markdown benchmark @@ -717,7 +768,20 @@ git push --no-verify ## Collaboration & Docs -For high-throughput collaboration and consistent reviews: +Start from the docs hub for a task-based map: + +- Documentation hub: [`docs/README.md`](docs/README.md) +- Unified docs TOC: [`docs/SUMMARY.md`](docs/SUMMARY.md) +- Commands reference: [`docs/commands-reference.md`](docs/commands-reference.md) +- Config reference: [`docs/config-reference.md`](docs/config-reference.md) +- Providers reference: [`docs/providers-reference.md`](docs/providers-reference.md) +- Channels reference: [`docs/channels-reference.md`](docs/channels-reference.md) +- Operations runbook: [`docs/operations-runbook.md`](docs/operations-runbook.md) +- Troubleshooting: [`docs/troubleshooting.md`](docs/troubleshooting.md) +- Docs inventory/classification: [`docs/docs-inventory.md`](docs/docs-inventory.md) +- PR/Issue triage snapshot (as of February 18, 2026): [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md) + +Core collaboration references: - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md) - PR workflow policy: [docs/pr-workflow.md](docs/pr-workflow.md) diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..d51e5fa --- /dev/null +++ b/README.ru.md @@ -0,0 +1,161 @@ +

+ ZeroClaw +

+ +

ZeroClaw 🦀（Русский）

+ +

+ Zero overhead. Zero compromise. 100% Rust. 100% Agnostic. +

+ +

+ 🌐 Языки: English · 简体中文 · 日本語 · Русский +

+ +

+ Установка в 1 клик | + Хаб документации | + TOC docs | + Команды | + Конфиг | + Providers | + Channels | + Операции | + Диагностика | + Вклад +

+ +

+ Быстрые маршруты: + Старт · + Справочники · + Операции · + Диагностика · + Безопасность · + Аппаратная часть · + Вклад и CI +

+ +> Этот файл — выверенный перевод `README.md` с акцентом на точность и читаемость (не дословный перевод). +> +> Технические идентификаторы (команды, ключи конфигурации, API-пути, имена Trait) сохранены на английском. +> +> Последняя синхронизация: **2026-02-18**. + +## О проекте + +ZeroClaw — это производительная и расширяемая инфраструктура автономного AI-агента: + +- Нативно на Rust, единый бинарник, переносимость между ARM / x86 / RISC-V +- Архитектура на Trait (`Provider`, `Channel`, `Tool`, `Memory` и др.) +- Безопасные значения по умолчанию: pairing, явные allowlist, sandbox и scope-ограничения + +## Почему выбирают ZeroClaw + +- **Лёгкий**: небольшой бинарник, низкое потребление памяти, быстрый старт +- **Расширяемый**: 28+ built-in providers (с алиасами) + custom совместимые endpoint +- **Удобный в эксплуатации**: `daemon`, `doctor`, `status`, `service` +- **Интеграции**: много каналов + 70+ integrations + +## Воспроизводимые метрики (пример) + +Текущие примерные значения из README (macOS arm64, 2026-02-18): + +- Размер release-бинарника: `8.8M` +- `zeroclaw --help`: ~`0.02s`, пик памяти ~`3.9MB` +- `zeroclaw status`: ~`0.01s`, пик памяти ~`4.1MB` + +Проверяйте производительность в своей среде: + +```bash +cargo build --release +ls -lh target/release/zeroclaw + +/usr/bin/time -l target/release/zeroclaw --help +/usr/bin/time -l target/release/zeroclaw status +``` + +## Установка в 1 клик + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +./bootstrap.sh +``` + +Для полной инициализации окружения: `./bootstrap.sh --install-system-deps --install-rust` (для системных пакетов может потребоваться `sudo`). + +Подробности: [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md). + +## Быстрый старт + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +cargo build --release --locked +cargo install --path . --force --locked + +zeroclaw onboard --api-key sk-... --provider openrouter +zeroclaw onboard --interactive + +zeroclaw agent -m "Hello, ZeroClaw!" + +# default: 127.0.0.1:3000 +zeroclaw gateway + +zeroclaw daemon +``` + +## Важные security-дефолты + +- Gateway по умолчанию: `127.0.0.1:3000` +- Pairing обязателен по умолчанию: `require_pairing = true` +- Публичный bind запрещён по умолчанию: `allow_public_bind = false` +- Семантика allowlist каналов: + - `[]` => deny-by-default + - `["*"]` => allow all (используйте осознанно) + +## Пример конфигурации + +```toml +api_key = "sk-..." +default_provider = "openrouter" +default_model = "anthropic/claude-sonnet-4" +default_temperature = 0.7 + +[memory] +backend = "sqlite" +auto_save = true +embedding_provider = "none" + +[gateway] +host = "127.0.0.1" +port = 3000 +require_pairing = true +allow_public_bind = false +``` + +## Навигация по документации + +- Хаб документации (English): [`docs/README.md`](docs/README.md) +- Единый TOC docs: [`docs/SUMMARY.md`](docs/SUMMARY.md) +- Хаб документации (Русский): [`docs/README.ru.md`](docs/README.ru.md) +- Справочник команд: [`docs/commands-reference.md`](docs/commands-reference.md) +- Справочник конфигурации: [`docs/config-reference.md`](docs/config-reference.md) +- Справочник providers: [`docs/providers-reference.md`](docs/providers-reference.md) +- Справочник channels: [`docs/channels-reference.md`](docs/channels-reference.md) +- Операционный runbook: [`docs/operations-runbook.md`](docs/operations-runbook.md) +- Устранение неполадок: [`docs/troubleshooting.md`](docs/troubleshooting.md) +- Инвентарь и классификация docs: [`docs/docs-inventory.md`](docs/docs-inventory.md) +- Снимок triage проекта: [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md) + +## Вклад и лицензия + +- Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md) +- PR workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md) +- Reviewer playbook: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md) +- License: MIT ([`LICENSE`](LICENSE), [`NOTICE`](NOTICE)) + +--- + +Для полной и исчерпывающей информации (архитектура, все команды, API, разработка) используйте основной английский документ: [`README.md`](README.md). diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..33232e1 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,166 @@ +

+ ZeroClaw +

+ +

ZeroClaw 🦀（简体中文）

+ +

+ Zero overhead. Zero compromise. 100% Rust. 100% Agnostic. +

+ +

+ 🌐 语言：English · 简体中文 · 日本語 · Русский +

+ +

+ 一键部署 | + 文档总览 | + 文档目录 | + 命令参考 | + 配置参考 | + Provider 参考 | + Channel 参考 | + 运维手册 | + 故障排查 | + 贡献指南 +

+ +

+ 场景分流： + 安装入门 · + 参考手册 · + 运维部署 · + 故障排查 · + 安全专题 · + 硬件外设 · + 贡献与 CI +

+ +> 本文是对 `README.md` 的人工对齐翻译（强调可读性与准确性，不做逐字直译）。 +> +> 技术标识（命令、配置键、API 路径、Trait 名称）保持英文，避免语义漂移。 +> +> 最后对齐时间：**2026-02-18**。 + +## 项目简介 + +ZeroClaw 是一个高性能、低资源占用、可组合的自主智能体运行时： + +- Rust 原生实现，单二进制部署，跨 ARM / x86 / RISC-V。 +- Trait 驱动架构，`Provider` / `Channel` / `Tool` / `Memory` 可替换。 +- 安全默认值优先：配对鉴权、显式 allowlist、沙箱与作用域约束。 + +## 为什么选择 ZeroClaw + +- **轻量**：小体积二进制，低内存占用，启动快。 +- **可扩展**：支持 28+ 内置 provider（含别名）以及自定义兼容端点。 +- **可运维**：具备 `daemon`、`doctor`、`status`、`service` 等运维命令。 +- **可集成**：多渠道（Telegram、Discord、Slack、Matrix、WhatsApp、Email、IRC、Lark、DingTalk、QQ 等）与 70+ integrations。 + +## 可复现基准（示例） + +以下是当前 README 中的样例数据（macOS arm64，2026-02-18）： + +- Release 二进制：`8.8M` +- `zeroclaw --help`：约 `0.02s`，峰值内存约 `3.9MB` +- `zeroclaw status`：约 `0.01s`，峰值内存约 `4.1MB` + +建议始终在你的目标环境自行复测： + +```bash +cargo build --release +ls -lh target/release/zeroclaw + +/usr/bin/time -l target/release/zeroclaw --help +/usr/bin/time -l target/release/zeroclaw status +``` + +## 一键部署 + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +./bootstrap.sh +``` + +可选环境初始化：`./bootstrap.sh --install-system-deps --install-rust`（可能需要 `sudo`）。 + +详细说明见：[`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md)。 + +## 快速开始 + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +cargo build --release --locked +cargo install --path . --force --locked + +# 快速初始化（无交互） +zeroclaw onboard --api-key sk-... --provider openrouter + +# 或使用交互式向导 +zeroclaw onboard --interactive + +# 单次对话 +zeroclaw agent -m "Hello, ZeroClaw!" + +# 启动网关（默认: 127.0.0.1:3000） +zeroclaw gateway + +# 启动长期运行模式 +zeroclaw daemon +``` + +## 安全默认行为（关键） + +- Gateway 默认绑定：`127.0.0.1:3000` +- Gateway 默认要求配对：`require_pairing = true` +- 默认拒绝公网绑定：`allow_public_bind = false` +- Channel allowlist 语义： + - 空列表 `[]` => deny-by-default + - `"*"` => allow all（仅在明确知道风险时使用） + +## 常用配置片段 + +```toml +api_key = "sk-..." +default_provider = "openrouter" +default_model = "anthropic/claude-sonnet-4" +default_temperature = 0.7 + +[memory] +backend = "sqlite" # sqlite | lucid | markdown | none +auto_save = true +embedding_provider = "none" # none | openai | custom:https://... + +[gateway] +host = "127.0.0.1" +port = 3000 +require_pairing = true +allow_public_bind = false +``` + +## 文档导航（推荐从这里开始） + +- 文档总览（英文）：[`docs/README.md`](docs/README.md) +- 统一目录（TOC）：[`docs/SUMMARY.md`](docs/SUMMARY.md) +- 文档总览（简体中文）：[`docs/README.zh-CN.md`](docs/README.zh-CN.md) +- 命令参考：[`docs/commands-reference.md`](docs/commands-reference.md) +- 配置参考：[`docs/config-reference.md`](docs/config-reference.md) +- Provider 参考：[`docs/providers-reference.md`](docs/providers-reference.md) +- Channel 参考：[`docs/channels-reference.md`](docs/channels-reference.md) +- 运维手册：[`docs/operations-runbook.md`](docs/operations-runbook.md) +- 故障排查：[`docs/troubleshooting.md`](docs/troubleshooting.md) +- 文档清单与分类：[`docs/docs-inventory.md`](docs/docs-inventory.md) +- 项目 triage 快照（2026-02-18）：[`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md) + +## 贡献与许可证 + +- 贡献指南：[`CONTRIBUTING.md`](CONTRIBUTING.md) +- PR 工作流：[`docs/pr-workflow.md`](docs/pr-workflow.md) +- Reviewer 指南：[`docs/reviewer-playbook.md`](docs/reviewer-playbook.md) +- 许可证：MIT（见 [`LICENSE`](LICENSE) 与 [`NOTICE`](NOTICE)） + +--- + +如果你需要完整实现细节（架构图、全部命令、完整 API、开发流程），请直接阅读英文主文档：[`README.md`](README.md)。 diff --git a/bootstrap.sh b/bootstrap.sh new file mode 100755 index 0000000..32a5574 --- /dev/null +++ b/bootstrap.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +exec "$ROOT_DIR/scripts/bootstrap.sh" "$@" diff --git a/docs/README.ja.md b/docs/README.ja.md new file mode 100644 index 0000000..aa418b2 --- /dev/null +++ b/docs/README.ja.md @@ -0,0 +1,82 @@ +# ZeroClaw ドキュメントハブ（日本語） + +このページは日本語のドキュメント入口です。 + +最終同期日: **2026-02-18**。 + +> 注: コマンド名・設定キー・API パスは英語のまま記載します。実装の一次情報は英語版ドキュメントを優先してください。 + +## すぐに参照したい項目 + +| やりたいこと | 参照先 | +|---|---| +| すぐにセットアップしたい | [../README.ja.md](../README.ja.md) / [../README.md](../README.md) | +| ワンコマンドで導入したい | [one-click-bootstrap.md](one-click-bootstrap.md) | +| コマンドを用途別に確認したい | [commands-reference.md](commands-reference.md) | +| 設定キーと既定値を確認したい | [config-reference.md](config-reference.md) | +| 日常運用（runbook）を確認したい | [operations-runbook.md](operations-runbook.md) | +| インストール/実行トラブルを解決したい | [troubleshooting.md](troubleshooting.md) | +| 統合 TOC から探したい | [SUMMARY.md](SUMMARY.md) | +| PR/Issue の現状を把握したい | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) | + +## 10秒ルーティング（まずここ） + +- 初回セットアップや導入をしたい → [getting-started/README.md](getting-started/README.md) +- CLI/設定キーを正確に確認したい → [reference/README.md](reference/README.md) +- 本番運用やサービス管理をしたい → [operations/README.md](operations/README.md) +- エラーや不具合を解消したい → [troubleshooting.md](troubleshooting.md) +- セキュリティ方針やロードマップを見たい → [security/README.md](security/README.md) +- ボード/周辺機器を扱いたい → [hardware/README.md](hardware/README.md) +- 貢献・レビュー・CIを確認したい → [contributing/README.md](contributing/README.md) +- 全体マップを見たい → [SUMMARY.md](SUMMARY.md) + +## カテゴリ別ナビゲーション（推奨） + +- 入門: [getting-started/README.md](getting-started/README.md) +- リファレンス: [reference/README.md](reference/README.md) +- 運用 / デプロイ: [operations/README.md](operations/README.md) +- セキュリティ: [security/README.md](security/README.md) +- ハードウェア: [hardware/README.md](hardware/README.md) +- コントリビュート / CI: [contributing/README.md](contributing/README.md) +- プロジェクトスナップショット: [project/README.md](project/README.md) + +## ロール別 + +### ユーザー / オペレーター + +- [commands-reference.md](commands-reference.md) +- [providers-reference.md](providers-reference.md) +- [channels-reference.md](channels-reference.md) +- [config-reference.md](config-reference.md) +- [operations-runbook.md](operations-runbook.md) +- [troubleshooting.md](troubleshooting.md) + +### コントリビューター / メンテナー + +- [../CONTRIBUTING.md](../CONTRIBUTING.md) +- [pr-workflow.md](pr-workflow.md) +- [reviewer-playbook.md](reviewer-playbook.md) +- [ci-map.md](ci-map.md) +- [actions-source-policy.md](actions-source-policy.md) + +### セキュリティ / 信頼性 + +> 注: このセクションには proposal/roadmap 文書が含まれ、想定段階のコマンドや設定が記載される場合があります。現行動作は [config-reference.md](config-reference.md)、[operations-runbook.md](operations-runbook.md)、[troubleshooting.md](troubleshooting.md) を優先してください。 + +- [security/README.md](security/README.md) +- [agnostic-security.md](agnostic-security.md) +- [sandboxing.md](sandboxing.md) +- [resource-limits.md](resource-limits.md) +- [audit-logging.md](audit-logging.md) +- [security-roadmap.md](security-roadmap.md) + +## ドキュメント運用 / 分類 + +- 統合 TOC: [SUMMARY.md](SUMMARY.md) +- ドキュメント一覧 / 分類: [docs-inventory.md](docs-inventory.md) + +## 他言語 + +- English: [README.md](README.md) +- 简体中文: [README.zh-CN.md](README.zh-CN.md) +- Русский: [README.ru.md](README.ru.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8806f1f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,78 @@ +# ZeroClaw Documentation Hub + +This page is the primary entry point for the documentation system. + +Last refreshed: **February 18, 2026**. + +Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Русский](README.ru.md). + +## Start Here + +| I want to… | Read this | +|---|---| +| Install and run ZeroClaw quickly | [README.md (Quick Start)](../README.md#quick-start) | +| Bootstrap in one command | [one-click-bootstrap.md](one-click-bootstrap.md) | +| Find commands by task | [commands-reference.md](commands-reference.md) | +| Check config defaults and keys quickly | [config-reference.md](config-reference.md) | +| Operate runtime (day-2 runbook) | [operations-runbook.md](operations-runbook.md) | +| Troubleshoot install/runtime/channel issues | [troubleshooting.md](troubleshooting.md) | +| Browse docs by category | [SUMMARY.md](SUMMARY.md) | +| See project PR/issue docs snapshot | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) | + +## Quick Decision Tree (10 seconds) + +- Need first-time setup or install? → [getting-started/README.md](getting-started/README.md) +- Need exact CLI/config keys? → [reference/README.md](reference/README.md) +- Need production/service operations? → [operations/README.md](operations/README.md) +- Seeing failures or regressions? → [troubleshooting.md](troubleshooting.md) +- Working on security hardening or roadmap? → [security/README.md](security/README.md) +- Working with boards/peripherals? → [hardware/README.md](hardware/README.md) +- Contributing/reviewing/CI workflow? → [contributing/README.md](contributing/README.md) +- Want the full map? → [SUMMARY.md](SUMMARY.md) + +## Collections (Recommended) + +- Getting started: [getting-started/README.md](getting-started/README.md) +- Reference catalogs: [reference/README.md](reference/README.md) +- Operations & deployment: [operations/README.md](operations/README.md) +- Security docs: [security/README.md](security/README.md) +- Hardware/peripherals: [hardware/README.md](hardware/README.md) +- Contributing/CI: [contributing/README.md](contributing/README.md) +- Project snapshots: [project/README.md](project/README.md) + +## By Audience + +### Users / Operators + +- [commands-reference.md](commands-reference.md) — command lookup by workflow +- [providers-reference.md](providers-reference.md) — provider IDs, aliases, credential env vars +- [channels-reference.md](channels-reference.md) — channel capabilities and setup paths +- [config-reference.md](config-reference.md) — high-signal config keys and secure defaults +- [operations-runbook.md](operations-runbook.md) — day-2 runtime operations and rollback flow +- [troubleshooting.md](troubleshooting.md) — common failure signatures and recovery steps + +### Contributors / Maintainers + +- [../CONTRIBUTING.md](../CONTRIBUTING.md) +- [pr-workflow.md](pr-workflow.md) +- [reviewer-playbook.md](reviewer-playbook.md) +- [ci-map.md](ci-map.md) +- [actions-source-policy.md](actions-source-policy.md) + +### Security / Reliability + +> Note: this area includes proposal/roadmap docs. For current behavior, start with [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + +- [security/README.md](security/README.md) +- [agnostic-security.md](agnostic-security.md) +- [frictionless-security.md](frictionless-security.md) +- [sandboxing.md](sandboxing.md) +- [audit-logging.md](audit-logging.md) +- [resource-limits.md](resource-limits.md) +- [security-roadmap.md](security-roadmap.md) + +## System Navigation & Governance + +- Unified TOC: [SUMMARY.md](SUMMARY.md) +- Documentation inventory/classification: [docs-inventory.md](docs-inventory.md) +- Project triage snapshot: [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) diff --git a/docs/README.ru.md b/docs/README.ru.md new file mode 100644 index 0000000..d1b0f10 --- /dev/null +++ b/docs/README.ru.md @@ -0,0 +1,82 @@ +# Документация ZeroClaw (Русский) + +Эта страница — русскоязычная точка входа в документацию. + +Последняя синхронизация: **2026-02-18**. + +> Примечание: команды, ключи конфигурации и API-пути сохраняются на английском. Для первоисточника ориентируйтесь на англоязычные документы. + +## Быстрые ссылки + +| Что нужно | Куда смотреть | +|---|---| +| Быстро установить и запустить | [../README.ru.md](../README.ru.md) / [../README.md](../README.md) | +| Установить одной командой | [one-click-bootstrap.md](one-click-bootstrap.md) | +| Найти команды по задаче | [commands-reference.md](commands-reference.md) | +| Проверить ключи конфигурации и дефолты | [config-reference.md](config-reference.md) | +| Операционный runbook (day-2) | [operations-runbook.md](operations-runbook.md) | +| Быстро устранить типовые проблемы | [troubleshooting.md](troubleshooting.md) | +| Открыть общий TOC docs | [SUMMARY.md](SUMMARY.md) | +| Посмотреть snapshot PR/Issue | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) | + +## Дерево решений на 10 секунд + +- Нужна первая установка и быстрый старт → [getting-started/README.md](getting-started/README.md) +- Нужны точные команды и ключи конфигурации → [reference/README.md](reference/README.md) +- Нужны операции/сервисный режим/деплой → [operations/README.md](operations/README.md) +- Есть ошибки, сбои или регрессии → [troubleshooting.md](troubleshooting.md) +- Нужны материалы по безопасности и roadmap → [security/README.md](security/README.md) +- Работаете с платами и периферией → [hardware/README.md](hardware/README.md) +- Нужны процессы вклада, ревью и CI → [contributing/README.md](contributing/README.md) +- Нужна полная карта docs → [SUMMARY.md](SUMMARY.md) + +## Навигация по категориям (рекомендуется) + +- Старт и установка: [getting-started/README.md](getting-started/README.md) +- Справочники: [reference/README.md](reference/README.md) +- Операции и деплой: [operations/README.md](operations/README.md) +- Безопасность: [security/README.md](security/README.md) +- Аппаратная часть: [hardware/README.md](hardware/README.md) +- Вклад и CI: [contributing/README.md](contributing/README.md) +- Снимки проекта: [project/README.md](project/README.md) + +## По ролям + +### Пользователи / Операторы + +- [commands-reference.md](commands-reference.md) +- [providers-reference.md](providers-reference.md) +- [channels-reference.md](channels-reference.md) +- [config-reference.md](config-reference.md) +- [operations-runbook.md](operations-runbook.md) +- [troubleshooting.md](troubleshooting.md) + +### Контрибьюторы / Мейнтейнеры + +- [../CONTRIBUTING.md](../CONTRIBUTING.md) +- [pr-workflow.md](pr-workflow.md) +- [reviewer-playbook.md](reviewer-playbook.md) +- [ci-map.md](ci-map.md) +- [actions-source-policy.md](actions-source-policy.md) + +### Безопасность / Надёжность + +> Примечание: часть документов в этом разделе относится к proposal/roadmap и может содержать гипотетические команды/конфигурации. Для текущего поведения сначала смотрите [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), [troubleshooting.md](troubleshooting.md). + +- [security/README.md](security/README.md) +- [agnostic-security.md](agnostic-security.md) +- [sandboxing.md](sandboxing.md) +- [resource-limits.md](resource-limits.md) +- [audit-logging.md](audit-logging.md) +- [security-roadmap.md](security-roadmap.md) + +## Инвентаризация и структура docs + +- Единый TOC: [SUMMARY.md](SUMMARY.md) +- Инвентарь и классификация docs: [docs-inventory.md](docs-inventory.md) + +## Другие языки + +- English: [README.md](README.md) +- 简体中文: [README.zh-CN.md](README.zh-CN.md) +- 日本語: [README.ja.md](README.ja.md) diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md new file mode 100644 index 0000000..e45284d --- /dev/null +++ b/docs/README.zh-CN.md @@ -0,0 +1,82 @@ +# ZeroClaw 文档导航（简体中文） + +这是文档系统的中文入口页。 + +最后对齐：**2026-02-18**。 + +> 说明：命令、配置键、API 路径保持英文；实现细节以英文文档为准。 + +## 快速入口 + +| 我想要… | 建议阅读 | +|---|---| +| 快速安装并运行 | [../README.zh-CN.md](../README.zh-CN.md) / [../README.md](../README.md) | +| 一键安装与初始化 | [one-click-bootstrap.md](one-click-bootstrap.md) | +| 按任务找命令 | [commands-reference.md](commands-reference.md) | +| 快速查看配置默认值与关键项 | [config-reference.md](config-reference.md) | +| 进行日常运维（runbook） | [operations-runbook.md](operations-runbook.md) | +| 快速排查安装/运行问题 | [troubleshooting.md](troubleshooting.md) | +| 统一目录导航 | [SUMMARY.md](SUMMARY.md) | +| 查看 PR/Issue 扫描快照 | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) | + +## 10 秒决策树（先看这个） + +- 首次安装或快速启动 → [getting-started/README.md](getting-started/README.md) +- 需要精确命令或配置键 → [reference/README.md](reference/README.md) +- 需要部署与服务化运维 → [operations/README.md](operations/README.md) +- 遇到报错、异常或回归 → [troubleshooting.md](troubleshooting.md) +- 查看安全现状与路线图 → [security/README.md](security/README.md) +- 接入板卡与外设 → [hardware/README.md](hardware/README.md) +- 参与贡献、评审与 CI → [contributing/README.md](contributing/README.md) +- 查看完整文档地图 → [SUMMARY.md](SUMMARY.md) + +## 按目录浏览（推荐） + +- 入门文档： [getting-started/README.md](getting-started/README.md) +- 参考手册： [reference/README.md](reference/README.md) +- 运维与部署： [operations/README.md](operations/README.md) +- 安全文档： [security/README.md](security/README.md) +- 硬件与外设： [hardware/README.md](hardware/README.md) +- 贡献与 CI： [contributing/README.md](contributing/README.md) +- 项目快照： [project/README.md](project/README.md) + +## 按角色 + +### 用户 / 运维 + +- [commands-reference.md](commands-reference.md) +- [providers-reference.md](providers-reference.md) +- [channels-reference.md](channels-reference.md) +- [config-reference.md](config-reference.md) +- [operations-runbook.md](operations-runbook.md) +- [troubleshooting.md](troubleshooting.md) + +### 贡献者 / 维护者 + +- [../CONTRIBUTING.md](../CONTRIBUTING.md) +- [pr-workflow.md](pr-workflow.md) +- [reviewer-playbook.md](reviewer-playbook.md) +- [ci-map.md](ci-map.md) +- [actions-source-policy.md](actions-source-policy.md) + +### 安全 / 稳定性 + +> 说明：本分组内有 proposal/roadmap 文档，可能包含设想中的命令或配置。当前可执行行为请优先阅读 [config-reference.md](config-reference.md)、[operations-runbook.md](operations-runbook.md)、[troubleshooting.md](troubleshooting.md)。 + +- [security/README.md](security/README.md) +- [agnostic-security.md](agnostic-security.md) +- [sandboxing.md](sandboxing.md) +- [resource-limits.md](resource-limits.md) +- [audit-logging.md](audit-logging.md) +- [security-roadmap.md](security-roadmap.md) + +## 文档治理与分类 + +- 统一目录（TOC）：[SUMMARY.md](SUMMARY.md) +- 文档清单与分类：[docs-inventory.md](docs-inventory.md) + +## 其他语言 + +- English: [README.md](README.md) +- 日本語: [README.ja.md](README.ja.md) +- Русский: [README.ru.md](README.ru.md) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..4cc030c --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,72 @@ +# ZeroClaw Docs Summary (Unified TOC) + +This file is the canonical table of contents for the documentation system. + +Last refreshed: **February 18, 2026**. + +## Language Entry + +- English README: [../README.md](../README.md) +- Chinese README: [../README.zh-CN.md](../README.zh-CN.md) +- Japanese README: [../README.ja.md](../README.ja.md) +- Russian README: [../README.ru.md](../README.ru.md) +- English Docs Hub: [README.md](README.md) +- Chinese Docs Hub: [README.zh-CN.md](README.zh-CN.md) +- Japanese Docs Hub: [README.ja.md](README.ja.md) +- Russian Docs Hub: [README.ru.md](README.ru.md) + +## Collections + +### 1) Getting Started + +- [getting-started/README.md](getting-started/README.md) +- [one-click-bootstrap.md](one-click-bootstrap.md) + +### 2) Command/Config References + +- [reference/README.md](reference/README.md) +- [commands-reference.md](commands-reference.md) +- [providers-reference.md](providers-reference.md) +- [channels-reference.md](channels-reference.md) +- [config-reference.md](config-reference.md) + +### 3) Operations & Deployment + +- [operations/README.md](operations/README.md) +- [operations-runbook.md](operations-runbook.md) +- [troubleshooting.md](troubleshooting.md) +- [network-deployment.md](network-deployment.md) +- [mattermost-setup.md](mattermost-setup.md) + +### 4) Security Design & Proposals + +- [security/README.md](security/README.md) +- [agnostic-security.md](agnostic-security.md) +- [frictionless-security.md](frictionless-security.md) +- [sandboxing.md](sandboxing.md) +- [resource-limits.md](resource-limits.md) +- [audit-logging.md](audit-logging.md) +- [security-roadmap.md](security-roadmap.md) + +### 5) Hardware & Peripherals + +- [hardware/README.md](hardware/README.md) +- [hardware-peripherals-design.md](hardware-peripherals-design.md) +- [adding-boards-and-tools.md](adding-boards-and-tools.md) +- [nucleo-setup.md](nucleo-setup.md) +- [arduino-uno-q-setup.md](arduino-uno-q-setup.md) + +### 6) Contribution & CI + +- [contributing/README.md](contributing/README.md) +- [../CONTRIBUTING.md](../CONTRIBUTING.md) +- [pr-workflow.md](pr-workflow.md) +- [reviewer-playbook.md](reviewer-playbook.md) +- [ci-map.md](ci-map.md) +- [actions-source-policy.md](actions-source-policy.md) + +### 7) Project Status & Snapshot + +- [project/README.md](project/README.md) +- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) +- [docs-inventory.md](docs-inventory.md) diff --git a/docs/adding-boards-and-tools.md b/docs/adding-boards-and-tools.md index a7e9eaa..071c133 100644 --- a/docs/adding-boards-and-tools.md +++ b/docs/adding-boards-and-tools.md @@ -11,7 +11,7 @@ zeroclaw peripheral add arduino-uno /dev/cu.usbmodem12345 zeroclaw peripheral add rpi-gpio native # for Raspberry Pi GPIO (Linux) # Restart daemon to apply -zeroclaw daemon --host 127.0.0.1 --port 8080 +zeroclaw daemon --host 127.0.0.1 --port 3000 ``` ## Supported Boards diff --git a/docs/agnostic-security.md b/docs/agnostic-security.md index 7ed0273..5c6213a 100644 --- a/docs/agnostic-security.md +++ b/docs/agnostic-security.md @@ -1,5 +1,10 @@ # Agnostic Security: Zero Impact on Portability +> ⚠️ **Status: Proposal / Roadmap** +> +> This document describes proposed approaches and may include hypothetical commands or config. +> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + ## Core Question: Will security features break... 1. ❓ Fast cross-compilation builds? 2. ❓ Pluggable architecture (swap anything)? diff --git a/docs/arduino-uno-q-setup.md b/docs/arduino-uno-q-setup.md index 8e170e8..dcd5aac 100644 --- a/docs/arduino-uno-q-setup.md +++ b/docs/arduino-uno-q-setup.md @@ -130,7 +130,7 @@ allowed_users = ["*"] [gateway] host = "127.0.0.1" -port = 8080 +port = 3000 allow_public_bind = false [agent] @@ -145,7 +145,7 @@ compact_context = true ssh arduino@ # Run daemon (Telegram polling works over WiFi) -zeroclaw daemon --host 127.0.0.1 --port 8080 +zeroclaw daemon --host 127.0.0.1 --port 3000 ``` **At this point:** Telegram chat works. Send messages to your bot — ZeroClaw responds. No GPIO yet. @@ -184,7 +184,7 @@ transport = "bridge" ### 5.3 Run ZeroClaw ```bash -zeroclaw daemon --host 127.0.0.1 --port 8080 +zeroclaw daemon --host 127.0.0.1 --port 3000 ``` Now when you message your Telegram bot *"Turn on the LED"* or *"Set pin 13 high"*, ZeroClaw uses `gpio_write` via the Bridge. @@ -203,7 +203,7 @@ Now when you message your Telegram bot *"Turn on the LED"* or *"Set pin 13 high" | 6 | `cargo build --release --no-default-features` | | 7 | `zeroclaw onboard --api-key KEY --provider openrouter` | | 8 | Edit `~/.zeroclaw/config.toml` (add Telegram bot_token) | -| 9 | `zeroclaw daemon --host 127.0.0.1 --port 8080` | +| 9 | `zeroclaw daemon --host 127.0.0.1 --port 3000` | | 10 | Message your Telegram bot — it responds | --- diff --git a/docs/audit-logging.md b/docs/audit-logging.md index 8871adb..fc44d67 100644 --- a/docs/audit-logging.md +++ b/docs/audit-logging.md @@ -1,5 +1,10 @@ # Audit Logging for ZeroClaw +> ⚠️ **Status: Proposal / Roadmap** +> +> This document describes proposed approaches and may include hypothetical commands or config. +> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + ## Problem ZeroClaw logs actions but lacks tamper-evident audit trails for: - Who executed what command diff --git a/docs/channels-reference.md b/docs/channels-reference.md new file mode 100644 index 0000000..066840f --- /dev/null +++ b/docs/channels-reference.md @@ -0,0 +1,105 @@ +# ZeroClaw Channels Reference + +This reference maps channel capabilities, config blocks, allowlist behavior, and setup paths. + +Last verified: **February 18, 2026**. + +## Quick Commands + +```bash +zeroclaw channel list +zeroclaw channel start +zeroclaw channel doctor +zeroclaw channel bind-telegram +``` + +## Channel Matrix + +| Channel | Config section | Access control field | Setup path | +|---|---|---|---| +| `CLI` | n/a (always enabled) | n/a | Built-in | +| `Telegram` | `[channels_config.telegram]` | `allowed_users` | `zeroclaw onboard` | +| `Discord` | `[channels_config.discord]` | `allowed_users` | `zeroclaw onboard` | +| `Slack` | `[channels_config.slack]` | `allowed_users` | `zeroclaw onboard` | +| `Mattermost` | `[channels_config.mattermost]` | `allowed_users` | Manual config | +| `Webhook` | `[channels_config.webhook]` | n/a (`secret` optional) | `zeroclaw onboard` or manual | +| `iMessage` | `[channels_config.imessage]` | `allowed_contacts` | `zeroclaw onboard` (macOS) | +| `Matrix` | `[channels_config.matrix]` | `allowed_users` | `zeroclaw onboard` | +| `Signal` | `[channels_config.signal]` | `allowed_from` | Manual config | +| `WhatsApp` | `[channels_config.whatsapp]` | `allowed_numbers` | `zeroclaw onboard` | +| `Email` | `[channels_config.email]` | `allowed_senders` | Manual config | +| `IRC` | `[channels_config.irc]` | `allowed_users` | `zeroclaw onboard` | +| `Lark` | `[channels_config.lark]` | `allowed_users` | Manual config | +| `DingTalk` | `[channels_config.dingtalk]` | `allowed_users` | `zeroclaw onboard` | +| `QQ` | `[channels_config.qq]` | `allowed_users` | `zeroclaw onboard` | + +## Deny-by-Default Rules + +For channel allowlists, the runtime behavior is intentionally strict: + +- Empty allowlist (`[]`) means **deny all**. +- Wildcard (`["*"]`) means **allow all**. +- Explicit IDs are exact matches unless channel-specific docs state otherwise. + +### Telegram pairing bootstrap + +Telegram has a secure bootstrap flow: + +- Keep `allowed_users = []` to start in pairing mode. +- Run `zeroclaw channel bind-telegram ` to add one identity safely. +- After binding, restart long-running channel processes if needed (`daemon` / `channel start`). + +## Minimal Config Examples + +### Telegram + +```toml +[channels_config.telegram] +bot_token = "123456:ABCDEF" +allowed_users = [] +``` + +### WhatsApp + +```toml +[channels_config.whatsapp] +access_token = "EAABx..." +phone_number_id = "123456789012345" +verify_token = "your-verify-token" +allowed_numbers = ["+1234567890"] +``` + +### Signal + +```toml +[channels_config.signal] +http_url = "http://127.0.0.1:8686" +account = "+1234567890" +allowed_from = ["+1987654321"] +ignore_attachments = true +ignore_stories = true +``` + +### Lark + +```toml +[channels_config.lark] +app_id = "cli_xxx" +app_secret = "xxx" +allowed_users = ["ou_abc"] +receive_mode = "websocket" # or "webhook" +# port = 3100 # required only when receive_mode = "webhook" +``` + +## Operational Notes + +- `zeroclaw channel add/remove` is intentionally not a full config mutator yet; use `zeroclaw onboard` or edit `~/.zeroclaw/config.toml`. +- `zeroclaw channel doctor` validates configured channel health and prints timeout/unhealthy status. +- If `webhook` is configured, doctor guidance points to gateway health check (`GET /health`). + +## Related Docs + +- [README.md (Channel allowlists)](../README.md#channel-allowlists-deny-by-default) +- [network-deployment.md](network-deployment.md) +- [mattermost-setup.md](mattermost-setup.md) +- [commands-reference.md](commands-reference.md) diff --git a/docs/commands-reference.md b/docs/commands-reference.md new file mode 100644 index 0000000..7b685ec --- /dev/null +++ b/docs/commands-reference.md @@ -0,0 +1,121 @@ +# ZeroClaw Commands Reference + +This reference is derived from the current CLI surface (`zeroclaw --help`). + +Last verified: **February 18, 2026**. + +## Top-Level Commands + +| Command | Purpose | +|---|---| +| `onboard` | Initialize workspace/config quickly or interactively | +| `agent` | Run interactive chat or single-message mode | +| `gateway` | Start webhook and WhatsApp HTTP gateway | +| `daemon` | Start supervised runtime (gateway + channels + optional heartbeat/scheduler) | +| `service` | Manage user-level OS service lifecycle | +| `doctor` | Run diagnostics and freshness checks | +| `status` | Print current configuration and system summary | +| `cron` | Manage scheduled tasks | +| `models` | Refresh provider model catalogs | +| `providers` | List provider IDs, aliases, and active provider | +| `channel` | Manage channels and channel health checks | +| `integrations` | Inspect integration details | +| `skills` | List/install/remove skills | +| `migrate` | Import from external runtimes (currently OpenClaw) | +| `hardware` | Discover and introspect USB hardware | +| `peripheral` | Configure and flash peripherals | + +## Command Groups + +### `onboard` + +- `zeroclaw onboard` +- `zeroclaw onboard --interactive` +- `zeroclaw onboard --channels-only` +- `zeroclaw onboard --api-key --provider --memory ` + +### `agent` + +- `zeroclaw agent` +- `zeroclaw agent -m "Hello"` +- `zeroclaw agent --provider --model --temperature <0.0-2.0>` +- `zeroclaw agent --peripheral ` + +### `gateway` / `daemon` + +- `zeroclaw gateway [--host ] [--port ]` +- `zeroclaw daemon [--host ] [--port ]` + +### `service` + +- `zeroclaw service install` +- `zeroclaw service start` +- `zeroclaw service stop` +- `zeroclaw service status` +- `zeroclaw service uninstall` + +### `cron` + +- `zeroclaw cron list` +- `zeroclaw cron add [--tz ] ` +- `zeroclaw cron add-at ` +- `zeroclaw cron add-every ` +- `zeroclaw cron once ` +- `zeroclaw cron remove ` +- `zeroclaw cron pause ` +- `zeroclaw cron resume ` + +### `models` + +- `zeroclaw models refresh` +- `zeroclaw models refresh --provider ` +- `zeroclaw models refresh --force` + +### `channel` + +- `zeroclaw channel list` +- `zeroclaw channel start` +- `zeroclaw channel doctor` +- `zeroclaw channel bind-telegram ` +- `zeroclaw channel add ` +- `zeroclaw channel remove ` + +`add/remove` currently route you back to managed setup/manual config paths (not full declarative mutators yet). + +### `integrations` + +- `zeroclaw integrations info ` + +### `skills` + +- `zeroclaw skills list` +- `zeroclaw skills install ` +- `zeroclaw skills remove ` + +### `migrate` + +- `zeroclaw migrate openclaw [--source ] [--dry-run]` + +### `hardware` + +- `zeroclaw hardware discover` +- `zeroclaw hardware introspect ` +- `zeroclaw hardware info [--chip ]` + +### `peripheral` + +- `zeroclaw peripheral list` +- `zeroclaw peripheral add ` +- `zeroclaw peripheral flash [--port ]` +- `zeroclaw peripheral setup-uno-q [--host ]` +- `zeroclaw peripheral flash-nucleo` + +## Validation Tip + +To verify docs against your current binary quickly: + +```bash +zeroclaw --help +zeroclaw --help +``` + diff --git a/docs/config-reference.md b/docs/config-reference.md new file mode 100644 index 0000000..46fc65f --- /dev/null +++ b/docs/config-reference.md @@ -0,0 +1,72 @@ +# ZeroClaw Config Reference (Operator-Oriented) + +This is a high-signal reference for common config sections and defaults. + +Last verified: **February 18, 2026**. + +Config file path: + +- `~/.zeroclaw/config.toml` + +## Core Keys + +| Key | Default | Notes | +|---|---|---| +| `default_provider` | `openrouter` | provider ID or alias | +| `default_model` | `anthropic/claude-sonnet-4` | model routed through selected provider | +| `default_temperature` | `0.7` | model temperature | + +## `[gateway]` + +| Key | Default | Purpose | +|---|---|---| +| `host` | `127.0.0.1` | bind address | +| `port` | `3000` | gateway listen port | +| `require_pairing` | `true` | require pairing before bearer auth | +| `allow_public_bind` | `false` | block accidental public exposure | + +## `[memory]` + +| Key | Default | Purpose | +|---|---|---| +| `backend` | `sqlite` | `sqlite`, `lucid`, `markdown`, `none` | +| `auto_save` | `true` | automatic persistence | +| `embedding_provider` | `none` | `none`, `openai`, or custom endpoint | +| `vector_weight` | `0.7` | hybrid ranking vector weight | +| `keyword_weight` | `0.3` | hybrid ranking keyword weight | + +## `[channels_config]` + +Top-level channel options are configured under `channels_config`. + +Examples: + +- `[channels_config.telegram]` +- `[channels_config.discord]` +- `[channels_config.whatsapp]` +- `[channels_config.email]` + +See detailed channel matrix and allowlist behavior in [channels-reference.md](channels-reference.md). + +## Security-Relevant Defaults + +- deny-by-default channel allowlists (`[]` means deny all) +- pairing required on gateway by default +- public bind disabled by default + +## Validation Commands + +After editing config: + +```bash +zeroclaw status +zeroclaw doctor +zeroclaw channel doctor +``` + +## Related Docs + +- [channels-reference.md](channels-reference.md) +- [providers-reference.md](providers-reference.md) +- [operations-runbook.md](operations-runbook.md) +- [troubleshooting.md](troubleshooting.md) diff --git a/docs/contributing/README.md b/docs/contributing/README.md new file mode 100644 index 0000000..fba915e --- /dev/null +++ b/docs/contributing/README.md @@ -0,0 +1,18 @@ +# Contributing, Review, and CI Docs + +For contributors, reviewers, and maintainers. + +## Core Policies + +- Contribution guide: [../../CONTRIBUTING.md](../../CONTRIBUTING.md) +- PR workflow rules: [../pr-workflow.md](../pr-workflow.md) +- Reviewer playbook: [../reviewer-playbook.md](../reviewer-playbook.md) +- CI map and ownership: [../ci-map.md](../ci-map.md) +- Actions source policy: [../actions-source-policy.md](../actions-source-policy.md) + +## Suggested Reading Order + +1. `CONTRIBUTING.md` +2. `docs/pr-workflow.md` +3. `docs/reviewer-playbook.md` +4. `docs/ci-map.md` diff --git a/docs/docs-inventory.md b/docs/docs-inventory.md new file mode 100644 index 0000000..99027eb --- /dev/null +++ b/docs/docs-inventory.md @@ -0,0 +1,95 @@ +# ZeroClaw Documentation Inventory + +This inventory classifies docs by intent so readers can quickly distinguish runtime-contract guides from design proposals. + +Last reviewed: **February 18, 2026**. + +## Classification Legend + +- **Current Guide/Reference**: intended to match current runtime behavior +- **Policy/Process**: collaboration or governance rules +- **Proposal/Roadmap**: design exploration; may include hypothetical commands +- **Snapshot**: time-bound operational report + +## Documentation Entry Points + +| Doc | Type | Audience | +|---|---|---| +| `README.md` | Current Guide | all readers | +| `README.zh-CN.md` | Current Guide (localized) | Chinese readers | +| `README.ja.md` | Current Guide (localized) | Japanese readers | +| `README.ru.md` | Current Guide (localized) | Russian readers | +| `docs/README.md` | Current Guide (hub) | all readers | +| `docs/README.zh-CN.md` | Current Guide (localized hub) | Chinese readers | +| `docs/README.ja.md` | Current Guide (localized hub) | Japanese readers | +| `docs/README.ru.md` | Current Guide (localized hub) | Russian readers | +| `docs/SUMMARY.md` | Current Guide (unified TOC) | all readers | + +## Collection Index Docs + +| Doc | Type | Audience | +|---|---|---| +| `docs/getting-started/README.md` | Current Guide | new users | +| `docs/reference/README.md` | Current Guide | users/operators | +| `docs/operations/README.md` | Current Guide | operators | +| `docs/security/README.md` | Current Guide | operators/contributors | +| `docs/hardware/README.md` | Current Guide | hardware builders | +| `docs/contributing/README.md` | Current Guide | contributors/reviewers | +| `docs/project/README.md` | Current Guide | maintainers | + +## Current Guides & References + +| Doc | Type | Audience | +|---|---|---| +| `docs/one-click-bootstrap.md` | Current Guide | users/operators | +| `docs/commands-reference.md` | Current Reference | users/operators | +| `docs/providers-reference.md` | Current Reference | users/operators | +| `docs/channels-reference.md` | Current Reference | users/operators | +| `docs/config-reference.md` | Current Reference | operators | +| `docs/operations-runbook.md` | Current Guide | operators | +| `docs/troubleshooting.md` | Current Guide | users/operators | +| `docs/network-deployment.md` | Current Guide | operators | +| `docs/mattermost-setup.md` | Current Guide | operators | +| `docs/adding-boards-and-tools.md` | Current Guide | hardware builders | +| `docs/arduino-uno-q-setup.md` | Current Guide | hardware builders | +| `docs/nucleo-setup.md` | Current Guide | hardware builders | +| `docs/hardware-peripherals-design.md` | Current Design Spec | hardware contributors | +| `docs/langgraph-integration.md` | Current Integration Guide | integration developers | + +## Policy / Process Docs + +| Doc | Type | +|---|---| +| `docs/pr-workflow.md` | Policy | +| `docs/reviewer-playbook.md` | Process | +| `docs/ci-map.md` | Process | +| `docs/actions-source-policy.md` | Policy | + +## Proposal / Roadmap Docs + +These are valuable context, but **not strict runtime contracts**. + +| Doc | Type | +|---|---| +| `docs/sandboxing.md` | Proposal | +| `docs/resource-limits.md` | Proposal | +| `docs/audit-logging.md` | Proposal | +| `docs/agnostic-security.md` | Proposal | +| `docs/frictionless-security.md` | Proposal | +| `docs/security-roadmap.md` | Roadmap | + +## Snapshot Docs + +| Doc | Type | +|---|---| +| `docs/project-triage-snapshot-2026-02-18.md` | Snapshot | + +## Maintenance Recommendations + +1. Update `commands-reference` whenever CLI surface changes. +2. Update `providers-reference` when provider catalog/aliases/env vars change. +3. Update `channels-reference` when channel support or allowlist semantics change. +4. Keep snapshots date-stamped and immutable. +5. Mark proposal docs clearly to avoid being mistaken for runtime contracts. +6. Keep localized README/docs-hub links aligned when adding new core docs. +7. Update `docs/SUMMARY.md` and collection indexes whenever new major docs are added. diff --git a/docs/frictionless-security.md b/docs/frictionless-security.md index d23dbfc..2f5fde6 100644 --- a/docs/frictionless-security.md +++ b/docs/frictionless-security.md @@ -1,5 +1,10 @@ # Frictionless Security: Zero Impact on Wizard +> ⚠️ **Status: Proposal / Roadmap** +> +> This document describes proposed approaches and may include hypothetical commands or config. +> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + ## Core Principle > **"Security features should be like airbags — present, protective, and invisible until needed."** diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md new file mode 100644 index 0000000..e462641 --- /dev/null +++ b/docs/getting-started/README.md @@ -0,0 +1,20 @@ +# Getting Started Docs + +For first-time setup and quick orientation. + +## Start Path + +1. Main overview and quick start: [../../README.md](../../README.md) +2. One-click setup and dual bootstrap mode: [../one-click-bootstrap.md](../one-click-bootstrap.md) +3. Find commands by tasks: [../commands-reference.md](../commands-reference.md) + +## Onboarding and Validation + +- Quick onboarding: `zeroclaw onboard --api-key "sk-..." --provider openrouter` +- Interactive onboarding: `zeroclaw onboard --interactive` +- Validate environment: `zeroclaw status` + `zeroclaw doctor` + +## Next + +- Runtime operations: [../operations/README.md](../operations/README.md) +- Reference catalogs: [../reference/README.md](../reference/README.md) diff --git a/docs/hardware/README.md b/docs/hardware/README.md new file mode 100644 index 0000000..6db982e --- /dev/null +++ b/docs/hardware/README.md @@ -0,0 +1,14 @@ +# Hardware & Peripherals Docs + +For board integration, firmware flow, and peripheral architecture. + +## Entry Points + +- Architecture and peripheral model: [../hardware-peripherals-design.md](../hardware-peripherals-design.md) +- Add a new board/tool: [../adding-boards-and-tools.md](../adding-boards-and-tools.md) +- Nucleo setup: [../nucleo-setup.md](../nucleo-setup.md) +- Arduino Uno R4 WiFi setup: [../arduino-uno-q-setup.md](../arduino-uno-q-setup.md) + +## Datasheets + +- Board/chip datasheets: [../datasheets](../datasheets) diff --git a/docs/mattermost-setup.md b/docs/mattermost-setup.md index 4b17b88..3833aab 100644 --- a/docs/mattermost-setup.md +++ b/docs/mattermost-setup.md @@ -18,10 +18,10 @@ ZeroClaw supports native integration with Mattermost via its REST API v4. This i ## Configuration -Add the following to your `config.toml` under the `[channels]` section: +Add the following to your `config.toml` under the `[channels_config]` section: ```toml -[channels.mattermost] +[channels_config.mattermost] url = "https://mm.your-domain.com" bot_token = "your-bot-access-token" channel_id = "your-channel-id" diff --git a/docs/network-deployment.md b/docs/network-deployment.md index 54a7694..e2f65b9 100644 --- a/docs/network-deployment.md +++ b/docs/network-deployment.md @@ -59,14 +59,14 @@ allowed_users = [] [gateway] host = "127.0.0.1" -port = 8080 +port = 3000 allow_public_bind = false ``` ### 2.4 Run Daemon (Local Only) ```bash -zeroclaw daemon --host 127.0.0.1 --port 8080 +zeroclaw daemon --host 127.0.0.1 --port 3000 ``` - Gateway binds to `127.0.0.1` — not reachable from other machines @@ -84,12 +84,12 @@ To allow other devices on your LAN to hit the gateway (e.g. for pairing or webho ```toml [gateway] host = "0.0.0.0" -port = 8080 +port = 3000 allow_public_bind = true ``` ```bash -zeroclaw daemon --host 0.0.0.0 --port 8080 +zeroclaw daemon --host 0.0.0.0 --port 3000 ``` **Security:** `allow_public_bind = true` exposes the gateway to your local network. Only use on trusted LANs. @@ -100,7 +100,7 @@ If you need a **public URL** (e.g. WhatsApp webhook, external clients): 1. Run gateway on localhost: ```bash - zeroclaw daemon --host 127.0.0.1 --port 8080 + zeroclaw daemon --host 127.0.0.1 --port 3000 ``` 2. Start a tunnel: @@ -177,13 +177,13 @@ provider = "ngrok" Or run ngrok manually: ```bash -ngrok http 8080 +ngrok http 3000 # Use the HTTPS URL for your webhook ``` ### 5.3 Cloudflare Tunnel -Configure Cloudflare Tunnel to forward to `127.0.0.1:8080`, then set your webhook URL to the tunnel's public hostname. +Configure Cloudflare Tunnel to forward to `127.0.0.1:3000`, then set your webhook URL to the tunnel's public hostname. --- @@ -191,7 +191,7 @@ Configure Cloudflare Tunnel to forward to `127.0.0.1:8080`, then set your webhoo - [ ] Build with `--features hardware` (and `peripheral-rpi` if using native GPIO) - [ ] Configure `[peripherals]` and `[channels_config.telegram]` -- [ ] Run `zeroclaw daemon --host 127.0.0.1 --port 8080` (Telegram works without 0.0.0.0) +- [ ] Run `zeroclaw daemon --host 127.0.0.1 --port 3000` (Telegram works without 0.0.0.0) - [ ] For LAN access: `--host 0.0.0.0` + `allow_public_bind = true` in config - [ ] For webhooks: use Tailscale, ngrok, or Cloudflare tunnel diff --git a/docs/nucleo-setup.md b/docs/nucleo-setup.md index 76e942e..a617b4f 100644 --- a/docs/nucleo-setup.md +++ b/docs/nucleo-setup.md @@ -113,7 +113,7 @@ baud = 115200 ## Phase 4: Run and Test ```bash -zeroclaw daemon --host 127.0.0.1 --port 8080 +zeroclaw daemon --host 127.0.0.1 --port 3000 ``` Or use the agent directly: @@ -131,7 +131,7 @@ Pin 13 = PA5 = User LED (LD2) on Nucleo-F401RE. | Step | Command | |------|---------| | 1 | Connect Nucleo via USB | -| 2 | `cargo install probe-rs --locked` | +| 2 | `cargo install probe-rs-tools --locked` | | 3 | `zeroclaw peripheral flash-nucleo` | | 4 | Add Nucleo to config.toml (path = your serial port) | | 5 | `zeroclaw daemon` or `zeroclaw agent -m "Turn on LED"` | diff --git a/docs/one-click-bootstrap.md b/docs/one-click-bootstrap.md new file mode 100644 index 0000000..0cc8b7c --- /dev/null +++ b/docs/one-click-bootstrap.md @@ -0,0 +1,92 @@ +# One-Click Bootstrap + +This page defines the fastest supported path to install and initialize ZeroClaw. + +Last verified: **February 18, 2026**. + +## Option A (Recommended): Clone + local script + +```bash +git clone https://github.com/zeroclaw-labs/zeroclaw.git +cd zeroclaw +./bootstrap.sh +``` + +What it does by default: + +1. `cargo build --release --locked` +2. `cargo install --path . --force --locked` + +## Dual-mode bootstrap + +Default behavior is **app-only** (build/install ZeroClaw) and expects existing Rust toolchain. + +For fresh machines, enable environment bootstrap explicitly: + +```bash +./bootstrap.sh --install-system-deps --install-rust +``` + +Notes: + +- `--install-system-deps` installs compiler/build prerequisites (may require `sudo`). +- `--install-rust` installs Rust via `rustup` when missing. + +## Option B: Remote one-liner + +```bash +curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash +``` + +For high-security environments, prefer Option A so you can review the script before execution. + +Legacy compatibility: + +```bash +curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash +``` + +This legacy endpoint prefers forwarding to `scripts/bootstrap.sh` and falls back to legacy source install if unavailable in that revision. + +If you run Option B outside a repository checkout, the bootstrap script automatically clones a temporary workspace, builds, installs, and then cleans it up. + +## Optional onboarding modes + +### Quick onboarding (non-interactive) + +```bash +./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter +``` + +Or with environment variables: + +```bash +ZEROCLAW_API_KEY="sk-..." ZEROCLAW_PROVIDER="openrouter" ./bootstrap.sh --onboard +``` + +### Interactive onboarding + +```bash +./bootstrap.sh --interactive-onboard +``` + +## Useful flags + +- `--install-system-deps` +- `--install-rust` +- `--skip-build` +- `--skip-install` +- `--provider ` + +See all options: + +```bash +./bootstrap.sh --help +``` + +## Related docs + +- [README.md](../README.md) +- [commands-reference.md](commands-reference.md) +- [providers-reference.md](providers-reference.md) +- [channels-reference.md](channels-reference.md) diff --git a/docs/operations-runbook.md b/docs/operations-runbook.md new file mode 100644 index 0000000..9eb740f --- /dev/null +++ b/docs/operations-runbook.md @@ -0,0 +1,128 @@ +# ZeroClaw Operations Runbook + +This runbook is for operators who maintain availability, security posture, and incident response. + +Last verified: **February 18, 2026**. + +## Scope + +Use this document for day-2 operations: + +- starting and supervising runtime +- health checks and diagnostics +- safe rollout and rollback +- incident triage and recovery + +For first-time installation, start from [one-click-bootstrap.md](one-click-bootstrap.md). + +## Runtime Modes + +| Mode | Command | When to use | +|---|---|---| +| Foreground runtime | `zeroclaw daemon` | local debugging, short-lived sessions | +| Foreground gateway only | `zeroclaw gateway` | webhook endpoint testing | +| User service | `zeroclaw service install && zeroclaw service start` | persistent operator-managed runtime | + +## Baseline Operator Checklist + +1. Validate configuration: + +```bash +zeroclaw status +``` + +2. Verify diagnostics: + +```bash +zeroclaw doctor +zeroclaw channel doctor +``` + +3. Start runtime: + +```bash +zeroclaw daemon +``` + +4. For persistent user session service: + +```bash +zeroclaw service install +zeroclaw service start +zeroclaw service status +``` + +## Health and State Signals + +| Signal | Command / File | Expected | +|---|---|---| +| Config validity | `zeroclaw doctor` | no critical errors | +| Channel connectivity | `zeroclaw channel doctor` | configured channels healthy | +| Runtime summary | `zeroclaw status` | expected provider/model/channels | +| Daemon heartbeat/state | `~/.zeroclaw/daemon_state.json` | file updates periodically | + +## Logs and Diagnostics + +### macOS / Windows (service wrapper logs) + +- `~/.zeroclaw/logs/daemon.stdout.log` +- `~/.zeroclaw/logs/daemon.stderr.log` + +### Linux (systemd user service) + +```bash +journalctl --user -u zeroclaw.service -f +``` + +## Incident Triage Flow (Fast Path) + +1. Snapshot system state: + +```bash +zeroclaw status +zeroclaw doctor +zeroclaw channel doctor +``` + +2. Check service state: + +```bash +zeroclaw service status +``` + +3. If service is unhealthy, restart cleanly: + +```bash +zeroclaw service stop +zeroclaw service start +``` + +4. If channels still fail, verify allowlists and credentials in `~/.zeroclaw/config.toml`. + +5. If gateway is involved, verify bind/auth settings (`[gateway]`) and local reachability. + +## Safe Change Procedure + +Before applying config changes: + +1. backup `~/.zeroclaw/config.toml` +2. apply one logical change at a time +3. run `zeroclaw doctor` +4. restart daemon/service +5. verify with `status` + `channel doctor` + +## Rollback Procedure + +If a rollout regresses behavior: + +1. restore previous `config.toml` +2. restart runtime (`daemon` or `service`) +3. confirm recovery via `doctor` and channel health checks +4. document incident root cause and mitigation + +## Related Docs + +- [one-click-bootstrap.md](one-click-bootstrap.md) +- [troubleshooting.md](troubleshooting.md) +- [config-reference.md](config-reference.md) +- [commands-reference.md](commands-reference.md) diff --git a/docs/operations/README.md b/docs/operations/README.md new file mode 100644 index 0000000..b208d20 --- /dev/null +++ b/docs/operations/README.md @@ -0,0 +1,23 @@ +# Operations & Deployment Docs + +For operators running ZeroClaw in persistent or production-like environments. + +## Core Operations + +- Day-2 runbook: [../operations-runbook.md](../operations-runbook.md) +- Troubleshooting matrix: [../troubleshooting.md](../troubleshooting.md) +- Safe network/gateway deployment: [../network-deployment.md](../network-deployment.md) +- Mattermost setup (channel-specific): [../mattermost-setup.md](../mattermost-setup.md) + +## Common Flow + +1. Validate runtime (`status`, `doctor`, `channel doctor`) +2. Apply one config change at a time +3. Restart service/daemon +4. Verify channel and gateway health +5. Roll back quickly if behavior regresses + +## Related + +- Config reference: [../config-reference.md](../config-reference.md) +- Security collection: [../security/README.md](../security/README.md) diff --git a/docs/project-triage-snapshot-2026-02-18.md b/docs/project-triage-snapshot-2026-02-18.md new file mode 100644 index 0000000..e608196 --- /dev/null +++ b/docs/project-triage-snapshot-2026-02-18.md @@ -0,0 +1,94 @@ +# ZeroClaw Project Triage Snapshot (2026-02-18) + +As-of date: **February 18, 2026**. + +This snapshot captures open PR/issue signals to guide docs and information-architecture work. + +## Data Source + +Collected via GitHub CLI against `zeroclaw-labs/zeroclaw`: + +- `gh repo view ...` +- `gh pr list --state open --limit 500 ...` +- `gh issue list --state open --limit 500 ...` +- `gh pr/issue view ...` for docs-relevant items + +## Repository Pulse + +- Open PRs: **30** +- Open Issues: **24** +- Stars: **11,220** +- Forks: **1,123** +- Default branch: `main` +- License metadata on GitHub API: `Other` (not MIT-detected) + +## PR Label Pressure (Open PRs) + +Top signals by frequency: + +1. `risk: high` — 24 +2. `experienced contributor` — 14 +3. `size: S` — 14 +4. `ci` — 11 +5. `size: XS` — 10 +6. `dependencies` — 7 +7. `principal contributor` — 6 + +Implication for docs: + +- CI/security/service changes remain high-churn areas. +- Operator-facing docs should prioritize “what changed” visibility and fast troubleshooting paths. + +## Issue Label Pressure (Open Issues) + +Top signals by frequency: + +1. `experienced contributor` — 12 +2. `enhancement` — 8 +3. `bug` — 4 + +Implication for docs: + +- Feature and performance requests still outpace explanatory docs. +- Troubleshooting and operational references should be kept near the top navigation. + +## Docs-Relevant Open PRs + +- [#716](https://github.com/zeroclaw-labs/zeroclaw/pull/716) — OpenRC support (service behavior/docs impact) +- [#725](https://github.com/zeroclaw-labs/zeroclaw/pull/725) — shell completion commands (CLI docs impact) +- [#732](https://github.com/zeroclaw-labs/zeroclaw/pull/732) — CI action replacement (contributor workflow docs impact) +- [#759](https://github.com/zeroclaw-labs/zeroclaw/pull/759) — daemon/channel response handling fix (channel troubleshooting impact) +- [#679](https://github.com/zeroclaw-labs/zeroclaw/pull/679) — pairing lockout accounting change (security behavior docs impact) + +## Docs-Relevant Open Issues + +- [#426](https://github.com/zeroclaw-labs/zeroclaw/issues/426) — explicit request for clearer capabilities documentation +- [#666](https://github.com/zeroclaw-labs/zeroclaw/issues/666) — operational runbook and alert/logging guidance request +- [#745](https://github.com/zeroclaw-labs/zeroclaw/issues/745) — Docker pull failure (`ghcr.io`) suggests deployment troubleshooting demand +- [#761](https://github.com/zeroclaw-labs/zeroclaw/issues/761) — Armbian compile error highlights platform troubleshooting needs +- [#758](https://github.com/zeroclaw-labs/zeroclaw/issues/758) — storage backend flexibility request impacts config/reference docs + +## Recommended Docs Backlog (Priority Order) + +1. **Keep docs IA stable and obvious** + - Maintain `docs/SUMMARY.md` + collection indexes as canonical nav. + - Keep localized hubs aligned with the same top-level doc map. + +2. **Protect operator discoverability** + - Keep `operations-runbook` + `troubleshooting` linked in top-level README/hubs. + - Add platform-specific troubleshooting snippets when issues repeat. + +3. **Track CLI/config drift aggressively** + - Update `commands/providers/channels/config` references when PRs touching these surfaces merge. + +4. **Separate current behavior from proposals** + - Preserve proposal banners in security roadmap docs. + - Keep runtime-contract docs (`config/runbook/troubleshooting`) clearly marked. + +5. **Maintain snapshot discipline** + - Keep snapshots date-stamped and immutable. + - Create a new snapshot file for each docs sprint instead of mutating historical snapshots. + +## Snapshot Caveat + +This is a time-bound snapshot (2026-02-18). Re-run the `gh` queries before planning a new documentation sprint. diff --git a/docs/project/README.md b/docs/project/README.md new file mode 100644 index 0000000..392a1d0 --- /dev/null +++ b/docs/project/README.md @@ -0,0 +1,13 @@ +# Project Snapshot & Triage Docs + +Time-bound project status snapshots for planning documentation and operations work. + +## Current Snapshot + +- [../project-triage-snapshot-2026-02-18.md](../project-triage-snapshot-2026-02-18.md) + +## Scope + +Use snapshots to understand changing PR/issue pressure and prioritize doc maintenance. + +For stable classification of docs intent, use [../docs-inventory.md](../docs-inventory.md). diff --git a/docs/providers-reference.md b/docs/providers-reference.md new file mode 100644 index 0000000..f30c110 --- /dev/null +++ b/docs/providers-reference.md @@ -0,0 +1,89 @@ +# ZeroClaw Providers Reference + +This document maps provider IDs, aliases, and credential environment variables. + +Last verified: **February 18, 2026**. + +## How to List Providers + +```bash +zeroclaw providers +``` + +## Credential Resolution Order + +Runtime resolution order is: + +1. Explicit credential from config/CLI +2. Provider-specific env var(s) +3. Generic fallback env vars: `ZEROCLAW_API_KEY` then `API_KEY` + +## Provider Catalog + +| Canonical ID | Aliases | Local | Provider-specific env var(s) | +|---|---|---:|---| +| `openrouter` | — | No | `OPENROUTER_API_KEY` | +| `anthropic` | — | No | `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` | +| `openai` | — | No | `OPENAI_API_KEY` | +| `ollama` | — | Yes | `OLLAMA_API_KEY` (optional) | +| `gemini` | `google`, `google-gemini` | No | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| `venice` | — | No | `VENICE_API_KEY` | +| `vercel` | `vercel-ai` | No | `VERCEL_API_KEY` | +| `cloudflare` | `cloudflare-ai` | No | `CLOUDFLARE_API_KEY` | +| `moonshot` | `kimi` | No | `MOONSHOT_API_KEY` | +| `synthetic` | — | No | `SYNTHETIC_API_KEY` | +| `opencode` | `opencode-zen` | No | `OPENCODE_API_KEY` | +| `zai` | `z.ai` | No | `ZAI_API_KEY` | +| `glm` | `zhipu` | No | `GLM_API_KEY` | +| `minimax` | — | No | `MINIMAX_API_KEY` | +| `bedrock` | `aws-bedrock` | No | (use config/`API_KEY` fallback) | +| `qianfan` | `baidu` | No | `QIANFAN_API_KEY` | +| `qwen` | `dashscope`, `qwen-intl`, `dashscope-intl`, `qwen-us`, `dashscope-us` | No | `DASHSCOPE_API_KEY` | +| `groq` | — | No | `GROQ_API_KEY` | +| `mistral` | — | No | `MISTRAL_API_KEY` | +| `xai` | `grok` | No | `XAI_API_KEY` | +| `deepseek` | — | No | `DEEPSEEK_API_KEY` | +| `together` | `together-ai` | No | `TOGETHER_API_KEY` | +| `fireworks` | `fireworks-ai` | No | `FIREWORKS_API_KEY` | +| `perplexity` | — | No | `PERPLEXITY_API_KEY` | +| `cohere` | — | No | `COHERE_API_KEY` | +| `copilot` | `github-copilot` | No | (use config/`API_KEY` fallback with GitHub token) | +| `lmstudio` | `lm-studio` | Yes | (optional; local by default) | +| `nvidia` | `nvidia-nim`, `build.nvidia.com` | No | `NVIDIA_API_KEY` | + +## Custom Endpoints + +- OpenAI-compatible endpoint: + +```toml +default_provider = "custom:https://your-api.example.com" +``` + +- Anthropic-compatible endpoint: + +```toml +default_provider = "anthropic-custom:https://your-api.example.com" +``` + +## Model Routing (`hint:`) + +You can route model calls by hint using `[[model_routes]]`: + +```toml +[[model_routes]] +hint = "reasoning" +provider = "openrouter" +model = "anthropic/claude-opus-4-20250514" + +[[model_routes]] +hint = "fast" +provider = "groq" +model = "llama-3.3-70b-versatile" +``` + +Then call with a hint model name (for example from tool or integration paths): + +```text +hint:reasoning +``` + diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000..391d624 --- /dev/null +++ b/docs/reference/README.md @@ -0,0 +1,14 @@ +# Reference Catalogs + +Structured reference index for commands, providers, channels, and config. + +## Core References + +- Commands by workflow: [../commands-reference.md](../commands-reference.md) +- Provider IDs / aliases / env vars: [../providers-reference.md](../providers-reference.md) +- Channel setup + allowlists: [../channels-reference.md](../channels-reference.md) +- Config defaults and keys: [../config-reference.md](../config-reference.md) + +## Usage + +Use this collection when you need precise CLI/config details rather than step-by-step tutorials. diff --git a/docs/resource-limits.md b/docs/resource-limits.md index e3834fc..4b85977 100644 --- a/docs/resource-limits.md +++ b/docs/resource-limits.md @@ -1,5 +1,10 @@ # Resource Limits for ZeroClaw +> ⚠️ **Status: Proposal / Roadmap** +> +> This document describes proposed approaches and may include hypothetical commands or config. +> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + ## Problem ZeroClaw has rate limiting (20 actions/hour) but no resource caps. A runaway agent could: - Exhaust available memory diff --git a/docs/sandboxing.md b/docs/sandboxing.md index 06abf59..4e0d905 100644 --- a/docs/sandboxing.md +++ b/docs/sandboxing.md @@ -1,5 +1,10 @@ # ZeroClaw Sandboxing Strategies +> ⚠️ **Status: Proposal / Roadmap** +> +> This document describes proposed approaches and may include hypothetical commands or config. +> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + ## Problem ZeroClaw currently has application-layer security (allowlists, path blocking, command injection protection) but lacks OS-level containment. If an attacker is on the allowlist, they can run any allowed command with zeroclaw's user permissions. diff --git a/docs/security-roadmap.md b/docs/security-roadmap.md index 6578d1f..8b57908 100644 --- a/docs/security-roadmap.md +++ b/docs/security-roadmap.md @@ -1,5 +1,10 @@ # ZeroClaw Security Improvement Roadmap +> ⚠️ **Status: Proposal / Roadmap** +> +> This document describes proposed approaches and may include hypothetical commands or config. +> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md). + ## Current State: Strong Foundation ZeroClaw already has **excellent application-layer security**: diff --git a/docs/security/README.md b/docs/security/README.md new file mode 100644 index 0000000..bc50ade --- /dev/null +++ b/docs/security/README.md @@ -0,0 +1,22 @@ +# Security Docs + +This section mixes current hardening guidance and proposal/roadmap documents. + +## Current-Behavior First + +For current runtime behavior, start here: + +- Config reference: [../config-reference.md](../config-reference.md) +- Operations runbook: [../operations-runbook.md](../operations-runbook.md) +- Troubleshooting: [../troubleshooting.md](../troubleshooting.md) + +## Proposal / Roadmap Docs + +The following docs are explicitly proposal-oriented and may include hypothetical CLI/config examples: + +- [../agnostic-security.md](../agnostic-security.md) +- [../frictionless-security.md](../frictionless-security.md) +- [../sandboxing.md](../sandboxing.md) +- [../resource-limits.md](../resource-limits.md) +- [../audit-logging.md](../audit-logging.md) +- [../security-roadmap.md](../security-roadmap.md) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..e06e74a --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,154 @@ +# ZeroClaw Troubleshooting + +This guide focuses on common setup/runtime failures and fast resolution paths. + +Last verified: **February 18, 2026**. + +## Installation / Bootstrap + +### `cargo` not found + +Symptom: + +- bootstrap exits with `cargo is not installed` + +Fix: + +```bash +./bootstrap.sh --install-rust +``` + +Or install from . + +### Missing system build dependencies + +Symptom: + +- build fails due to compiler or `pkg-config` issues + +Fix: + +```bash +./bootstrap.sh --install-system-deps +``` + +### `zeroclaw` command not found after install + +Symptom: + +- install succeeds but shell cannot find `zeroclaw` + +Fix: + +```bash +export PATH="$HOME/.cargo/bin:$PATH" +which zeroclaw +``` + +Persist in your shell profile if needed. + +## Runtime / Gateway + +### Gateway unreachable + +Checks: + +```bash +zeroclaw status +zeroclaw doctor +``` + +Verify `~/.zeroclaw/config.toml`: + +- `[gateway].host` (default `127.0.0.1`) +- `[gateway].port` (default `3000`) +- `allow_public_bind` only when intentionally exposing LAN/public interfaces + +### Pairing / auth failures on webhook + +Checks: + +1. Ensure pairing completed (`/pair` flow) +2. Ensure bearer token is current +3. Re-run diagnostics: + +```bash +zeroclaw doctor +``` + +## Channel Issues + +### Telegram conflict: `terminated by other getUpdates request` + +Cause: + +- multiple pollers using same bot token + +Fix: + +- keep only one active runtime for that token +- stop extra `zeroclaw daemon` / `zeroclaw channel start` processes + +### Channel unhealthy in `channel doctor` + +Checks: + +```bash +zeroclaw channel doctor +``` + +Then verify channel-specific credentials + allowlist fields in config. + +## Service Mode + +### Service installed but not running + +Checks: + +```bash +zeroclaw service status +``` + +Recovery: + +```bash +zeroclaw service stop +zeroclaw service start +``` + +Linux logs: + +```bash +journalctl --user -u zeroclaw.service -f +``` + +## Legacy Installer Compatibility + +Both still work: + +```bash +curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash +curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash +``` + +`install.sh` is a compatibility entry and forwards/falls back to bootstrap behavior. + +## Still Stuck? + +Collect and include these outputs when filing an issue: + +```bash +zeroclaw --version +zeroclaw status +zeroclaw doctor +zeroclaw channel doctor +``` + +Also include OS, install method, and sanitized config snippets (no secrets). + +## Related Docs + +- [operations-runbook.md](operations-runbook.md) +- [one-click-bootstrap.md](one-click-bootstrap.md) +- [channels-reference.md](channels-reference.md) +- [network-deployment.md](network-deployment.md) diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh new file mode 100755 index 0000000..09c7140 --- /dev/null +++ b/scripts/bootstrap.sh @@ -0,0 +1,314 @@ +#!/usr/bin/env bash +set -euo pipefail + +info() { + echo "==> $*" +} + +warn() { + echo "warning: $*" >&2 +} + +error() { + echo "error: $*" >&2 +} + +usage() { + cat <<'USAGE' +ZeroClaw one-click bootstrap + +Usage: + ./bootstrap.sh [options] + +Modes: + Default mode installs/builds ZeroClaw only (requires existing Rust toolchain). + Optional bootstrap mode can also install system dependencies and Rust. + +Options: + --install-system-deps Install build dependencies (Linux/macOS) + --install-rust Install Rust via rustup if missing + --onboard Run onboarding after install + --interactive-onboard Run interactive onboarding (implies --onboard) + --api-key API key for non-interactive onboarding + --provider Provider for non-interactive onboarding (default: openrouter) + --skip-build Skip `cargo build --release --locked` + --skip-install Skip `cargo install --path . --force --locked` + -h, --help Show help + +Examples: + ./bootstrap.sh + ./bootstrap.sh --install-system-deps --install-rust + ./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter + ./bootstrap.sh --interactive-onboard + + # Remote one-liner + curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash + +Environment: + ZEROCLAW_API_KEY Used when --api-key is not provided + ZEROCLAW_PROVIDER Used when --provider is not provided (default: openrouter) +USAGE +} + +have_cmd() { + command -v "$1" >/dev/null 2>&1 +} + +run_privileged() { + if [[ "$(id -u)" -eq 0 ]]; then + "$@" + elif have_cmd sudo; then + sudo "$@" + else + error "sudo is required to install system dependencies." + return 1 + fi +} + +install_system_deps() { + info "Installing system dependencies" + + case "$(uname -s)" in + Linux) + if have_cmd apt-get; then + run_privileged apt-get update -qq + run_privileged apt-get install -y build-essential pkg-config git curl + elif have_cmd dnf; then + run_privileged dnf groupinstall -y "Development Tools" + run_privileged dnf install -y pkg-config git curl + else + warn "Unsupported Linux distribution. Install compiler toolchain + pkg-config + git + curl manually." + fi + ;; + Darwin) + if ! xcode-select -p >/dev/null 2>&1; then + info "Installing Xcode Command Line Tools" + xcode-select --install || true + cat <<'MSG' +Please complete the Xcode Command Line Tools installation dialog, +then re-run bootstrap. +MSG + exit 0 + fi + if ! have_cmd git; then + warn "git is not available. Install git (e.g., Homebrew) and re-run bootstrap." + fi + ;; + *) + warn "Unsupported OS for automatic dependency install. Continuing without changes." + ;; + esac +} + +install_rust_toolchain() { + if have_cmd cargo && have_cmd rustc; then + info "Rust already installed: $(rustc --version)" + return + fi + + if ! have_cmd curl; then + error "curl is required to install Rust via rustup." + exit 1 + fi + + info "Installing Rust via rustup" + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y + + if [[ -f "$HOME/.cargo/env" ]]; then + # shellcheck disable=SC1090 + source "$HOME/.cargo/env" + fi + + if ! have_cmd cargo; then + error "Rust installation completed but cargo is still unavailable in PATH." + error "Run: source \"$HOME/.cargo/env\"" + exit 1 + fi +} + +SCRIPT_PATH="${BASH_SOURCE[0]:-$0}" +SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" >/dev/null 2>&1 && pwd || pwd)" +ROOT_DIR="$(cd "$SCRIPT_DIR/.." >/dev/null 2>&1 && pwd || pwd)" +REPO_URL="https://github.com/zeroclaw-labs/zeroclaw.git" + +INSTALL_SYSTEM_DEPS=false +INSTALL_RUST=false +RUN_ONBOARD=false +INTERACTIVE_ONBOARD=false +SKIP_BUILD=false +SKIP_INSTALL=false +API_KEY="${ZEROCLAW_API_KEY:-}" +PROVIDER="${ZEROCLAW_PROVIDER:-openrouter}" + +while [[ $# -gt 0 ]]; do + case "$1" in + --install-system-deps) + INSTALL_SYSTEM_DEPS=true + shift + ;; + --install-rust) + INSTALL_RUST=true + shift + ;; + --onboard) + RUN_ONBOARD=true + shift + ;; + --interactive-onboard) + RUN_ONBOARD=true + INTERACTIVE_ONBOARD=true + shift + ;; + --api-key) + API_KEY="${2:-}" + [[ -n "$API_KEY" ]] || { + error "--api-key requires a value" + exit 1 + } + shift 2 + ;; + --provider) + PROVIDER="${2:-}" + [[ -n "$PROVIDER" ]] || { + error "--provider requires a value" + exit 1 + } + shift 2 + ;; + --skip-build) + SKIP_BUILD=true + shift + ;; + --skip-install) + SKIP_INSTALL=true + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + error "unknown option: $1" + echo + usage + exit 1 + ;; + esac +done + +if [[ "$INSTALL_SYSTEM_DEPS" == true ]]; then + install_system_deps +fi + +if [[ "$INSTALL_RUST" == true ]]; then + install_rust_toolchain +fi + +if ! have_cmd cargo; then + error "cargo is not installed." + cat <<'MSG' >&2 +Install Rust first: https://rustup.rs/ +or re-run with: + ./bootstrap.sh --install-rust +MSG + exit 1 +fi + +WORK_DIR="$ROOT_DIR" +TEMP_CLONE=false +TEMP_DIR="" + +cleanup() { + if [[ "$TEMP_CLONE" == true && -n "$TEMP_DIR" && -d "$TEMP_DIR" ]]; then + rm -rf "$TEMP_DIR" + fi +} +trap cleanup EXIT + +# Support three launch modes: +# 1) ./bootstrap.sh from repo root +# 2) scripts/bootstrap.sh from repo +# 3) curl | bash (no local repo => temporary clone) +if [[ ! -f "$WORK_DIR/Cargo.toml" ]]; then + if [[ -f "$(pwd)/Cargo.toml" ]]; then + WORK_DIR="$(pwd)" + else + if ! have_cmd git; then + error "git is required when running bootstrap outside a local repository checkout." + if [[ "$INSTALL_SYSTEM_DEPS" == false ]]; then + error "Re-run with --install-system-deps or install git manually." + fi + exit 1 + fi + + TEMP_DIR="$(mktemp -d -t zeroclaw-bootstrap-XXXXXX)" + info "No local repository detected; cloning latest main branch" + git clone --depth 1 "$REPO_URL" "$TEMP_DIR" + WORK_DIR="$TEMP_DIR" + TEMP_CLONE=true + fi +fi + +info "ZeroClaw bootstrap" +echo " workspace: $WORK_DIR" + +cd "$WORK_DIR" + +if [[ "$SKIP_BUILD" == false ]]; then + info "Building release binary" + cargo build --release --locked +else + info "Skipping build" +fi + +if [[ "$SKIP_INSTALL" == false ]]; then + info "Installing zeroclaw to cargo bin" + cargo install --path "$WORK_DIR" --force --locked +else + info "Skipping install" +fi + +ZEROCLAW_BIN="" +if have_cmd zeroclaw; then + ZEROCLAW_BIN="zeroclaw" +elif [[ -x "$WORK_DIR/target/release/zeroclaw" ]]; then + ZEROCLAW_BIN="$WORK_DIR/target/release/zeroclaw" +fi + +if [[ "$RUN_ONBOARD" == true ]]; then + if [[ -z "$ZEROCLAW_BIN" ]]; then + error "onboarding requested but zeroclaw binary is not available." + error "Run without --skip-install, or ensure zeroclaw is in PATH." + exit 1 + fi + + if [[ "$INTERACTIVE_ONBOARD" == true ]]; then + info "Running interactive onboarding" + "$ZEROCLAW_BIN" onboard --interactive + else + if [[ -z "$API_KEY" ]]; then + cat <<'MSG' +==> Onboarding requested, but API key not provided. +Use either: + --api-key "sk-..." +or: + ZEROCLAW_API_KEY="sk-..." ./bootstrap.sh --onboard +or run interactive: + ./bootstrap.sh --interactive-onboard +MSG + exit 1 + fi + info "Running quick onboarding (provider: $PROVIDER)" + "$ZEROCLAW_BIN" onboard --api-key "$API_KEY" --provider "$PROVIDER" + fi +fi + +cat <<'DONE' + +✅ Bootstrap complete. + +Next steps: + zeroclaw status + zeroclaw agent -m "Hello, ZeroClaw!" + zeroclaw gateway +DONE diff --git a/scripts/install.sh b/scripts/install.sh old mode 100644 new mode 100755 index a6a7f51..68efa95 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -1,151 +1,58 @@ #!/usr/bin/env bash -# install.sh — Build and install ZeroClaw from source. -# Usage: -# curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash -# # or -# bash scripts/install.sh - set -euo pipefail -# --- Logging -------------------------------------------------------------- +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd || pwd)" +BOOTSTRAP_LOCAL="$SCRIPT_DIR/bootstrap.sh" +REPO_URL="https://github.com/zeroclaw-labs/zeroclaw.git" -info() { printf ">>> %s\n" "$*"; } -warn() { printf ">>> [WARN] %s\n" "$*"; } -error() { printf ">>> [ERROR] %s\n" "$*" >&2; } -die() { error "$@"; exit 1; } +echo "[deprecated] scripts/install.sh -> bootstrap.sh" >&2 -# --- Step 1: Detect OS and install system dependencies -------------------- +if [[ -f "$BOOTSTRAP_LOCAL" ]]; then + exec "$BOOTSTRAP_LOCAL" "$@" +fi -install_system_deps() { - info "Detecting operating system..." - - local os - os="$(uname -s)" - - case "${os}" in - Linux) - install_linux_deps - ;; - Darwin) - install_macos_deps - ;; - *) - die "Unsupported operating system: ${os}. Only Linux and macOS are supported." - ;; - esac -} - -install_linux_deps() { - if command -v apt-get >/dev/null 2>&1; then - info "Detected Debian/Ubuntu — installing build-essential, pkg-config, git..." - sudo apt-get update -qq - sudo apt-get install -y build-essential pkg-config git - elif command -v dnf >/dev/null 2>&1; then - info "Detected Fedora/RHEL — installing Development Tools, pkg-config, git..." - sudo dnf groupinstall -y "Development Tools" - sudo dnf install -y pkg-config git - else - die "Unsupported Linux distribution. Please install a C compiler, pkg-config, and git manually, then re-run this script." - fi -} - -install_macos_deps() { - if ! xcode-select -p >/dev/null 2>&1; then - info "Installing Xcode Command Line Tools..." - xcode-select --install - warn "A dialog may have appeared. Please complete the Xcode CLT installation, then re-run this script." - exit 0 - else - info "Xcode Command Line Tools already installed." - fi - - if ! command -v git >/dev/null 2>&1; then - die "git not found. Please install git (e.g. via Homebrew) and re-run this script." - fi -} - -# --- Step 2: Install Rust ------------------------------------------------- - -install_rust() { - if command -v rustc >/dev/null 2>&1; then - info "Rust already installed ($(rustc --version))." - else - info "Installing Rust via rustup..." - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y - # shellcheck source=/dev/null - source "${HOME}/.cargo/env" - info "Rust installed ($(rustc --version))." - fi -} - -# --- Step 3: Clone repository --------------------------------------------- - -CLONE_DIR="/tmp/zeroclaw-install" - -clone_repo() { - if [ -d "${CLONE_DIR}" ]; then - info "Removing previous clone at ${CLONE_DIR}..." - rm -rf "${CLONE_DIR}" - fi - - info "Cloning ZeroClaw repository..." - git clone --depth 1 https://github.com/zeroclaw-labs/zeroclaw.git "${CLONE_DIR}" -} - -# --- Step 4: Build and install -------------------------------------------- - -build_and_install() { - info "Building ZeroClaw (release mode)..." - cargo build --release --locked --manifest-path "${CLONE_DIR}/Cargo.toml" - - info "Installing ZeroClaw binary..." - cargo install --path "${CLONE_DIR}" --force --locked -} - -# --- Step 5: Cleanup ------------------------------------------------------ +if ! command -v git >/dev/null 2>&1; then + echo "error: git is required for legacy install.sh remote mode" >&2 + exit 1 +fi +TEMP_DIR="$(mktemp -d -t zeroclaw-install-XXXXXX)" cleanup() { - info "Cleaning up build directory..." - rm -rf "${CLONE_DIR}" + rm -rf "$TEMP_DIR" } +trap cleanup EXIT -# --- Step 6: Success message ---------------------------------------------- +git clone --depth 1 "$REPO_URL" "$TEMP_DIR" >/dev/null 2>&1 -print_success() { - echo "" - info "ZeroClaw installed successfully!" - echo "" - echo " To use zeroclaw in your current shell, run:" - echo "" - echo " source \"\${HOME}/.cargo/env\"" - echo "" - echo " To make it permanent, add the line above to your shell profile" - echo " (~/.bashrc, ~/.zshrc, etc.)." - echo "" - echo " Then get started:" - echo "" - echo " zeroclaw onboard" - echo "" -} +if [[ -x "$TEMP_DIR/scripts/bootstrap.sh" ]]; then + "$TEMP_DIR/scripts/bootstrap.sh" "$@" + exit 0 +fi -# --- Main ----------------------------------------------------------------- +echo "[deprecated] cloned revision has no bootstrap.sh; falling back to legacy source install flow" >&2 -main() { - echo "" - info "ZeroClaw — Source Install" - echo "" +if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then + cat <<'USAGE' +Legacy install.sh fallback mode - install_system_deps - echo "" - install_rust - echo "" - clone_repo - echo "" - build_and_install - echo "" - cleanup - echo "" - print_success -} +Behavior: + - Clone repository + - cargo build --release --locked + - cargo install --path --force --locked -main \ No newline at end of file +For the new dual-mode installer, use: + ./bootstrap.sh --help +USAGE + exit 0 +fi + +if ! command -v cargo >/dev/null 2>&1; then + echo "error: cargo is required for legacy install.sh fallback mode" >&2 + echo "Install Rust first: https://rustup.rs/" >&2 + exit 1 +fi + +cargo build --release --locked --manifest-path "$TEMP_DIR/Cargo.toml" +cargo install --path "$TEMP_DIR" --force --locked + +echo "Legacy source install completed." >&2