feat: refactor sgclaw around zeroclaw compat runtime
This commit is contained in:
zyl
24
third_party/zeroclaw/docs/ops/README.md
vendored
Normal file
24
third_party/zeroclaw/docs/ops/README.md
vendored
Normal file
@@ -0,0 +1,24 @@
|
||||
# Operations & Deployment Docs
|
||||
|
||||
For operators running ZeroClaw in persistent or production-like environments.
|
||||
|
||||
## Core Operations
|
||||
|
||||
- Day-2 runbook: [./operations-runbook.md](./operations-runbook.md)
|
||||
- Release runbook: [../contributing/release-process.md](../contributing/release-process.md)
|
||||
- Troubleshooting matrix: [./troubleshooting.md](./troubleshooting.md)
|
||||
- Safe network/gateway deployment: [./network-deployment.md](./network-deployment.md)
|
||||
- Mattermost setup (channel-specific): [../setup-guides/mattermost-setup.md](../setup-guides/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: [../reference/api/config-reference.md](../reference/api/config-reference.md)
|
||||
- Security collection: [../security/README.md](../security/README.md)
|
||||
305
third_party/zeroclaw/docs/ops/network-deployment.md
vendored
Normal file
305
third_party/zeroclaw/docs/ops/network-deployment.md
vendored
Normal file
@@ -0,0 +1,305 @@
|
||||
# Network Deployment — ZeroClaw on Raspberry Pi and Local Network
|
||||
|
||||
This document covers deploying ZeroClaw on a Raspberry Pi or other host on your local network, with Telegram and optional webhook channels.
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
| Mode | Inbound port needed? | Use case |
|
||||
|------|----------------------|----------|
|
||||
| **Telegram polling** | No | ZeroClaw polls Telegram API; works from anywhere |
|
||||
| **Matrix sync (including E2EE)** | No | ZeroClaw syncs via Matrix client API; no inbound webhook required |
|
||||
| **Discord/Slack** | No | Same — outbound only |
|
||||
| **Nostr** | No | Connects to relays via WebSocket; outbound only |
|
||||
| **Gateway webhook** | Yes | POST /webhook, /whatsapp, /linq, /nextcloud-talk need a public URL |
|
||||
| **Gateway pairing** | Yes | If you pair clients via the gateway |
|
||||
| **Alpine/OpenRC service** | No | System-wide background service on Alpine Linux |
|
||||
|
||||
**Key:** Telegram, Discord, Slack, and Nostr use **outbound connections** — ZeroClaw connects to external servers/relays. No port forwarding or public IP required.
|
||||
|
||||
---
|
||||
|
||||
## 2. ZeroClaw on Raspberry Pi
|
||||
|
||||
### 2.1 Prerequisites
|
||||
|
||||
- Raspberry Pi (3/4/5) with Raspberry Pi OS
|
||||
- USB peripherals (Arduino, Nucleo) if using serial transport
|
||||
- Optional: `rppal` for native GPIO (`peripheral-rpi` feature)
|
||||
|
||||
### 2.2 Install
|
||||
|
||||
```bash
|
||||
# Build for RPi (or cross-compile from host)
|
||||
cargo build --release --features hardware
|
||||
|
||||
# Or install via your preferred method
|
||||
```
|
||||
|
||||
### 2.3 Config
|
||||
|
||||
Edit `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
[peripherals]
|
||||
enabled = true
|
||||
|
||||
[[peripherals.boards]]
|
||||
board = "rpi-gpio"
|
||||
transport = "native"
|
||||
|
||||
# Or Arduino over USB
|
||||
[[peripherals.boards]]
|
||||
board = "arduino-uno"
|
||||
transport = "serial"
|
||||
path = "/dev/ttyACM0"
|
||||
baud = 115200
|
||||
|
||||
[channels_config.telegram]
|
||||
bot_token = "YOUR_BOT_TOKEN"
|
||||
allowed_users = []
|
||||
|
||||
[gateway]
|
||||
host = "127.0.0.1"
|
||||
port = 42617
|
||||
allow_public_bind = false
|
||||
```
|
||||
|
||||
### 2.4 Run Daemon (Local Only)
|
||||
|
||||
```bash
|
||||
zeroclaw daemon --host 127.0.0.1 --port 42617
|
||||
```
|
||||
|
||||
- Gateway binds to `127.0.0.1` — not reachable from other machines
|
||||
- Telegram channel works: ZeroClaw polls Telegram API (outbound)
|
||||
- No firewall or port forwarding needed
|
||||
|
||||
---
|
||||
|
||||
## 3. Binding to 0.0.0.0 (Local Network)
|
||||
|
||||
To allow other devices on your LAN to hit the gateway (e.g. for pairing or webhooks):
|
||||
|
||||
### 3.1 Option A: Explicit Opt-In
|
||||
|
||||
```toml
|
||||
[gateway]
|
||||
host = "0.0.0.0"
|
||||
port = 42617
|
||||
allow_public_bind = true
|
||||
```
|
||||
|
||||
```bash
|
||||
zeroclaw daemon --host 0.0.0.0 --port 42617
|
||||
```
|
||||
|
||||
**Security:** `allow_public_bind = true` exposes the gateway to your local network. Only use on trusted LANs.
|
||||
|
||||
### 3.2 Option B: Tunnel (Recommended for Webhooks)
|
||||
|
||||
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 42617
|
||||
```
|
||||
|
||||
2. Start a tunnel:
|
||||
```toml
|
||||
[tunnel]
|
||||
provider = "tailscale" # or "ngrok", "cloudflare"
|
||||
```
|
||||
Or use `zeroclaw tunnel` (see tunnel docs).
|
||||
|
||||
3. ZeroClaw will refuse `0.0.0.0` unless `allow_public_bind = true` or a tunnel is active.
|
||||
|
||||
---
|
||||
|
||||
## 4. Telegram Polling (No Inbound Port)
|
||||
|
||||
Telegram uses **long-polling** by default:
|
||||
|
||||
- ZeroClaw calls `https://api.telegram.org/bot{token}/getUpdates`
|
||||
- No inbound port or public IP needed
|
||||
- Works behind NAT, on RPi, in a home lab
|
||||
|
||||
**Config:**
|
||||
|
||||
```toml
|
||||
[channels_config.telegram]
|
||||
bot_token = "YOUR_BOT_TOKEN"
|
||||
allowed_users = [] # deny-by-default, bind identities explicitly
|
||||
```
|
||||
|
||||
Run `zeroclaw daemon` — Telegram channel starts automatically.
|
||||
|
||||
To approve one Telegram account at runtime:
|
||||
|
||||
```bash
|
||||
zeroclaw channel bind-telegram <IDENTITY>
|
||||
```
|
||||
|
||||
`<IDENTITY>` can be a numeric Telegram user ID or a username (without `@`).
|
||||
|
||||
### 4.1 Single Poller Rule (Important)
|
||||
|
||||
Telegram Bot API `getUpdates` supports only one active poller per bot token.
|
||||
|
||||
- Keep one runtime instance for the same token (recommended: `zeroclaw daemon` service).
|
||||
- Do not run `cargo run -- channel start` or another bot process at the same time.
|
||||
|
||||
If you hit this error:
|
||||
|
||||
`Conflict: terminated by other getUpdates request`
|
||||
|
||||
you have a polling conflict. Stop extra instances and restart only one daemon.
|
||||
|
||||
---
|
||||
|
||||
## 5. Webhook Channels (WhatsApp, Nextcloud Talk, Custom)
|
||||
|
||||
Webhook-based channels need a **public URL** so Meta (WhatsApp) or your client can POST events.
|
||||
|
||||
### 5.1 Tailscale Funnel
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
provider = "tailscale"
|
||||
```
|
||||
|
||||
Tailscale Funnel exposes your gateway via a `*.ts.net` URL. No port forwarding.
|
||||
|
||||
### 5.2 ngrok
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
provider = "ngrok"
|
||||
```
|
||||
|
||||
Or run ngrok manually:
|
||||
```bash
|
||||
ngrok http 42617
|
||||
# Use the HTTPS URL for your webhook
|
||||
```
|
||||
|
||||
### 5.3 Cloudflare Tunnel
|
||||
|
||||
Configure Cloudflare Tunnel to forward to `127.0.0.1:42617`, then set your webhook URL to the tunnel's public hostname.
|
||||
|
||||
---
|
||||
|
||||
## 6. Checklist: RPi Deployment
|
||||
|
||||
- [ ] 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 42617` (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
|
||||
|
||||
---
|
||||
|
||||
## 7. OpenRC (Alpine Linux Service)
|
||||
|
||||
ZeroClaw supports OpenRC for Alpine Linux and other distributions using the OpenRC init system. OpenRC services run **system-wide** and require root/sudo.
|
||||
|
||||
### 7.1 Prerequisites
|
||||
|
||||
- Alpine Linux (or another OpenRC-based distro)
|
||||
- Root or sudo access
|
||||
- A dedicated `zeroclaw` system user (created during install)
|
||||
|
||||
### 7.2 Install Service
|
||||
|
||||
```bash
|
||||
# Install service (OpenRC is auto-detected on Alpine)
|
||||
sudo zeroclaw service install
|
||||
```
|
||||
|
||||
This creates:
|
||||
- Init script: `/etc/init.d/zeroclaw`
|
||||
- Config directory: `/etc/zeroclaw/`
|
||||
- Log directory: `/var/log/zeroclaw/`
|
||||
|
||||
### 7.3 Configuration
|
||||
|
||||
Manual config copy is usually not required.
|
||||
|
||||
`sudo zeroclaw service install` automatically prepares `/etc/zeroclaw`, migrates existing runtime state from your user setup when available, and sets ownership/permissions for the `zeroclaw` service user.
|
||||
|
||||
If no prior runtime state is available to migrate, create `/etc/zeroclaw/config.toml` before starting the service.
|
||||
|
||||
### 7.4 Enable and Start
|
||||
|
||||
```bash
|
||||
# Add to default runlevel
|
||||
sudo rc-update add zeroclaw default
|
||||
|
||||
# Start the service
|
||||
sudo rc-service zeroclaw start
|
||||
|
||||
# Check status
|
||||
sudo rc-service zeroclaw status
|
||||
```
|
||||
|
||||
### 7.5 Manage Service
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `sudo rc-service zeroclaw start` | Start the daemon |
|
||||
| `sudo rc-service zeroclaw stop` | Stop the daemon |
|
||||
| `sudo rc-service zeroclaw status` | Check service status |
|
||||
| `sudo rc-service zeroclaw restart` | Restart the daemon |
|
||||
| `sudo zeroclaw service status` | ZeroClaw status wrapper (uses `/etc/zeroclaw` config) |
|
||||
|
||||
### 7.6 Logs
|
||||
|
||||
OpenRC routes logs to:
|
||||
|
||||
| Log | Path |
|
||||
|-----|------|
|
||||
| Access/stdout | `/var/log/zeroclaw/access.log` |
|
||||
| Errors/stderr | `/var/log/zeroclaw/error.log` |
|
||||
|
||||
View logs:
|
||||
|
||||
```bash
|
||||
sudo tail -f /var/log/zeroclaw/error.log
|
||||
```
|
||||
|
||||
### 7.7 Uninstall
|
||||
|
||||
```bash
|
||||
# Stop and remove from runlevel
|
||||
sudo rc-service zeroclaw stop
|
||||
sudo rc-update del zeroclaw default
|
||||
|
||||
# Remove init script
|
||||
sudo zeroclaw service uninstall
|
||||
```
|
||||
|
||||
### 7.8 Notes
|
||||
|
||||
- OpenRC is **system-wide only** (no user-level services)
|
||||
- Requires `sudo` or root for all service operations
|
||||
- The service runs as the `zeroclaw:zeroclaw` user (least privilege)
|
||||
- Config must be at `/etc/zeroclaw/config.toml` (explicit path in init script)
|
||||
- If the `zeroclaw` user does not exist, install will fail with instructions to create it
|
||||
|
||||
### 7.9 Checklist: Alpine/OpenRC Deployment
|
||||
|
||||
- [ ] Install: `sudo zeroclaw service install`
|
||||
- [ ] Enable: `sudo rc-update add zeroclaw default`
|
||||
- [ ] Start: `sudo rc-service zeroclaw start`
|
||||
- [ ] Verify: `sudo rc-service zeroclaw status`
|
||||
- [ ] Check logs: `/var/log/zeroclaw/error.log`
|
||||
|
||||
---
|
||||
|
||||
## 8. References
|
||||
|
||||
- [channels-reference.md](../reference/api/channels-reference.md) — Channel configuration overview
|
||||
- [matrix-e2ee-guide.md](../security/matrix-e2ee-guide.md) — Matrix setup and encrypted-room troubleshooting
|
||||
- [hardware-peripherals-design.md](../hardware/hardware-peripherals-design.md) — Peripherals design
|
||||
- [adding-boards-and-tools.md](../contributing/adding-boards-and-tools.md) — Hardware setup and adding boards
|
||||
186
third_party/zeroclaw/docs/ops/operations-runbook.md
vendored
Normal file
186
third_party/zeroclaw/docs/ops/operations-runbook.md
vendored
Normal file
@@ -0,0 +1,186 @@
|
||||
# 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](../setup-guides/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 |
|
||||
| Docker / Podman | `docker compose up -d` | containerized deployment |
|
||||
|
||||
## Docker / Podman Runtime
|
||||
|
||||
If you installed via `./install.sh --docker`, the container exits after onboarding. To run
|
||||
ZeroClaw as a long-lived container, use the repository `docker-compose.yml` or start a
|
||||
container manually against the persisted data directory.
|
||||
|
||||
### Recommended: docker-compose
|
||||
|
||||
```bash
|
||||
# Start (detached, auto-restarts on reboot)
|
||||
docker compose up -d
|
||||
|
||||
# Stop
|
||||
docker compose down
|
||||
|
||||
# Restart
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Replace `docker` with `podman` if using Podman.
|
||||
|
||||
### Manual container lifecycle
|
||||
|
||||
```bash
|
||||
# Start a new container from the bootstrap image
|
||||
docker run -d --name zeroclaw \
|
||||
--restart unless-stopped \
|
||||
-v "$PWD/.zeroclaw-docker/.zeroclaw:/zeroclaw-data/.zeroclaw" \
|
||||
-v "$PWD/.zeroclaw-docker/workspace:/zeroclaw-data/workspace" \
|
||||
-e HOME=/zeroclaw-data \
|
||||
-e ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace \
|
||||
-p 42617:42617 \
|
||||
zeroclaw-bootstrap:local \
|
||||
gateway
|
||||
|
||||
# Stop (preserves config and workspace)
|
||||
docker stop zeroclaw
|
||||
|
||||
# Restart a stopped container
|
||||
docker start zeroclaw
|
||||
|
||||
# View logs
|
||||
docker logs -f zeroclaw
|
||||
|
||||
# Health check
|
||||
docker exec zeroclaw zeroclaw status
|
||||
```
|
||||
|
||||
For Podman, add `--userns keep-id --user "$(id -u):$(id -g)"` and append `:Z` to volume mounts.
|
||||
|
||||
### Key detail: do not re-run install.sh to restart
|
||||
|
||||
Re-running `install.sh --docker` rebuilds the image and re-runs onboarding. To simply
|
||||
restart, use `docker start`, `docker compose up -d`, or `podman start`.
|
||||
|
||||
For full setup instructions, see [one-click-bootstrap.md](../setup-guides/one-click-bootstrap.md#stopping-and-restarting-a-dockerpodman-container).
|
||||
|
||||
## 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](../setup-guides/one-click-bootstrap.md)
|
||||
- [troubleshooting.md](./troubleshooting.md)
|
||||
- [config-reference.md](../reference/api/config-reference.md)
|
||||
- [commands-reference.md](../reference/cli/commands-reference.md)
|
||||
229
third_party/zeroclaw/docs/ops/proxy-agent-playbook.md
vendored
Normal file
229
third_party/zeroclaw/docs/ops/proxy-agent-playbook.md
vendored
Normal file
@@ -0,0 +1,229 @@
|
||||
# Proxy Agent Playbook
|
||||
|
||||
This playbook provides copy-paste tool calls for configuring proxy behavior via `proxy_config`.
|
||||
|
||||
Use this document when you want the agent to switch proxy scope quickly and safely.
|
||||
|
||||
## 0. Summary
|
||||
|
||||
- **Purpose:** provide copy-ready agent tool calls for proxy scope management and rollback.
|
||||
- **Audience:** operators and maintainers running ZeroClaw in proxied networks.
|
||||
- **Scope:** `proxy_config` actions, mode selection, verification flow, and troubleshooting.
|
||||
- **Non-goals:** generic network debugging outside ZeroClaw runtime behavior.
|
||||
|
||||
---
|
||||
|
||||
## 1. Fast Path by Intent
|
||||
|
||||
Use this section for quick operational routing.
|
||||
|
||||
### 1.1 Proxy only ZeroClaw internal traffic
|
||||
|
||||
1. Use scope `zeroclaw`.
|
||||
2. Set `http_proxy`/`https_proxy` or `all_proxy`.
|
||||
3. Validate with `{"action":"get"}`.
|
||||
|
||||
Go to:
|
||||
|
||||
- [Section 4](#4-mode-a--proxy-only-for-zeroclaw-internals)
|
||||
|
||||
### 1.2 Proxy only selected services
|
||||
|
||||
1. Use scope `services`.
|
||||
2. Set concrete keys or wildcard selectors in `services`.
|
||||
3. Validate coverage using `{"action":"list_services"}`.
|
||||
|
||||
Go to:
|
||||
|
||||
- [Section 5](#5-mode-b--proxy-only-for-specific-services)
|
||||
|
||||
### 1.3 Export process-wide proxy environment variables
|
||||
|
||||
1. Use scope `environment`.
|
||||
2. Apply with `{"action":"apply_env"}`.
|
||||
3. Verify env snapshot via `{"action":"get"}`.
|
||||
|
||||
Go to:
|
||||
|
||||
- [Section 6](#6-mode-c--proxy-for-full-process-environment)
|
||||
|
||||
### 1.4 Emergency rollback
|
||||
|
||||
1. Disable proxy.
|
||||
2. If needed, clear env exports.
|
||||
3. Re-check runtime and environment snapshots.
|
||||
|
||||
Go to:
|
||||
|
||||
- [Section 7](#7-disable--rollback-patterns)
|
||||
|
||||
---
|
||||
|
||||
## 2. Scope Decision Matrix
|
||||
|
||||
| Scope | Affects | Exports env vars | Typical use |
|
||||
|---|---|---|---|
|
||||
| `zeroclaw` | ZeroClaw internal HTTP clients | No | Normal runtime proxying without process-level side effects |
|
||||
| `services` | Only selected service keys/selectors | No | Fine-grained routing for specific providers/tools/channels |
|
||||
| `environment` | Runtime + process environment proxy variables | Yes | Integrations that require `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Standard Safe Workflow
|
||||
|
||||
Use this sequence for every proxy change:
|
||||
|
||||
1. Inspect current state.
|
||||
2. Discover valid service keys/selectors.
|
||||
3. Apply target scope configuration.
|
||||
4. Verify runtime and environment snapshots.
|
||||
5. Roll back if behavior is not expected.
|
||||
|
||||
Tool calls:
|
||||
|
||||
```json
|
||||
{"action":"get"}
|
||||
{"action":"list_services"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Mode A — Proxy Only for ZeroClaw Internals
|
||||
|
||||
Use when ZeroClaw provider/channel/tool HTTP traffic should use proxy, without exporting process-level proxy env vars.
|
||||
|
||||
Tool calls:
|
||||
|
||||
```json
|
||||
{"action":"set","enabled":true,"scope":"zeroclaw","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":["localhost","127.0.0.1"]}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- Runtime proxy is active for ZeroClaw HTTP clients.
|
||||
- `HTTP_PROXY` / `HTTPS_PROXY` process env exports are not required.
|
||||
|
||||
---
|
||||
|
||||
## 5. Mode B — Proxy Only for Specific Services
|
||||
|
||||
Use when only part of the system should use proxy (for example specific providers/tools/channels).
|
||||
|
||||
### 5.1 Target specific services
|
||||
|
||||
```json
|
||||
{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request","channel.telegram"],"all_proxy":"socks5h://127.0.0.1:1080","no_proxy":["localhost","127.0.0.1",".internal"]}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
### 5.2 Target by selectors
|
||||
|
||||
```json
|
||||
{"action":"set","enabled":true,"scope":"services","services":["provider.*","tool.*"],"http_proxy":"http://127.0.0.1:7890"}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- Only matched services use proxy.
|
||||
- Unmatched services bypass proxy.
|
||||
|
||||
---
|
||||
|
||||
## 6. Mode C — Proxy for Full Process Environment
|
||||
|
||||
Use when you intentionally need exported process env vars (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) for runtime integrations.
|
||||
|
||||
### 6.1 Configure and apply environment scope
|
||||
|
||||
```json
|
||||
{"action":"set","enabled":true,"scope":"environment","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":"localhost,127.0.0.1,.internal"}
|
||||
{"action":"apply_env"}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- Runtime proxy is active.
|
||||
- Environment variables are exported for the process.
|
||||
|
||||
---
|
||||
|
||||
## 7. Disable / Rollback Patterns
|
||||
|
||||
### 7.1 Disable proxy (default safe behavior)
|
||||
|
||||
```json
|
||||
{"action":"disable"}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
### 7.2 Disable proxy and force-clear env vars
|
||||
|
||||
```json
|
||||
{"action":"disable","clear_env":true}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
### 7.3 Keep proxy enabled but clear environment exports only
|
||||
|
||||
```json
|
||||
{"action":"clear_env"}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Common Operation Recipes
|
||||
|
||||
### 8.1 Switch from environment-wide proxy to service-only proxy
|
||||
|
||||
```json
|
||||
{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request"],"all_proxy":"socks5://127.0.0.1:1080"}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
### 8.2 Add one more proxied service
|
||||
|
||||
```json
|
||||
{"action":"set","scope":"services","services":["provider.openai","tool.http_request","channel.slack"]}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
### 8.3 Reset `services` list with selectors
|
||||
|
||||
```json
|
||||
{"action":"set","scope":"services","services":["provider.*","channel.telegram"]}
|
||||
{"action":"get"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Troubleshooting
|
||||
|
||||
- Error: `proxy.scope='services' requires a non-empty proxy.services list`
|
||||
- Fix: set at least one concrete service key or selector.
|
||||
|
||||
- Error: invalid proxy URL scheme
|
||||
- Allowed schemes: `http`, `https`, `socks5`, `socks5h`.
|
||||
|
||||
- Proxy does not apply as expected
|
||||
- Run `{"action":"list_services"}` and verify service names/selectors.
|
||||
- Run `{"action":"get"}` and check `runtime_proxy` and `environment` snapshot values.
|
||||
|
||||
---
|
||||
|
||||
## 10. Related Docs
|
||||
|
||||
- [README.md](./README.md) — Documentation index and taxonomy.
|
||||
- [network-deployment.md](./network-deployment.md) — end-to-end network deployment and tunnel topology guidance.
|
||||
- [resource-limits.md](./resource-limits.md) — runtime safety limits for network/tool execution contexts.
|
||||
|
||||
---
|
||||
|
||||
## 11. Maintenance Notes
|
||||
|
||||
- **Owner:** runtime and tooling maintainers.
|
||||
- **Update trigger:** new `proxy_config` actions, proxy scope semantics, or supported service selector changes.
|
||||
- **Last reviewed:** 2026-02-18.
|
||||
105
third_party/zeroclaw/docs/ops/resource-limits.md
vendored
Normal file
105
third_party/zeroclaw/docs/ops/resource-limits.md
vendored
Normal file
@@ -0,0 +1,105 @@
|
||||
# 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](../reference/api/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
|
||||
- Spin CPU at 100%
|
||||
- Fill disk with logs/output
|
||||
|
||||
---
|
||||
|
||||
## Proposed Solutions
|
||||
|
||||
### Option 1: cgroups v2 (Linux, Recommended)
|
||||
Automatically create a cgroup for zeroclaw with limits.
|
||||
|
||||
```bash
|
||||
# Create systemd service with limits
|
||||
[Service]
|
||||
MemoryMax=512M
|
||||
CPUQuota=100%
|
||||
IOReadBandwidthMax=/dev/sda 10M
|
||||
IOWriteBandwidthMax=/dev/sda 10M
|
||||
TasksMax=100
|
||||
```
|
||||
|
||||
### Option 2: tokio::task::deadlock detection
|
||||
Prevent task starvation.
|
||||
|
||||
```rust
|
||||
use tokio::time::{timeout, Duration};
|
||||
|
||||
pub async fn execute_with_timeout<F, T>(
|
||||
fut: F,
|
||||
cpu_time_limit: Duration,
|
||||
memory_limit: usize,
|
||||
) -> Result<T>
|
||||
where
|
||||
F: Future<Output = Result<T>>,
|
||||
{
|
||||
// CPU timeout
|
||||
timeout(cpu_time_limit, fut).await?
|
||||
}
|
||||
```
|
||||
|
||||
### Option 3: Memory monitoring
|
||||
Track heap usage and kill if over limit.
|
||||
|
||||
```rust
|
||||
use std::alloc::{GlobalAlloc, Layout, System};
|
||||
|
||||
struct LimitedAllocator<A> {
|
||||
inner: A,
|
||||
max_bytes: usize,
|
||||
used: std::sync::atomic::AtomicUsize,
|
||||
}
|
||||
|
||||
unsafe impl<A: GlobalAlloc> GlobalAlloc for LimitedAllocator<A> {
|
||||
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
|
||||
let current = self.used.fetch_add(layout.size(), std::sync::atomic::Ordering::Relaxed);
|
||||
if current + layout.size() > self.max_bytes {
|
||||
std::process::abort();
|
||||
}
|
||||
self.inner.alloc(layout)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Config Schema
|
||||
|
||||
```toml
|
||||
[resources]
|
||||
# Memory limits (in MB)
|
||||
max_memory_mb = 512
|
||||
max_memory_per_command_mb = 128
|
||||
|
||||
# CPU limits
|
||||
max_cpu_percent = 50
|
||||
max_cpu_time_seconds = 60
|
||||
|
||||
# Disk I/O limits
|
||||
max_log_size_mb = 100
|
||||
max_temp_storage_mb = 500
|
||||
|
||||
# Process limits
|
||||
max_subprocesses = 10
|
||||
max_open_files = 100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
| Phase | Feature | Effort | Impact |
|
||||
|-------|---------|--------|--------|
|
||||
| **P0** | Memory monitoring + kill | Low | High |
|
||||
| **P1** | CPU timeout per command | Low | High |
|
||||
| **P2** | cgroups integration (Linux) | Medium | Very High |
|
||||
| **P3** | Disk I/O limits | Medium | Medium |
|
||||
242
third_party/zeroclaw/docs/ops/troubleshooting.md
vendored
Normal file
242
third_party/zeroclaw/docs/ops/troubleshooting.md
vendored
Normal file
@@ -0,0 +1,242 @@
|
||||
# ZeroClaw Troubleshooting
|
||||
|
||||
This guide focuses on common setup/runtime failures and fast resolution paths.
|
||||
|
||||
Last verified: **February 20, 2026**.
|
||||
|
||||
## Installation / Bootstrap
|
||||
|
||||
### `cargo` not found
|
||||
|
||||
Symptom:
|
||||
|
||||
- bootstrap exits with `cargo is not installed`
|
||||
|
||||
Fix:
|
||||
|
||||
```bash
|
||||
./install.sh --install-rust
|
||||
```
|
||||
|
||||
Or install from <https://rustup.rs/>.
|
||||
|
||||
### Missing system build dependencies
|
||||
|
||||
Symptom:
|
||||
|
||||
- build fails due to compiler or `pkg-config` issues
|
||||
|
||||
Fix:
|
||||
|
||||
```bash
|
||||
./install.sh --install-system-deps
|
||||
```
|
||||
|
||||
### Build fails on low-RAM / low-disk hosts
|
||||
|
||||
Symptoms:
|
||||
|
||||
- `cargo build --release` is killed (`signal: 9`, OOM killer, or `cannot allocate memory`)
|
||||
- Build crashes after adding swap because disk space runs out
|
||||
|
||||
Why this happens:
|
||||
|
||||
- Runtime memory (<5MB for common operations) is not the same as compile-time memory.
|
||||
- Full source build can require **2 GB RAM + swap** and **6+ GB free disk**.
|
||||
- Enabling swap on a tiny disk can avoid RAM OOM but still fail due to disk exhaustion.
|
||||
|
||||
Preferred path for constrained machines:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Binary-only mode (no source fallback):
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
If you must compile from source on constrained hosts:
|
||||
|
||||
1. Add swap only if you also have enough free disk for both swap + build output.
|
||||
1. Limit cargo parallelism:
|
||||
|
||||
```bash
|
||||
CARGO_BUILD_JOBS=1 cargo build --release --locked
|
||||
```
|
||||
|
||||
1. Reduce heavy features when Matrix is not required:
|
||||
|
||||
```bash
|
||||
cargo build --release --locked --features hardware
|
||||
```
|
||||
|
||||
1. Cross-compile on a stronger machine and copy the binary to the target host.
|
||||
|
||||
### Build is very slow or appears stuck
|
||||
|
||||
Symptoms:
|
||||
|
||||
- `cargo check` / `cargo build` appears stuck at `Checking zeroclaw` for a long time
|
||||
- repeated `Blocking waiting for file lock on package cache` or `build directory`
|
||||
|
||||
Why this happens in ZeroClaw:
|
||||
|
||||
- Matrix E2EE stack (`matrix-sdk`, `ruma`, `vodozemac`) is large and expensive to type-check.
|
||||
- TLS + crypto native build scripts (`aws-lc-sys`, `ring`) add noticeable compile time.
|
||||
- `rusqlite` with bundled SQLite compiles C code locally.
|
||||
- Running multiple cargo jobs/worktrees in parallel causes lock contention.
|
||||
|
||||
Fast checks:
|
||||
|
||||
```bash
|
||||
cargo check --timings
|
||||
cargo tree -d
|
||||
```
|
||||
|
||||
The timing report is written to `target/cargo-timings/cargo-timing.html`.
|
||||
|
||||
Faster local iteration (when Matrix channel is not needed):
|
||||
|
||||
```bash
|
||||
cargo check
|
||||
```
|
||||
|
||||
This uses the lean default feature set and can significantly reduce compile time.
|
||||
|
||||
To build with Matrix support explicitly enabled:
|
||||
|
||||
```bash
|
||||
cargo check --features channel-matrix
|
||||
```
|
||||
|
||||
To build with Matrix + Lark + hardware support:
|
||||
|
||||
```bash
|
||||
cargo check --features hardware,channel-matrix,channel-lark
|
||||
```
|
||||
|
||||
Lock-contention mitigation:
|
||||
|
||||
```bash
|
||||
pgrep -af "cargo (check|build|test)|cargo check|cargo build|cargo test"
|
||||
```
|
||||
|
||||
Stop unrelated cargo jobs before running your own build.
|
||||
|
||||
### `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 `42617`)
|
||||
- `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
|
||||
```
|
||||
|
||||
## Installer URL
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
## 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](../setup-guides/one-click-bootstrap.md)
|
||||
- [channels-reference.md](../reference/api/channels-reference.md)
|
||||
- [network-deployment.md](network-deployment.md)
|
||||
7
third_party/zeroclaw/docs/ops/troubleshooting.vi.md
vendored
Normal file
7
third_party/zeroclaw/docs/ops/troubleshooting.vi.md
vendored
Normal file
@@ -0,0 +1,7 @@
|
||||
# Vietnamese Troubleshooting (Moved)
|
||||
|
||||
Canonical page:
|
||||
|
||||
- [i18n/vi/troubleshooting.md](../i18n/vi/troubleshooting.md)
|
||||
|
||||
Compatibility shim only.
|
||||
Reference in New Issue
Block a user