docs

Operator reference

Everything an operator (or AI agent) needs to run, debug, or extend openclaw-hawkins. The deep specs (vines/spec.md, vecna/spec.md) remain the source of truth — this page is the operator-facing summary plus cross-cutting topics.

configuration

Environment variables

All non-secret config can also live under plugins.entries.openclaw-hawkins.config in openclaw.json. Secrets are env-only by design — the plugin's configSchema deliberately rejects mariadb.password and linear.apiKey.

Required

  • MARIADB_URL — mariadb://<host>[:port]/<database>. Credentials embedded in the URL win over the user/password vars.
  • MARIADB_USER — database account name.
  • MARIADB_PASSWORD — env-only. Must be wired via gateway env (0600 EnvironmentFile or systemctl --user set-environment).

Optional

  • MARIADB_SSL — disabled | preferred | required | insecure. Default preferred. insecure is for self-signed cloud certs only.
  • LINEAR_API_KEY — env-only. Optional. Enables Linear-anchored recovery; everything else works without it.
  • VECNA_PORT — TCP port for the standalone HTTP Nexus (default 8765). Only relevant when running vecna serve.
  • VECNA_HOST — bind address (default 127.0.0.1). Keep loopback in production.
  • VECNA_AUTH_TOKEN — bearer token for the HTTP Nexus. Required in production deployments.
  • VECNA_DEDUP_WINDOW_MIN — dedup window in minutes (default 5).
  • VECNA_URL — used by clients / CLI to find the Nexus (default http://127.0.0.1:8765).
security

Security model

Five known design properties operators should reason about. Full text in SECURITY.md.

Shared agent memory (VECNA)

All agents read and write to a single MariaDB table. Recall is gated by topic match, non-deprecated status, the dedup window, and a decay penalty for stale low-importance entries. Set VECNA_AUTH_TOKEN in production.

Inter-agent dispatch (OpenClaw pattern)

The Nexus dispatches sub-tasks via openclaw agent --agent <id> --message …. Tool inputs and recalled context land in the receiving agent's prompt → its model provider. Never pass secrets in tool arguments.

Linear API scope

The configured Linear key carries whatever scope its issuer granted. Use an OAuth app token scoped to a single team rather than a Personal API key for production. Review the first few tickets the orchestrator creates.

Plugin tools are gateway-wide by default

The 12 tools register through OpenClaw's standard plugin model. Per-agent allowlisting is the operator's responsibility (scoped in openclaw.json). Restrict to the intended Hawkins agents where possible.

MARIADB_SSL=insecure opts out of cert verification

By design, for self-signed cloud certs. Prefer verified TLS when the deployment allows. Insecure mode is gated behind explicit operator config — not a default.

Setup runs effects locally

openclaw hawkins setup writes schemas to the operator-configured MariaDB and creates 6 OpenClaw agent workspaces. Idempotent + non-destructive (skips existing). All effects listed in the post-install banner.

recovery

Crash + restart recovery

After a host crash or gateway restart, the Nexus runs the recovery sequence once on its first turn of the new session:

recovery sequence
# 1. Liveness check.
vecna_healthz   # must return { ok: true, db: 'up' }

# 2. Scan for unfinished work.
vines_recover   # returns summary + items

# 3. For each summary.resumable item, the Nexus picks up
#    from item.lastCompletedChild → item.nextPendingChild in Linear,
#    or marks orphans as failed if markOrphanedAsFailed=true.

The recovery scan distinguishes three states per unfinished row:

  • lookupStatus: "ok" — Linear parent fetched, children enumerated, resumable.
  • lookupStatus: "missing" — Linear definitively returns no parent issue. Truly orphaned. Safe to mark failed.
  • lookupStatus: "lookup_failed" — Linear API errored (transient). Do NOT mark failed. The orchestration stays in its current state for the next recovery pass.

This distinction is load-bearing: a flaky Linear API can't destroy live state by misclassifying a momentarily-unreachable ticket as orphaned.

manifest

Plugin manifest shape

openclaw.plugin.json at the package root declares the plugin to OpenClaw's runtime. Excerpt:

openclaw.plugin.json (abridged)
{
  "id": "openclaw-hawkins",
  "name": "OpenClaw Hawkins — VINES + VECNA",
  "activation": { "onStartup": true },
  "contracts": {
    "tools": [
      "vines_triage", "vines_start", "vines_set_state",
      "vines_attach_linear_parent", "vines_recover", "vines_status",
      "vecna_connect", "vecna_recall", "vecna_evolve",
      "vecna_search", "vecna_fragment", "vecna_healthz"
    ]
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "mariadb": {
        "type": "object",
        "additionalProperties": false,
        "description": "Non-secret connection metadata only.",
        "properties": {
          "url": { "type": "string" },
          "user": { "type": "string" },
          "ssl": { "enum": ["disabled","preferred","required","insecure"] }
        }
      },
      "autoRecovery": { "type": "boolean" },
      "vecna": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "dedupWindowMinutes": { "type": "number", "minimum": 0 }
        }
      }
    }
  }
}
troubleshooting

When things don't work

"the plugin tools aren't directly accessible yet"

The Nexus has the tools registered but didn't re-read its workspace. Confirm HAWKINS_PROTOCOL.md is at ~/.openclaw/workspace/ and restart the gateway.

vecna_healthz returns db: down

MariaDB unreachable from the gateway. Check MARIADB_URL in the env, run nc -vz <host> <port>, confirm the firewall.

Linear ticket creation skipped

~/.openclaw/linear.json missing, OR LINEAR_API_KEY not in the gateway env, OR linear-ticket not on PATH. The Nexus protocol skips Linear when linear.json is absent.

Token required - not valid tokenless upload (ClawHub)

Your CI publish workflow is missing the CLAWHUB_TOKEN repo secret or CLAWHUB_CONFIG_PATH isn't pointing at a config file with {registry, token}.

canonical sources

Read deeper

spec

VINES — Versatile Integration for Networked Execution & State

The canonical contract for durable orchestration. Behavior wins over implementation; if anything drifts, update the spec first.

spec

VECNA — Versatile Entity for Contextual Network Awareness

The Hive's knowledge-fragment contract. Recall ranking, decay handling, the dedup window, the evolve protocol.

security

SECURITY.md

Threat model, design properties, what VINES defends against, what it does not defend against, and the operator-facing security model section.

installer

SKILL.md

The OpenClaw skill manifest for autonomous install. DETECT → ACT → VERIFY stanzas for every phase. Same content as the /install/llm/ page on this site.

protocol

HAWKINS_PROTOCOL.md

The Nexus's plugin-aware orchestration protocol. Step 0 → Step 5 worked sequence, when to skip Linear, restart-recovery recipe.

install

INSTALL.md

The full from-source install. Spelled out step by step in case you want to do it by hand or understand what scripts/setup.sh does.