---
name: skillclaw-ops
description: Operate the SkillClaw installation on the VPS — the client proxy (skillclaw.service), the evolve server (skillclaw-evolve.service), and the local closed loop. Trigger on any mention of SkillClaw status, restarting it, checking what it learned, routing traffic through it, wiring it into the gateway, or debugging its services.
---

# SkillClaw operations (VPS)

SkillClaw records LLM sessions that pass through its local proxy, then periodically "evolves" reusable skills from them. Installed 2026-07-28. The closed loop is live but deliberately NOT in the gateway path — it only sees traffic explicitly sent through it. The user decided to run it this way and re-evaluate benefits later before wiring the gateway through it.

## Layout

- Repo + venv: `/root/.hermes/SkillClaw` (editable install, extras `[evolve]` present)
- Config/data home: `/root/.hermes/skillclaw-home/.skillclaw/` — **`HOME=/root/.hermes/skillclaw-home` must prefix every `skillclaw` CLI command** (the tool resolves config via `Path.home()`; /root is read-only)
- Local shared store: `~/.skillclaw/local-share/default/` — sessions land in `sessions/`, evolved skills in `skills/`, registry in `evolve_skill_registry.json`
- Logs: `journalctl -u skillclaw` and `journalctl -u skillclaw-evolve`

## Services (both system units, enabled, Restart=always)

| Unit | What | Listen |
|---|---|---|
| `skillclaw.service` | client proxy, records + injects skills | `127.0.0.1:30000` (OpenAI-compatible) |
| `skillclaw-evolve.service` | evolve server, workflow engine, 300s cycle + HTTP trigger | `0.0.0.0:8787` |

Evolve unit runs: `skillclaw-evolve-server --use-skillclaw-config --interval 300 --port 8787` with `Environment=HOME=/root/.hermes/skillclaw-home`.

## Config state (`~/.skillclaw/config.yaml`)

- Upstream LLM: Nous (`inference-api.nousresearch.com/v1`), real key resolved from `/root/.hermes/.env` (NOT the `env:VAR` reference — that traps upstream into 401; see operating-hermes-gateway pitfalls)
- `claw_type: none` — the live hermes-gateway was never touched
- `sharing.backend: local`, `sharing.local_root: ~/.skillclaw/local-share`, `auto_pull_on_start: true`
- `evolve.server_url: http://127.0.0.1:8787` — proxy auto-triggers evolve after each session upload
- PRM off, remote sharing off, validation off, dashboard off, publish_mode=direct

## How a session flows

1. Client POSTs to `127.0.0.1:30000/v1/chat/completions` with model `skillclaw-model` → proxy forwards to Nous.
2. Session closes on idle (180s sweeper) → proxy uploads `sessions/<id>.json` to local-share → POSTs `:8787/trigger`.
3. Evolve server drains, summarizes, LLM-judges each session; worthwhile ones become/refresh skills in the shared store; proxy polls (30s) and pulls them into its local skill dir.
4. Trivial sessions (e.g. "reply with X") are correctly judged skip-worthy — no skill created. Expect zero skills until real working sessions flow through.

## Sending traffic through it

- One-shot: `hermes chat -Q --provider skillclaw -m skillclaw-model -q "..."` (a `skillclaw` provider entry exists in `/root/.hermes/config.yaml` pointing at the proxy)
- Direct: curl `127.0.0.1:30000/v1/chat/completions`, model field `skillclaw-model`
- **Gateway/desktop traffic bypasses all of this by design** — `model.base_url` in hermes config points straight at Nous. Routing the gateway through the proxy = change `model.base_url` to `http://127.0.0.1:30000/v1` + restart hermes-gateway.service; trade-offs (SPOF, per-session evolve LLM cost, latency, session recordings on disk incl. GHL content) were presented 2026-07-28 and deferred.

### Routing the Web UI / TUI through the proxy (for build sessions)

The Web UI and TUI do NOT use the gateway — `tui_gateway/server.py` spawns a per-session `slash_worker` that talks direct to the provider. Routing them:

- **Per-session (preferred trial):** `/model skillclaw-model --provider skillclaw` inside the session. Session-scoped override, survives rebuilds, zero risk to other sessions. The `skillclaw` provider entry already exists in config.yaml.
- **Whole backend:** `Environment=HERMES_TUI_PROVIDER=skillclaw` in the hermes-serve systemd unit (`_resolve_startup_runtime()` checks `HERMES_TUI_PROVIDER`, then `HERMES_MODEL`/`HERMES_INFERENCE_MODEL`, then config.yaml). Covers Web UI + TUI. Makes skillclaw.service a hard dependency of every session — verify fallback-to-Nous behavior on proxy failure BEFORE doing this.
- Decision deferred until first real build project (2026-07-28); start with per-session, promote to env var only if evolved skills prove useful.

### Subagent/delegation blind spot

`delegation:` in config.yaml pins subagents to `provider: openrouter, model: deepseek/deepseek-v4-flash` — subagent traffic bypasses the proxy AND Nous entirely (pin is absolute, no inheritance — so no silent breakage either). Consequences: SkillClaw records only the parent session's view of delegated work (summaries), never subagent raw sessions; evolved skills are injected into parent requests only, subagents never see them; evolve-cycle spend is unaffected (only proxy traffic costs). Deliberate 80/20: parent turns carry architecture + steering; subagent grunt work is low-value recording material. Do NOT repin delegation to the skillclaw provider — that would run subagents on kimi-k3 via Nous and defeat the cost pin. If a specific subagent's mechanics are ever worth recording, elevate just that task's provider per-call.

## Inspecting what it learned

```bash
ls /root/.hermes/skillclaw-home/.skillclaw/skills/
journalctl -u skillclaw-evolve --since "-7 days" | grep "cycle done"
curl -s -X POST http://127.0.0.1:8787/trigger   # manual cycle; returns JSON stats
```

## Pitfalls

- Forgetting the `HOME=` prefix makes the CLI read/write a phantom config under the real home — always prefix.
- Sessions only upload on close; an open/idle session sits unrecorded until the 180s sweeper fires.
- `skillclaw.service` dying is currently harmless (nothing routes through it); if the gateway is ever pointed at the proxy it becomes a hard dependency — check it FIRST for any chat outage after such a change.
- Evolve cycles spend LLM calls (summarize + judge + aggregate, ~4/session). Scales with traffic routed through the proxy.
- `/etc/systemd/system/` writes: use terminal heredoc (write_file/patch tools refuse system paths).