Merge branch 'main' into commands-list-clean
This commit is contained in:
Luke
GitHub
41
docs/automation/auth-monitoring.md
Normal file
41
docs/automation/auth-monitoring.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
summary: "Monitor OAuth expiry for model providers"
|
||||
read_when:
|
||||
- Setting up auth expiry monitoring or alerts
|
||||
- Automating Claude Code / Codex OAuth refresh checks
|
||||
---
|
||||
# Auth monitoring
|
||||
|
||||
Clawdbot exposes OAuth expiry health via `clawdbot models status`. Use that for
|
||||
automation and alerting; scripts are optional extras for phone workflows.
|
||||
|
||||
## Preferred: CLI check (portable)
|
||||
|
||||
```bash
|
||||
clawdbot models status --check
|
||||
```
|
||||
|
||||
Exit codes:
|
||||
- `0`: OK
|
||||
- `1`: expired or missing credentials
|
||||
- `2`: expiring soon (within 24h)
|
||||
|
||||
This works in cron/systemd and requires no extra scripts.
|
||||
|
||||
## Optional scripts (ops / phone workflows)
|
||||
|
||||
These live under `scripts/` and are **optional**. They assume SSH access to the
|
||||
gateway host and are tuned for systemd + Termux.
|
||||
|
||||
- `scripts/claude-auth-status.sh` now uses `clawdbot models status --json` as the
|
||||
source of truth (falling back to direct file reads if the CLI is unavailable),
|
||||
so keep `clawdbot` on `PATH` for timers.
|
||||
- `scripts/auth-monitor.sh`: cron/systemd timer target; sends alerts (ntfy or phone).
|
||||
- `scripts/systemd/clawdbot-auth-monitor.{service,timer}`: systemd user timer.
|
||||
- `scripts/claude-auth-status.sh`: Claude Code + Clawdbot auth checker (full/json/simple).
|
||||
- `scripts/mobile-reauth.sh`: guided re‑auth flow over SSH.
|
||||
- `scripts/termux-quick-auth.sh`: one‑tap widget status + open auth URL.
|
||||
- `scripts/termux-auth-widget.sh`: full guided widget flow.
|
||||
- `scripts/termux-sync-widget.sh`: sync Claude Code creds → Clawdbot.
|
||||
|
||||
If you don’t need phone automation or systemd timers, skip these scripts.
|
||||
@@ -20,6 +20,7 @@ This page describes the current CLI behavior. If commands change, update this do
|
||||
- ANSI colors and progress indicators only render in TTY sessions.
|
||||
- OSC-8 hyperlinks render as clickable links in supported terminals; otherwise we fall back to plain URLs.
|
||||
- `--json` (and `--plain` where supported) disables styling for clean output.
|
||||
- `--no-color` disables ANSI styling where supported; `NO_COLOR=1` is also respected.
|
||||
- Long-running commands show a progress indicator (OSC 9;4 when supported).
|
||||
|
||||
## Color palette
|
||||
@@ -165,8 +166,9 @@ Options:
|
||||
- `--workspace <dir>`
|
||||
- `--non-interactive`
|
||||
- `--mode <local|remote>`
|
||||
- `--auth-choice <oauth|claude-cli|openai-codex|codex-cli|antigravity|apiKey|minimax|skip>`
|
||||
- `--auth-choice <oauth|claude-cli|openai-codex|codex-cli|antigravity|gemini-api-key|apiKey|minimax|skip>`
|
||||
- `--anthropic-api-key <key>`
|
||||
- `--gemini-api-key <key>`
|
||||
- `--gateway-port <port>`
|
||||
- `--gateway-bind <loopback|lan|tailnet|auto>`
|
||||
- `--gateway-auth <off|token|password>`
|
||||
@@ -442,10 +444,17 @@ Notes:
|
||||
### `logs`
|
||||
Tail Gateway file logs via RPC.
|
||||
|
||||
Notes:
|
||||
- TTY sessions render a colorized, structured view; non-TTY falls back to plain text.
|
||||
- `--json` emits line-delimited JSON (one log event per line).
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
clawdbot logs --follow
|
||||
clawdbot logs --limit 200
|
||||
clawdbot logs --plain
|
||||
clawdbot logs --json
|
||||
clawdbot logs --no-color
|
||||
```
|
||||
|
||||
### `gateway <subcommand>`
|
||||
@@ -479,6 +488,9 @@ Options:
|
||||
Options:
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check` (exit 1=expired/missing, 2=expiring)
|
||||
|
||||
Always includes the auth overview and OAuth expiry status for profiles in the auth store.
|
||||
|
||||
### `models set <model>`
|
||||
Set `agent.model.primary`.
|
||||
|
||||
@@ -12,6 +12,11 @@ file tools and for workspace context. Keep it private and treat it as memory.
|
||||
This is separate from `~/.clawdbot/`, which stores config, credentials, and
|
||||
sessions.
|
||||
|
||||
**Important:** the workspace is the **default cwd**, not a hard sandbox. Tools
|
||||
resolve relative paths against the workspace, but absolute paths can still reach
|
||||
elsewhere on the host unless sandboxing is enabled. If you need isolation, use
|
||||
[`agent.sandbox`](/gateway/sandboxing) (and/or per‑agent sandbox config).
|
||||
|
||||
## Default location
|
||||
|
||||
- Default: `~/clawd`
|
||||
|
||||
@@ -33,6 +33,37 @@ Related:
|
||||
Model refs are normalized to lowercase. Provider aliases like `z.ai/*` normalize
|
||||
to `zai/*`.
|
||||
|
||||
## “Model is not allowed” (and why replies stop)
|
||||
|
||||
If `agent.models` is set, it becomes the **allowlist** for `/model` and for
|
||||
session overrides. When a user selects a model that isn’t in that allowlist,
|
||||
Clawdbot returns:
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
This happens **before** a normal reply is generated, so the message can feel
|
||||
like it “didn’t respond.” The fix is to either:
|
||||
|
||||
- Add the model to `agent.models`, or
|
||||
- Clear the allowlist (remove `agent.models`), or
|
||||
- Pick a model from `/model list`.
|
||||
|
||||
Example allowlist config:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
model: { primary: "anthropic/claude-sonnet-4-5" },
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
|
||||
"anthropic/claude-opus-4-5": { alias: "Opus" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI commands
|
||||
|
||||
```bash
|
||||
@@ -71,7 +102,14 @@ Shows configured models by default. Useful flags:
|
||||
### `models status`
|
||||
|
||||
Shows the resolved primary model, fallbacks, image model, and an auth overview
|
||||
of configured providers. `--plain` prints only the resolved primary model.
|
||||
of configured providers. It also surfaces OAuth expiry status for profiles found
|
||||
in the auth store (warns within 24h by default). `--plain` prints only the
|
||||
resolved primary model.
|
||||
OAuth status is always shown (and included in `--json` output). If a configured
|
||||
provider has no credentials, `models status` prints a **Missing auth** section.
|
||||
JSON includes `auth.oauth` (warn window + profiles) and `auth.providers`
|
||||
(effective auth per provider).
|
||||
Use `--check` for automation (exit `1` when missing/expired, `2` when expiring).
|
||||
|
||||
## Scanning (OpenRouter free models)
|
||||
|
||||
|
||||
@@ -17,8 +17,16 @@ An **agent** is a fully scoped brain with its own:
|
||||
- **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
|
||||
- **Session store** (chat history + routing state) under `~/.clawdbot/agents/<agentId>/sessions`.
|
||||
|
||||
Skills are per-agent via each workspace’s `skills/` folder, with shared skills
|
||||
available from `~/.clawdbot/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
|
||||
|
||||
The Gateway can host **one agent** (default) or **many agents** side-by-side.
|
||||
|
||||
**Workspace note:** each agent’s workspace is the **default cwd**, not a hard
|
||||
sandbox. Relative paths resolve inside the workspace, but absolute paths can
|
||||
reach other host locations unless sandboxing is enabled. See
|
||||
[Sandboxing](/gateway/sandboxing).
|
||||
|
||||
## Paths (quick map)
|
||||
|
||||
- Config: `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`)
|
||||
|
||||
@@ -49,10 +49,13 @@ If you already signed in with the external CLIs *on the gateway host*, Clawdbot
|
||||
- Codex CLI: reads `~/.codex/auth.json` → profile `openai-codex:codex-cli`
|
||||
|
||||
Sync happens when Clawdbot loads the auth store (so it stays up-to-date when the CLIs refresh tokens).
|
||||
On macOS, the first read may trigger a Keychain prompt; run `clawdbot models status`
|
||||
in a terminal once if the Gateway runs headless and can’t access the entry.
|
||||
|
||||
How to verify:
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot providers list
|
||||
```
|
||||
|
||||
|
||||
@@ -97,6 +97,14 @@
|
||||
"source": "/bun",
|
||||
"destination": "/install/bun"
|
||||
},
|
||||
{
|
||||
"source": "/auth-monitoring",
|
||||
"destination": "/automation/auth-monitoring"
|
||||
},
|
||||
{
|
||||
"source": "/scripts",
|
||||
"destination": "/scripts"
|
||||
},
|
||||
{
|
||||
"source": "/camera",
|
||||
"destination": "/nodes/camera"
|
||||
@@ -576,6 +584,7 @@
|
||||
"gateway/gateway-lock",
|
||||
"gateway/configuration",
|
||||
"gateway/configuration-examples",
|
||||
"gateway/authentication",
|
||||
"gateway/background-process",
|
||||
"gateway/health",
|
||||
"gateway/heartbeat",
|
||||
@@ -616,6 +625,7 @@
|
||||
{
|
||||
"group": "Automation & Hooks",
|
||||
"pages": [
|
||||
"automation/auth-monitoring",
|
||||
"automation/webhook",
|
||||
"automation/gmail-pubsub",
|
||||
"automation/cron-jobs",
|
||||
@@ -689,6 +699,7 @@
|
||||
{
|
||||
"group": "Reference & Templates",
|
||||
"pages": [
|
||||
"scripts",
|
||||
"reference/rpc",
|
||||
"reference/device-models",
|
||||
"reference/test",
|
||||
|
||||
82
docs/gateway/authentication.md
Normal file
82
docs/gateway/authentication.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
summary: "Model authentication: OAuth, API keys, and Claude Code token reuse"
|
||||
read_when:
|
||||
- Debugging model auth or OAuth expiry
|
||||
- Documenting authentication or credential storage
|
||||
---
|
||||
# Authentication
|
||||
|
||||
Clawdbot supports OAuth and API keys for model providers. For Anthropic
|
||||
subscription accounts, the most stable path is to **reuse Claude Code OAuth
|
||||
credentials**, including the 1‑year token created by `claude setup-token`.
|
||||
|
||||
See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
|
||||
layout.
|
||||
|
||||
## Recommended: long‑lived Claude Code token
|
||||
|
||||
Run this on the **gateway host** (the machine running the Gateway):
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
```
|
||||
|
||||
This issues a long‑lived **OAuth token** (not an API key) and stores it for
|
||||
Claude Code. Then sync and verify:
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot doctor
|
||||
```
|
||||
|
||||
Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
|
||||
|
||||
```bash
|
||||
clawdbot models status --check
|
||||
```
|
||||
|
||||
Optional ops scripts (systemd/Termux) are documented here:
|
||||
[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
|
||||
`clawdbot models status` loads Claude Code credentials into Clawdbot’s
|
||||
`auth-profiles.json` and shows expiry (warns within 24h by default).
|
||||
`clawdbot doctor` also performs the sync when it runs.
|
||||
|
||||
> `claude setup-token` requires an interactive TTY.
|
||||
|
||||
## Checking model auth status
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot doctor
|
||||
```
|
||||
|
||||
## How sync works
|
||||
|
||||
1. **Claude Code** stores credentials in `~/.claude/.credentials.json` (or
|
||||
Keychain on macOS).
|
||||
2. **Clawdbot** syncs those into
|
||||
`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` when the auth store is
|
||||
loaded.
|
||||
3. OAuth refresh happens automatically on use if a token is expired.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### “No credentials found”
|
||||
|
||||
If the Anthropic OAuth profile is missing, run `claude setup-token` on the
|
||||
**gateway host**, then re-check:
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
```
|
||||
|
||||
### Token expiring/expired
|
||||
|
||||
Run `clawdbot models status` to confirm which profile is expiring. If the profile
|
||||
is `anthropic:claude-cli`, rerun `claude setup-token`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Max or Pro subscription (for `claude setup-token`)
|
||||
- Claude Code CLI installed (`claude` command available)
|
||||
@@ -61,6 +61,7 @@ cat ~/.clawdbot/clawdbot.json
|
||||
- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
|
||||
- State integrity and permissions checks (sessions, transcripts, state dir).
|
||||
- Config file permission checks (chmod 600) when running locally.
|
||||
- Model auth health: checks OAuth expiry and can refresh expiring tokens.
|
||||
- Legacy workspace dir detection (`~/clawdis`, `~/clawdbot`).
|
||||
- Sandbox image repair when sandboxing is enabled.
|
||||
- Legacy service migration and extra gateway detection.
|
||||
@@ -135,33 +136,40 @@ Doctor checks:
|
||||
- **Config file permissions**: warns if `~/.clawdbot/clawdbot.json` is
|
||||
group/world readable and offers to tighten to `600`.
|
||||
|
||||
### 5) Sandbox image repair
|
||||
### 5) Model auth health (OAuth expiry)
|
||||
Doctor inspects OAuth profiles in the auth store, warns when tokens are
|
||||
expiring/expired, and can refresh them when safe. If the Anthropic Claude Code
|
||||
profile is stale, it suggests `claude setup-token` on the gateway host.
|
||||
Refresh prompts only appear when running interactively (TTY); `--non-interactive`
|
||||
skips refresh attempts.
|
||||
|
||||
### 6) Sandbox image repair
|
||||
When sandboxing is enabled, doctor checks Docker images and offers to build or
|
||||
switch to legacy names if the current image is missing.
|
||||
|
||||
### 6) Gateway service migrations and cleanup hints
|
||||
### 7) Gateway service migrations and cleanup hints
|
||||
Doctor detects legacy Clawdis gateway services (launchd/systemd/schtasks) and
|
||||
offers to remove them and install the Clawdbot service using the current gateway
|
||||
port. It can also scan for extra gateway-like services and print cleanup hints
|
||||
to ensure only one gateway runs per machine.
|
||||
|
||||
### 7) Security warnings
|
||||
### 8) Security warnings
|
||||
Doctor emits warnings when a provider is open to DMs without an allowlist, or
|
||||
when a policy is configured in a dangerous way.
|
||||
|
||||
### 8) systemd linger (Linux)
|
||||
### 9) systemd linger (Linux)
|
||||
If running as a systemd user service, doctor ensures lingering is enabled so the
|
||||
gateway stays alive after logout.
|
||||
|
||||
### 9) Skills status
|
||||
### 10) Skills status
|
||||
Doctor prints a quick summary of eligible/missing/blocked skills for the current
|
||||
workspace.
|
||||
|
||||
### 10) Gateway health check + restart
|
||||
### 11) Gateway health check + restart
|
||||
Doctor runs a health check and offers to restart the gateway when it looks
|
||||
unhealthy.
|
||||
|
||||
### 11) Supervisor config audit + repair
|
||||
### 12) Supervisor config audit + repair
|
||||
Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
|
||||
missing or outdated defaults (e.g., systemd network-online dependencies and
|
||||
restart delay). When it finds a mismatch, it recommends an update and can
|
||||
@@ -174,24 +182,24 @@ Notes:
|
||||
- `clawdbot doctor --repair --force` overwrites custom supervisor configs.
|
||||
- You can always force a full rewrite via `clawdbot daemon install --force`.
|
||||
|
||||
### 12) Gateway runtime + port diagnostics
|
||||
### 13) Gateway runtime + port diagnostics
|
||||
Doctor inspects the daemon runtime (PID, last exit status) and warns when the
|
||||
service is installed but not actually running. It also checks for port collisions
|
||||
on the gateway port (default `18789`) and reports likely causes (gateway already
|
||||
running, SSH tunnel).
|
||||
|
||||
### 13) Gateway runtime best practices
|
||||
### 14) Gateway runtime best practices
|
||||
Doctor warns when the gateway service runs on Bun or a version-managed Node path
|
||||
(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram providers require Node,
|
||||
and version-manager paths can break after upgrades because the daemon does not
|
||||
load your shell init. Doctor offers to migrate to a system Node install when
|
||||
available (Homebrew/apt/choco).
|
||||
|
||||
### 14) Config write + wizard metadata
|
||||
### 15) Config write + wizard metadata
|
||||
Doctor persists any config changes and stamps wizard metadata to record the
|
||||
doctor run.
|
||||
|
||||
### 15) Workspace tips (backup + memory system)
|
||||
### 16) Workspace tips (backup + memory system)
|
||||
Doctor suggests a workspace memory system when missing and prints a backup tip
|
||||
if the workspace is not already under git.
|
||||
|
||||
|
||||
@@ -7,6 +7,8 @@ read_when:
|
||||
|
||||
# Logging
|
||||
|
||||
For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
|
||||
|
||||
Clawdbot has two log “surfaces”:
|
||||
|
||||
- **Console output** (what you see in the terminal / Debug UI).
|
||||
|
||||
@@ -77,6 +77,13 @@ Even with strong system prompts, **prompt injection is not solved**. What helps
|
||||
- Run sensitive tool execution in a sandbox; keep secrets out of the agent’s reachable filesystem.
|
||||
- **Model choice matters:** we recommend Anthropic Opus 4.5 because it’s quite good at recognizing prompt injections (see [“A step forward on safety”](https://www.anthropic.com/news/claude-opus-4-5)). Using weaker models increases risk.
|
||||
|
||||
## Reasoning & verbose output in groups
|
||||
|
||||
`/reasoning` and `/verbose` can expose internal reasoning or tool output that
|
||||
was not meant for a public channel. In group settings, treat them as **debug
|
||||
only** and keep them off unless you explicitly need them. If you enable them,
|
||||
do so only in trusted DMs or tightly controlled rooms.
|
||||
|
||||
## Lessons Learned (The Hard Way)
|
||||
|
||||
### The `find ~` Incident 🦞
|
||||
|
||||
@@ -33,6 +33,19 @@ Doctor/daemon will show runtime state (PID/last exit) and log hints.
|
||||
- Linux systemd (if installed): `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
|
||||
- Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`
|
||||
|
||||
**Enable more logging:**
|
||||
- Bump file log detail (persisted JSONL):
|
||||
```json
|
||||
{ "logging": { "level": "debug" } }
|
||||
```
|
||||
- Bump console verbosity (TTY output only):
|
||||
```json
|
||||
{ "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
|
||||
```
|
||||
- Quick tip: `--verbose` affects **console** output only. File logs remain controlled by `logging.level`.
|
||||
|
||||
See [/logging](/logging) for a full overview of formats, config, and access.
|
||||
|
||||
### Service Environment (PATH + runtime)
|
||||
|
||||
The gateway daemon runs with a **minimal PATH** to avoid shell/manager cruft:
|
||||
|
||||
205
docs/install/ansible.md
Normal file
205
docs/install/ansible.md
Normal file
@@ -0,0 +1,205 @@
|
||||
---
|
||||
summary: "Automated, hardened Clawdbot installation with Ansible, Tailscale VPN, and firewall isolation"
|
||||
read_when:
|
||||
- You want automated server deployment with security hardening
|
||||
- You need firewall-isolated setup with VPN access
|
||||
- You're deploying to remote Debian/Ubuntu servers
|
||||
---
|
||||
|
||||
# Ansible Installation
|
||||
|
||||
The recommended way to deploy Clawdbot to production servers is via **[clawdbot-ansible](https://github.com/clawdbot/clawdbot-ansible)** — an automated installer with security-first architecture.
|
||||
|
||||
## Quick Start
|
||||
|
||||
One-command install:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/clawdbot/clawdbot-ansible/main/install.sh | bash
|
||||
```
|
||||
|
||||
> **📦 Full guide: [github.com/clawdbot/clawdbot-ansible](https://github.com/clawdbot/clawdbot-ansible)**
|
||||
>
|
||||
> The clawdbot-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.
|
||||
|
||||
## What You Get
|
||||
|
||||
- 🔒 **Firewall-first security**: UFW + Docker isolation (only SSH + Tailscale accessible)
|
||||
- 🔐 **Tailscale VPN**: Secure remote access without exposing services publicly
|
||||
- 🐳 **Docker**: Isolated sandbox containers, localhost-only bindings
|
||||
- 🛡️ **Defense in depth**: 4-layer security architecture
|
||||
- 🚀 **One-command setup**: Complete deployment in minutes
|
||||
- 🔧 **Systemd integration**: Auto-start on boot with hardening
|
||||
|
||||
## Requirements
|
||||
|
||||
- **OS**: Debian 11+ or Ubuntu 20.04+
|
||||
- **Access**: Root or sudo privileges
|
||||
- **Network**: Internet connection for package installation
|
||||
- **Ansible**: 2.14+ (installed automatically by quick-start script)
|
||||
|
||||
## What Gets Installed
|
||||
|
||||
The Ansible playbook installs and configures:
|
||||
|
||||
1. **Tailscale** (mesh VPN for secure remote access)
|
||||
2. **UFW firewall** (SSH + Tailscale ports only)
|
||||
3. **Docker CE + Compose V2** (for agent sandboxes)
|
||||
4. **Node.js 22.x + pnpm** (runtime dependencies)
|
||||
5. **Clawdbot** (host-based, not containerized)
|
||||
6. **Systemd service** (auto-start with security hardening)
|
||||
|
||||
Note: The gateway runs **directly on the host** (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details.
|
||||
|
||||
## Post-Install Setup
|
||||
|
||||
After installation completes, switch to the clawdbot user:
|
||||
|
||||
```bash
|
||||
sudo -i -u clawdbot
|
||||
```
|
||||
|
||||
The post-install script will guide you through:
|
||||
|
||||
1. **Onboarding wizard**: Configure Clawdbot settings
|
||||
2. **Provider login**: Connect WhatsApp/Telegram/Discord/Signal
|
||||
3. **Gateway testing**: Verify the installation
|
||||
4. **Tailscale setup**: Connect to your VPN mesh
|
||||
|
||||
### Quick commands
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
sudo systemctl status clawdbot
|
||||
|
||||
# View live logs
|
||||
sudo journalctl -u clawdbot -f
|
||||
|
||||
# Restart gateway
|
||||
sudo systemctl restart clawdbot
|
||||
|
||||
# Provider login (run as clawdbot user)
|
||||
sudo -i -u clawdbot
|
||||
clawdbot login
|
||||
```
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### 4-Layer Defense
|
||||
|
||||
1. **Firewall (UFW)**: Only SSH (22) + Tailscale (41641/udp) exposed publicly
|
||||
2. **VPN (Tailscale)**: Gateway accessible only via VPN mesh
|
||||
3. **Docker Isolation**: DOCKER-USER iptables chain prevents external port exposure
|
||||
4. **Systemd Hardening**: NoNewPrivileges, PrivateTmp, unprivileged user
|
||||
|
||||
### Verification
|
||||
|
||||
Test external attack surface:
|
||||
|
||||
```bash
|
||||
nmap -p- YOUR_SERVER_IP
|
||||
```
|
||||
|
||||
Should show **only port 22** (SSH) open. All other services (gateway, Docker) are locked down.
|
||||
|
||||
### Docker Availability
|
||||
|
||||
Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
|
||||
|
||||
See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration.
|
||||
|
||||
## Manual Installation
|
||||
|
||||
If you prefer manual control over the automation:
|
||||
|
||||
```bash
|
||||
# 1. Install prerequisites
|
||||
sudo apt update && sudo apt install -y ansible git
|
||||
|
||||
# 2. Clone repository
|
||||
git clone https://github.com/clawdbot/clawdbot-ansible.git
|
||||
cd clawdbot-ansible
|
||||
|
||||
# 3. Install Ansible collections
|
||||
ansible-galaxy collection install -r requirements.yml
|
||||
|
||||
# 4. Run playbook
|
||||
./run-playbook.sh
|
||||
|
||||
# Or run directly (then manually execute /tmp/clawdbot-setup.sh after)
|
||||
# ansible-playbook playbook.yml --ask-become-pass
|
||||
```
|
||||
|
||||
## Updating Clawdbot
|
||||
|
||||
The Ansible installer sets up Clawdbot for manual updates. See [Updating](/install/updating) for the standard update flow.
|
||||
|
||||
To re-run the Ansible playbook (e.g., for configuration changes):
|
||||
|
||||
```bash
|
||||
cd clawdbot-ansible
|
||||
./run-playbook.sh
|
||||
```
|
||||
|
||||
Note: This is idempotent and safe to run multiple times.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Firewall blocks my connection
|
||||
|
||||
If you're locked out:
|
||||
- Ensure you can access via Tailscale VPN first
|
||||
- SSH access (port 22) is always allowed
|
||||
- The gateway is **only** accessible via Tailscale by design
|
||||
|
||||
### Service won't start
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
sudo journalctl -u clawdbot -n 100
|
||||
|
||||
# Verify permissions
|
||||
sudo ls -la /opt/clawdbot
|
||||
|
||||
# Test manual start
|
||||
sudo -i -u clawdbot
|
||||
cd ~/clawdbot
|
||||
pnpm start
|
||||
```
|
||||
|
||||
### Docker sandbox issues
|
||||
|
||||
```bash
|
||||
# Verify Docker is running
|
||||
sudo systemctl status docker
|
||||
|
||||
# Check sandbox image
|
||||
sudo docker images | grep clawdbot-sandbox
|
||||
|
||||
# Build sandbox image if missing
|
||||
cd /opt/clawdbot/clawdbot
|
||||
sudo -u clawdbot ./scripts/sandbox-setup.sh
|
||||
```
|
||||
|
||||
### Provider login fails
|
||||
|
||||
Make sure you're running as the `clawdbot` user:
|
||||
|
||||
```bash
|
||||
sudo -i -u clawdbot
|
||||
clawdbot login
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
For detailed security architecture and troubleshooting:
|
||||
- [Security Architecture](https://github.com/clawdbot/clawdbot-ansible/blob/main/docs/security.md)
|
||||
- [Technical Details](https://github.com/clawdbot/clawdbot-ansible/blob/main/docs/architecture.md)
|
||||
- [Troubleshooting Guide](https://github.com/clawdbot/clawdbot-ansible/blob/main/docs/troubleshooting.md)
|
||||
|
||||
## Related
|
||||
|
||||
- [clawdbot-ansible](https://github.com/clawdbot/clawdbot-ansible) — full deployment guide
|
||||
- [Docker](/install/docker) — containerized gateway setup
|
||||
- [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
|
||||
- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation
|
||||
144
docs/logging.md
Normal file
144
docs/logging.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
summary: "Logging overview: file logs, console output, CLI tailing, and the Control UI"
|
||||
read_when:
|
||||
- You need a beginner-friendly overview of logging
|
||||
- You want to configure log levels or formats
|
||||
- You are troubleshooting and need to find logs quickly
|
||||
---
|
||||
|
||||
# Logging
|
||||
|
||||
Clawdbot logs in two places:
|
||||
|
||||
- **File logs** (JSON lines) written by the Gateway.
|
||||
- **Console output** shown in terminals and the Control UI.
|
||||
|
||||
This page explains where logs live, how to read them, and how to configure log
|
||||
levels and formats.
|
||||
|
||||
## Where logs live
|
||||
|
||||
By default, the Gateway writes a rolling log file under:
|
||||
|
||||
`/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
|
||||
|
||||
You can override this in `~/.clawdbot/clawdbot.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"logging": {
|
||||
"file": "/path/to/clawdbot.log"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## How to read logs
|
||||
|
||||
### CLI: live tail (recommended)
|
||||
|
||||
Use the CLI to tail the gateway log file via RPC:
|
||||
|
||||
```bash
|
||||
clawdbot logs --follow
|
||||
```
|
||||
|
||||
Output modes:
|
||||
|
||||
- **TTY sessions**: pretty, colorized, structured log lines.
|
||||
- **Non-TTY sessions**: plain text.
|
||||
- `--json`: line-delimited JSON (one log event per line).
|
||||
- `--plain`: force plain text in TTY sessions.
|
||||
- `--no-color`: disable ANSI colors.
|
||||
|
||||
In JSON mode, the CLI emits `type`-tagged objects:
|
||||
|
||||
- `meta`: stream metadata (file, cursor, size)
|
||||
- `log`: parsed log entry
|
||||
- `notice`: truncation / rotation hints
|
||||
- `raw`: unparsed log line
|
||||
|
||||
If the Gateway is unreachable, the CLI prints a short hint to run:
|
||||
|
||||
```bash
|
||||
clawdbot doctor
|
||||
```
|
||||
|
||||
### Control UI (web)
|
||||
|
||||
The Control UI’s **Logs** tab tails the same file using `logs.tail`.
|
||||
See [/web/control-ui](/web/control-ui) for how to open it.
|
||||
|
||||
### Provider-only logs
|
||||
|
||||
To filter provider activity (WhatsApp/Telegram/etc), use:
|
||||
|
||||
```bash
|
||||
clawdbot providers logs --provider whatsapp
|
||||
```
|
||||
|
||||
## Log formats
|
||||
|
||||
### File logs (JSONL)
|
||||
|
||||
Each line in the log file is a JSON object. The CLI and Control UI parse these
|
||||
entries to render structured output (time, level, subsystem, message).
|
||||
|
||||
### Console output
|
||||
|
||||
Console logs are **TTY-aware** and formatted for readability:
|
||||
|
||||
- Subsystem prefixes (e.g. `gateway/providers/whatsapp`)
|
||||
- Level coloring (info/warn/error)
|
||||
- Optional compact or JSON mode
|
||||
|
||||
Console formatting is controlled by `logging.consoleStyle`.
|
||||
|
||||
## Configuring logging
|
||||
|
||||
All logging configuration lives under `logging` in `~/.clawdbot/clawdbot.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"logging": {
|
||||
"level": "info",
|
||||
"file": "/tmp/clawdbot/clawdbot-YYYY-MM-DD.log",
|
||||
"consoleLevel": "info",
|
||||
"consoleStyle": "pretty",
|
||||
"redactSensitive": "tools",
|
||||
"redactPatterns": [
|
||||
"sk-.*"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Log levels
|
||||
|
||||
- `logging.level`: **file logs** (JSONL) level.
|
||||
- `logging.consoleLevel`: **console** verbosity level.
|
||||
|
||||
`--verbose` only affects console output; it does not change file log levels.
|
||||
|
||||
### Console styles
|
||||
|
||||
`logging.consoleStyle`:
|
||||
|
||||
- `pretty`: human-friendly, colored, with timestamps.
|
||||
- `compact`: tighter output (best for long sessions).
|
||||
- `json`: JSON per line (for log processors).
|
||||
|
||||
### Redaction
|
||||
|
||||
Tool summaries can redact sensitive tokens before they hit the console:
|
||||
|
||||
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
|
||||
- `logging.redactPatterns`: list of regex strings to override the default set
|
||||
|
||||
Redaction affects **console output only** and does not alter file logs.
|
||||
|
||||
## Troubleshooting tips
|
||||
|
||||
- **Gateway not reachable?** Run `clawdbot doctor` first.
|
||||
- **Logs empty?** Check that the Gateway is running and writing to the file path
|
||||
in `logging.file`.
|
||||
- **Need more detail?** Set `logging.level` to `debug` or `trace` and retry.
|
||||
26
docs/scripts.md
Normal file
26
docs/scripts.md
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
summary: "Repository scripts: purpose, scope, and safety notes"
|
||||
read_when:
|
||||
- Running scripts from the repo
|
||||
- Adding or changing scripts under ./scripts
|
||||
---
|
||||
# Scripts
|
||||
|
||||
The `scripts/` directory contains helper scripts for local workflows and ops tasks.
|
||||
Use these when a task is clearly tied to a script; otherwise prefer the CLI.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Scripts are **optional** unless referenced in docs or release checklists.
|
||||
- Prefer CLI surfaces when they exist (example: auth monitoring uses `clawdbot models status --check`).
|
||||
- Assume scripts are host‑specific; read them before running on a new machine.
|
||||
|
||||
## Auth monitoring scripts
|
||||
|
||||
Auth monitoring scripts are documented here:
|
||||
[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
|
||||
## When adding scripts
|
||||
|
||||
- Keep scripts focused and documented.
|
||||
- Add a short entry in the relevant doc (or create one if missing).
|
||||
@@ -33,10 +33,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
||||
Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health).
|
||||
|
||||
5) **Tail the latest log**
|
||||
```bash
|
||||
clawdbot logs --follow
|
||||
```
|
||||
If RPC is down, fall back to:
|
||||
```bash
|
||||
tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)"
|
||||
```
|
||||
File logs are separate from service logs; see [Logging](/gateway/logging) and [Troubleshooting](/gateway/troubleshooting).
|
||||
File logs are separate from service logs; see [Logging](/logging) and [Troubleshooting](/gateway/troubleshooting).
|
||||
|
||||
## What is Clawdbot?
|
||||
|
||||
@@ -114,6 +118,26 @@ Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`
|
||||
|
||||
Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agent.workspace` (default: `~/clawd`).
|
||||
|
||||
### Can agents work outside the workspace?
|
||||
|
||||
Yes. The workspace is the **default cwd** and memory anchor, not a hard sandbox.
|
||||
Relative paths resolve inside the workspace, but absolute paths can access other
|
||||
host locations unless sandboxing is enabled. If you need isolation, use
|
||||
[`agent.sandbox`](/gateway/sandboxing) or per‑agent sandbox settings. If you
|
||||
want a repo to be the default working directory, point that agent’s
|
||||
`workspace` to the repo root. The Clawdbot repo is just source code; keep the
|
||||
workspace separate unless you intentionally want the agent to work inside it.
|
||||
|
||||
Example (repo as default cwd):
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/Projects/my-repo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### I’m in remote mode — where is the session store?
|
||||
|
||||
Session state is owned by the **gateway host**. If you’re in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session).
|
||||
@@ -257,6 +281,18 @@ Use the `/model` command as a standalone message:
|
||||
|
||||
You can list available models with `/model`, `/model list`, or `/model status`.
|
||||
|
||||
### Why do I see “Model … is not allowed” and then no reply?
|
||||
|
||||
If `agent.models` is set, it becomes the **allowlist** for `/model` and any
|
||||
session overrides. Choosing a model that isn’t in that list returns:
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
That error is returned **instead of** a normal reply. Fix: add the model to
|
||||
`agent.models`, remove the allowlist, or pick a model from `/model list`.
|
||||
|
||||
### Are opus / sonnet / gpt built‑in shortcuts?
|
||||
|
||||
Yes. Clawdbot ships a few default shorthands (only applied when the model exists in `agent.models`):
|
||||
@@ -346,7 +382,7 @@ It means the system attempted to use the auth profile ID `anthropic:default`, bu
|
||||
- **Make sure you’re editing the correct agent**
|
||||
- Multi‑agent setups mean there can be multiple `auth-profiles.json` files.
|
||||
- **Sanity‑check model/auth status**
|
||||
- Use `/model status` to see configured models and whether providers are authenticated.
|
||||
- Use `clawdbot models status` to see configured models and whether providers are authenticated.
|
||||
|
||||
### Why did it also try Google Gemini and fail?
|
||||
|
||||
|
||||
@@ -170,6 +170,17 @@ clawdbot onboard --non-interactive \
|
||||
|
||||
Add `--json` for a machine‑readable summary.
|
||||
|
||||
Gemini example:
|
||||
|
||||
```bash
|
||||
clawdbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice gemini-api-key \
|
||||
--gemini-api-key "$GEMINI_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Add agent (non‑interactive) example:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -50,7 +50,8 @@ bun add -g clawdhub
|
||||
|
||||
By default, the CLI installs skills into `./skills` under your current working directory. Clawdbot loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence.
|
||||
|
||||
For more detail on how skills are loaded and gated, see `docs/skills.md`.
|
||||
For more detail on how skills are loaded, shared, and gated, see
|
||||
[Skills](/tools/skills).
|
||||
|
||||
## What the service provides (features)
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ read_when:
|
||||
- **Global availability gate**: `agent.elevated` is global (not per-agent). If disabled or sender not allowlisted, elevated is unavailable everywhere.
|
||||
- **Per-session state**: `/elevated on|off` sets the elevated level for the current session key.
|
||||
- **Inline directive**: `/elevated on` inside a message applies to that message only.
|
||||
- **Groups**: In group chats, elevated directives are only honored when the agent is mentioned.
|
||||
- **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
|
||||
- **Host execution**: elevated runs `bash` on the host (bypasses sandbox).
|
||||
- **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `bash` runs.
|
||||
- **Tool policy still applies**: if `bash` is denied by tool policy, elevated cannot be used.
|
||||
|
||||
@@ -23,6 +23,36 @@ If a skill name conflicts, precedence is:
|
||||
Additionally, you can configure extra skill folders (lowest precedence) via
|
||||
`skills.load.extraDirs` in `~/.clawdbot/clawdbot.json`.
|
||||
|
||||
## Per-agent vs shared skills
|
||||
|
||||
In **multi-agent** setups, each agent has its own workspace. That means:
|
||||
|
||||
- **Per-agent skills** live in `<workspace>/skills` for that agent only.
|
||||
- **Shared skills** live in `~/.clawdbot/skills` (managed/local) and are visible
|
||||
to **all agents** on the same machine.
|
||||
- **Shared folders** can also be added via `skills.load.extraDirs` (lowest
|
||||
precedence) if you want a common skills pack used by multiple agents.
|
||||
|
||||
If the same skill name exists in more than one place, the usual precedence
|
||||
applies: workspace wins, then managed/local, then bundled.
|
||||
|
||||
## ClawdHub (install + sync)
|
||||
|
||||
ClawdHub is the public skills registry for Clawdbot. Use it to discover,
|
||||
install, update, and back up skills. Full guide: [ClawdHub](/tools/clawdhub).
|
||||
|
||||
Common flows:
|
||||
|
||||
- Install a skill into your workspace:
|
||||
- `clawdhub install <skill-slug>`
|
||||
- Update all installed skills:
|
||||
- `clawdhub update --all`
|
||||
- Sync (scan + publish updates):
|
||||
- `clawdhub sync --all`
|
||||
|
||||
By default, `clawdhub` installs into `./skills` under your current working
|
||||
directory; Clawdbot picks that up as `<workspace>/skills` on the next session.
|
||||
|
||||
## Format (AgentSkills + Pi-compatible)
|
||||
|
||||
`SKILL.md` must include at least:
|
||||
|
||||
@@ -53,6 +53,8 @@ Text-only:
|
||||
|
||||
Notes:
|
||||
- Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
|
||||
- `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
|
||||
- `/reasoning` (and `/verbose`) are risky in group settings: they may reveal internal reasoning or tool output you did not intend to expose. Prefer leaving them off, especially in group chats.
|
||||
|
||||
## Surface notes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user