install · for AI installer agents

Autonomous install — LLM guide

This page is the same content as the repo's SKILL.md, formatted for an installer agent running on the operator's host to follow autonomously. The agent executes each phase in order, recording outputs into a final report.

Operating principle: never block the install on an unanswered question. If you can ask the operator, ask. If not, use the defaults documented below and proceed. Halts are reserved for unrecoverable errors — log them and continue.

phase 0

Host probe

Capture environment basics and decide install mode (greenfield vs incremental). Output goes into the final report.

environment basics

uname -a
node --version 2>/dev/null || echo "node: absent"
openclaw --version 2>&1 | head -1
openclaw gateway status 2>&1 | head -3
command -v jq >/dev/null && echo "jq: present" || echo "jq: absent"
command -v op >/dev/null && echo "op: present" || echo "op: absent"
op whoami 2>/dev/null && echo "op: signed in"

greenfield — none of the six Tendril workspaces, the Nexus AGENTS.md, or linear-ticket exist. Run every phase in full.
incremental — one or more of the above are present. Proceed cautiously: back up before overlaying, reuse existing personalisation.

phase A

Prerequisites (hard gates)

halt if any of these fail

openclaw --version              # require >= 2026.5.7
openclaw gateway status         # require Runtime: running
command -v git  >/dev/null
command -v curl >/dev/null
openclaw models list | head -5  # require >= 1 model configured

soft checks (warn in report, don't halt)

command -v jq >/dev/null
command -v op >/dev/null  # recommended for 1Password-first creds

phase B

Credential resolution — 1Password first

When op is installed and signed in, prefer 1Password: ask the operator which vault + item holds the MariaDB credentials, fetch via op item get, export without echoing values. Never prompt for a plaintext password.

when op is signed in

OP_VAULT="<vault id or name>"
OP_ITEM="<item id or name>"
OP_DB="${OP_DB:-hawkins}"   # most items leave the database field blank

export MARIADB_URL="mariadb://$(op item get "$OP_ITEM" --vault "$OP_VAULT" --fields label=server --reveal):$(op item get "$OP_ITEM" --vault "$OP_VAULT" --fields label=port --reveal)/$OP_DB"
export MARIADB_USER="$(op item get "$OP_ITEM" --vault "$OP_VAULT" --fields label=username --reveal)"
export MARIADB_PASSWORD="$(op item get "$OP_ITEM" --vault "$OP_VAULT" --fields label=password --reveal)"
export MARIADB_SSL="${MARIADB_SSL:-insecure}"

Else fall back to env vars the operator already exported (MARIADB_URL, MARIADB_USER, MARIADB_PASSWORD). If neither path is usable, skip the VINES/VECNA install steps and note creds_source=none in the report.

phase C

Plan announcement

Before any host change, write the plan to the operator (chat, stdout, log). Format:

plan format

openclaw-hawkins install plan
  mode:        <greenfield | incremental>
  path:        <plugin | source-clone>
  clone:       $HOME/openclaw-hawkins  (clone | pull | skip-plugin-path)
  tendrils:    system code research data comm vision  (create | skip-existing)
  nexus:       AGENTS.md TOOLS.md IDENTITY.md HAWKINS_PROTOCOL.md
  linear:      <yes-reuse | yes-env | skip>
  vines:       <yes | skip>  (db: <host>:<port>/<db>)
  vecna:       <yes | skip>  (port: 8765, systemd user service)

phase D

Install — plugin-first path

Always try the plugin path first. Fall back to source-clone only when openclaw plugins install fails.

DETECT

openclaw --version | grep -qE '2026\.(5|[6-9])' && ok=true || ok=false
openclaw plugins search openclaw-hawkins 2>/dev/null \
  | grep -q openclaw-hawkins && plugin_published=true || plugin_published=false

ACT — plugin path

# 1. Install. Falls back to npm if ClawHub unreachable.
openclaw plugins install clawhub:openclaw-hawkins \
  || openclaw plugins install npm:openclaw-hawkins

# 2. Configure non-secrets (NEVER set the password here).
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.url  "$MARIADB_URL"
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.user "$MARIADB_USER"
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.ssl  "${MARIADB_SSL:-insecure}"

# 3. Install MARIADB_PASSWORD into the gateway env via 0600 file.
mkdir -p "$HOME/.openclaw/secrets" && chmod 700 "$HOME/.openclaw/secrets"
( umask 077 && printf 'MARIADB_PASSWORD=%s\n' "$MARIADB_PASSWORD" \
    > "$HOME/.openclaw/secrets/hawkins.env" )
mkdir -p "$HOME/.config/systemd/user/openclaw-gateway.service.d"
cat > "$HOME/.config/systemd/user/openclaw-gateway.service.d/hawkins.conf" <<'EOF'
[Service]
EnvironmentFile=%h/.openclaw/secrets/hawkins.env
EOF
systemctl --user daemon-reload
openclaw gateway restart

# 4. One-shot provisioning: schemas + 6 agents + protocol doc.
openclaw hawkins setup

VERIFY

openclaw plugins inspect openclaw-hawkins --runtime --json \
  | jq -e '.plugin.status=="loaded" and (.plugin.toolNames|length==12)' \
  && echo "plugin ok" || echo "plugin NOT ok"

test -f ~/.openclaw/workspace/HAWKINS_PROTOCOL.md \
  && echo "nexus protocol ok" || echo "nexus protocol MISSING"

openclaw agent --agent system-agent --json --timeout 90 \
  --message "Call vecna_healthz and return only the JSON." \
  | jq -e '.result.payloads[0].text | fromjson | .ok==true' \
  && echo "vecna_healthz ok" || echo "vecna_healthz NOT ok"

# Nexus tool-use check — catches "tools registered but Nexus doesn't know".
openclaw agent --agent main --json --timeout 90 \
  --message "Call vines_recover with no arguments. Return only the .summary." \
  | jq -e '.result.payloads[0].text | fromjson | has("scanned")' \
  && echo "nexus tool-use ok" || echo "nexus tool-use NOT ok"

Critical: The gateway restart after writing the EnvironmentFile is not optional. Without it, the 12 tools are registered but the Nexus hasn't re-read its workspace — symptom is the orchestrator saying "the plugin tools aren't directly accessible yet". Always verify with the --agent main probe above.

phase E

Final report

Emit a structured report to the operator. Use this exact shape so downstream parsers can pick it up:

phase E — report shape (JSON)

{
  "status": "ok | partial | halted",
  "mode": "greenfield | incremental",
  "path": "plugin | source-clone",
  "creds_source": "1password | env | none",
  "components": {
    "plugin": "installed | skipped | failed",
    "schemas": ["vines", "vecna"],
    "agents": ["system-agent", "code-agent", "..."],
    "nexus_protocol": "installed | exists | missing",
    "linear": "configured | skipped"
  },
  "verifications": {
    "plugin_loaded": true,
    "vecna_healthz": true,
    "nexus_tool_use": true
  },
  "warnings": [],
  "next_steps": [
    "Personalise ~/.openclaw/agents/<id>/workspace/IDENTITY.md per specialist.",
    "Review tickets the orchestrator creates within a few minutes of first dispatch."
  ]
}

full SKILL.md on GitHub human install guide