Agent Guide

Hollanov is the custom AI agent for the OpenClaw project. It connects to the Claude API, manages 34 tools for VPS/docs/git/quality operations, enforces permissions, tracks sessions, and gives you full visibility into what the agent does.

Running the Agent

Prerequisites

npm install                  # Install dependencies
just agent-doctor            # Verify environment is ready

Start the Interactive Agent

ANTHROPIC_API_KEY=$(op item get "Anthropic API Key" --vault="Shared-Infrastructure" --fields credential --reveal) just agent-run

This boots the runtime (34 tools, session persistence, budget tracking) and drops you into an interactive REPL:

Hollanov
========================================
Booting...

Session: fc79acac-d35a-4621-bad6-99d083b82804
Tools:   21 registered
Budget:  1,000,000 tokens

Type a message to chat. Commands:
  /tools    — list available tools
  /session  — show session info
  /budget   — show budget status
  /quit     — exit

openclaw> List my VPS instances

[tool: vps-list]
Here are your VPS instances:
...
[tokens: +2,043 | stop: completed]

REPL Commands

Command	What It Does
/tools	List all 21 available tools with risk indicators
/session	Show session ID, turn count, message count, token usage
/budget	Show tokens used, remaining, and turn count
/quit	Persist session and exit

Web Environment (Claude Code)

In a Claude Code web session, VPS operations are available via the web VPS recipes. First, configure your environment (see Developer Setup — Claude Code Web Environment):

1. Set network access to Custom or Full in environment settings
2. Add VPS hostname/IP to the allowlist
3. Set HOSTINGER_API_TOKEN and optionally VPS_SSH_PRIVATE_KEY as project env vars

Then:

just setup-web         # Install tools + configure SSH
just vps-status        # Check VPS status via API
just vps-exec "docker logs hollanov --tail 20"  # Run VPS commands
just agent-test        # Run tests

What the Agent Can Do

The agent has 34 tools organized into categories. When you ask it to do something, it picks the right tool, checks permissions, executes it, and explains the result.

VPS Management

Tool	What It Does	Risk
vps-list	List all VPSes with status, IP, plan, and roles	Read-only
vps-add	Register a VPS in SSH config	Mutating
vps-new	Provision a new VPS from scratch	Mutating
vps-provision	Run modules on existing VPS (SSH, firewall, webserver)	Mutating
vps-destroy	Permanently destroy a VPS	Destructive

Documentation

Tool	What It Does	Risk
docs-build	Build Docusaurus docs and preview locally	Mutating
docs-deploy	Build and deploy to Cloudflare Pages	Mutating

Git and PRs

Tool	What It Does	Risk
pr-create	Create branch, push, open PR, poll for CodeRabbit	Mutating
pr-merge	Wait for checks, squash-merge, delete branch	Destructive

Code Quality

Tool	What It Does	Risk
lint-sh	Lint shell scripts with shellcheck	Read-only
lint-md	Lint markdown files	Read-only
lint	Run all linters	Read-only

Agent Runtime

Tool	What It Does	Risk
agent-test	Run all 373 tests	Read-only
agent-typecheck	TypeScript type checking	Read-only
agent-doctor	System health diagnostics	Read-only
agent-verify	Safety invariant checks	Read-only

Memory

Tool	What It Does	Risk
memory-store	Store a persistent memory (survives across sessions)	Mutating
memory-recall	Search persistent memories by keyword or type	Read-only

Web Search

Tool	What It Does	Risk
web-search	Search the web using Brave Search API	Read-only

Skills

Tool	What It Does	Risk
skill-coderabbit	Check and fix CodeRabbit PR feedback	Mutating
skill-deploy	Deploy docs and verify live	Mutating
skill-new-doc	Scaffold a new doc with frontmatter	Mutating
skill-status	View/update project status	Mutating
skill-vps	Run SSH command on hollanov VPS	Mutating

How Permissions Work

You don't need to configure permissions — they work automatically. The system prevents dangerous actions in automated contexts while allowing them in interactive mode with your oversight.

What happens automatically:

• Read-only tools (linters, tests, VPS list) are always approved
• Destructive tools (VPS destroy, PR merge) are blocked in automated modes
• Dangerous SSH commands (rm -rf /, shutdown, iptables -F) are caught before execution
• Dangerous git commands (push --force, reset --hard) are caught before execution
• Every permission decision is logged with timestamp and reason

Example — the agent tries to destroy a VPS in worker mode:

[denied: vps-destroy — Destructive tool "vps-destroy" requires interactive mode]

Sessions

Every conversation is a session. Sessions persist to disk automatically after each turn, so you never lose context.

What's saved:

• Conversation messages (user + assistant)
• Token usage (input, output, total)
• Permission decisions (every grant and denial)
• Active workflow state
• Available tool pool
• Turn count

Where: ~/.openclaw/sessions/{session-id}.json

Sessions resume automatically if you pass a session ID at boot.

Budget Tracking

The agent checks the token budget before every API call. If you're over budget, the turn halts gracefully instead of spending money.

Default limits:

• 1,000,000 tokens per session
• 100 turns per session

Check budget anytime with /budget:

  Used:      8,516 tokens
  Remaining: 991,484 tokens
  Turns:     3 / 100

Agent Types

The runtime supports constrained agent types that limit what tools are available. This is useful when you want an agent that can only read (not write), or only test (not deploy).

Type	What It Can Do
explore	Search, read, lint, test — cannot edit, deploy, or destroy
plan	Analyze and design — cannot execute or modify anything
verification	Run tests and linting — cannot deploy or destroy
general-purpose	Everything (default)
deploy	Build, test, deploy — cannot destroy or merge PRs

Persistent Memory

The agent maintains persistent memory across conversations. Memories have provenance (where they came from), relevance scores (how important they are), and age decay (old memories fade).

Memory types:

• user — who you are, your preferences, your role
• feedback — what to do and not do (corrections and confirmations)
• project — ongoing work, goals, deadlines
• reference — where to find things in external systems

Session memory is separate — things the agent learns during a conversation that don't need to persist forever.

Skill Modules

Skills are reusable workflows loaded from .claude/skills/ directories. Each skill has a trigger (like /deploy), a prompt template, and tool requirements.

The agent can load skills at boot and register them as tools automatically.

Hooks

Hooks let you add custom behavior before or after agent events — like logging every tool execution, transforming inputs, or blocking specific actions. They run in priority order and can modify data flowing through the pipeline.

Hook events: tool execution, permission checks, session lifecycle, message adds, streaming events, turn start/end, boot completion, transcript compaction.

Monitoring

Event Stream

The agent emits structured events in real time:

• tool_selected — which tool the agent chose and why
• permission_check — whether it was granted or denied
• message_delta — text being streamed
• usage_update — current token counts
• message_stop — why the turn ended (completed, budget, error, etc.)

System Logs

Structured JSONL logs at ~/.openclaw/logs/{date}.jsonl. Contains initialization events, tool executions, permission decisions, errors — everything the system does, separate from the conversation.

Audit Trail

Every permission decision is recorded: which tool, granted or denied, why, when, and which check in the pipeline made the decision.

Health and Safety

Health Check

just agent-doctor

Checks Node.js, GitHub CLI, 1Password, session directory, just, and shellcheck.

Safety Invariants

just agent-verify

Verifies 5 invariants:

1. Destructive tools always require approval
2. Denied tools never execute
3. Budget exhaustion produces a graceful halt
4. Sessions round-trip correctly (persist → resume)
5. Permission decisions are always logged

All Commands

Command	What It Does
just agent-run	Start the interactive agent REPL
just agent-doctor	Check system health
just agent-verify	Verify safety invariants
just agent-test	Run all 373 tests
just agent-test-watch	Run tests in watch mode
just agent-typecheck	Check TypeScript types
just agent-build	Compile TypeScript to dist/