| name | netclaw-operations |
| description | REQUIRED when the user asks about scheduling, reminders, cron jobs, timers, background jobs, diagnostics, troubleshooting, MCP tools, daemon health, identity updates, or Netclaw capabilities and self-maintenance. |
| metadata | {"author":"netclaw","version":"2.33.0"} |
Netclaw Operations
This is your operational guide. Load it when the user's request is about
Netclaw itself — what it can do, how to schedule work, how to diagnose
problems, how to update preferences, or how to maintain itself.
Route by Intent
Safety-critical and high-frequency guidance (tool arguments, large output,
approvals, identity-vs-memory routing) is inline below. Everything else lives in
a reference file — load the one matching the user's intent with
skill_read_resource.
| User intent | Where |
|---|
| Schedule reminders/cron; run background shell jobs | skill_read_resource('netclaw-operations', 'references/scheduling.md') |
| How tool arguments are validated | Tool argument validation |
| Handle very large tool output | Large tool output |
| Understand approval prompts | Approval Prompts |
| Update identity / where facts go (identity vs memory) | Identity |
| Work on a project, switch projects | skill_read_resource('netclaw-operations', 'references/projects.md') |
| Discover MCP / available tools | skill_read_resource('netclaw-operations', 'references/tools.md') |
| Manage skills and sources | skill_read_resource('netclaw-operations', 'references/skills.md') |
| Manage inbound webhooks / attachments | skill_read_resource('netclaw-operations', 'references/webhooks.md') |
| Add/switch LLM or search provider, OAuth login | skill_read_resource('netclaw-operations', 'references/providers.md') |
| Diagnose problems, kill switches, self-update | skill_read_resource('netclaw-operations', 'references/diagnostics.md') |
| Rotate or repair secrets | skill_read_resource('netclaw-operations', 'references/secrets.md') |
| Pair remote devices, manage access | skill_read_resource('netclaw-operations', 'references/devices.md') |
| Kick the tires on Netclaw end-to-end locally | skill_read_resource('netclaw-operations', 'references/demo-apphost.md') |
Project Directory
set_working_directory(path) sets the session's project root (absolute path within
allowed roots); the project's identity file (.netclaw/AGENTS.md, CLAUDE.md,
AGENTS.md, or CONTEXT.md) then loads into the prompt. Full rules:
skill_read_resource('netclaw-operations', 'references/projects.md').
For Team and Personal sessions, [working-context] is refreshed at the start
of each new turn. In a Git project it includes the active worktree, branch,
HEAD, upstream divergence, and dirty counts. Treat this as turn-start
grounding: a checkout or commit performed during the current tool loop appears
in the next turn's snapshot. If Git is unavailable, the turn continues with an
explicit unavailable status rather than invented repository state. Subagents
receive a read-only project/recent-file snapshot. Successful and partial runs
return only file edits confirmed through their own tools; failed or cancelled
runs contribute no parent working-context changes.
Scheduling & Background Jobs
Reminders: set_reminder with schedule type once / interval / cron. Always
set delivery_kind explicitly (current_session / channel / none). A reminder
that fires unattended cannot answer approval prompts, so pre-approve any shell verbs
it needs first with netclaw approvals trust-verb <verb>. Background shell: set
_background: true on shell_execute (max 5 concurrent; cancel servers/watchers
when done; background jobs are killed when the session passivates).
Full detail — delivery contract, proactive channel messaging, approval scoping,
job lifecycle — is in
skill_read_resource('netclaw-operations', 'references/scheduling.md').
Tool argument validation
Prefer the canonical argument names exactly as a tool declares them, and the
canonical meta keys _rationale, _timeout_seconds, _background (leading
underscore, snake_case). Recognition is spelling-tolerant so a near-miss is
consumed rather than dropped: declared params fold case/punctuation, and the
meta keys also accept the underscore-dropped/cased/shortened forms
(TimeoutSeconds, timeout_seconds, Timeout → the timeout hint; Rationale,
Background likewise). The supplied value is always used — never silently
defaulted.
Three things are still rejected loudly, and when rejected the tool did NOT run —
fix and re-issue once, do not retry the same shape:
- Unknown keys — a key that matches no parameter and no meta field rejects
with a
did you mean '<canonical>'? suggestion and the list of valid names.
- Invalid values — a value that cannot parse as its type (
_timeout_seconds: "1200ms", _background: "yes") rejects instead of falling back to a default.
- Ambiguous meta spelling — supplying two keys that map to the same meta
field (e.g. both
_timeout_seconds and TimeoutSeconds) rejects; send one.
Large tool output
Tool output is bounded to a small inline budget
(Session.Tuning.MaxInlineToolResultChars, default 2000 chars) so it never floods
the context window. When a tool's output exceeds that budget you get a head+tail
view inline plus a pointer to the full output — not the whole thing:
shell_execute spills the full (redacted) output to
{session}/tool-calls/{toolCallId}.log and gives you the path. Read a slice with
file_read (StartLine/Limit) or grep it — do NOT re-run the command to see more.file_read on a large file returns the head and steers you to read a
specific range with StartLine/Limit or grep (StartLine is a 1-based line
number — line 1 is the first line). Don't cat a huge file through
shell_execute to get around it — that just spills again.background_job output goes to ~/.netclaw/jobs/{id}/output.log (bounded);
check_background_job returns a tail, and you can file_read/grep the log for the rest.
Reading a targeted range or grepping is always cheaper than re-running a command or
re-reading a whole file. Secret-bearing values are redacted from all tool output.
Tool Discovery
Only a core toolset is always loaded. Use search_tools(query) to find additional
or MCP tools by capability before concluding a tool doesn't exist. Full guidance:
skill_read_resource('netclaw-operations', 'references/tools.md').
Approval Prompts
Approvals are typed (verb, directory) pairs in tool-approvals.json:
- verb — the command head plus subcommand chain only (e.g.
git push,
grep, freshdesk). No flags, no path arguments.
- directory — the directory the grant applies to. Sourced two ways:
- Path argument in the original command (
find /repo, ls /var/log,
cat ~/.bashrc). The path argument is the directory; for file targets
the parent directory is used so cat ~/.bashrc scopes to ~.
- Cwd when no path argument is present (
git status, freshdesk).
null for the global wildcard ("approve this verb in any
directory") — only set by Always anywhere.
Folder-scoped trust compounds. An entry on (find, /home/user/repo)
auto-allows find /home/user/repo/.netclaw -name X because the candidate's
extracted path is under the entry's directory. You don't have to call
set_working_directory for this — running a command with a path argument
declares scope implicitly.
The approval gate runs three layers in order:
- Hard-deny list — system-protected paths. Always blocks.
- Safe-verb ∩ safe-space short-circuit — when the verb is on the curated
safe list AND the effective directory (path arg or cwd) is under your
declared safe space (
session_dir or project_dir), the call auto-runs
with no prompt. The list covers demonstrably read-only verbs: file readers
(ls, grep, cat, …), system/info verbs (date, whoami, uname,
uptime, …), and read-only git/gh queries (git status, git log,
gh pr view, gh run list, …). Mutating verbs (git push, git fetch,
rm, sed -i), command-prefixing verbs (env, xargs, sudo),
network-writing verbs (gh api, curl), and environment/process-inspection
verbs (printenv, ps) are never on the list — the safe-space gate
cannot scope a verb that dumps the environment or the process table.
- Interactive prompt — everything else. Five buttons:
- Once — run this one time, persist nothing.
- This chat — allow the verbs in this directory for the rest of the
session.
- Always here — persist
(verb, effective directory). The
"directory" is the command's path argument when present, else cwd.
- Always anywhere — persist
(verb, null) global wildcard.
Danger style.
- Deny — refuse this call only.
Side-effect-only clauses are authorized but not persisted. When a
compound command includes pure side-effect verbs (echo, printf, :,
true, false) with no path argument and no redirect, those clauses are
authorized for the current call by the click but no ApprovalEntry is
written for them. Recording every literal echo "===" would be noise.
Prompts survive passivation and restart. Pending approval prompts are
journaled with their requester and trust context, so if the session goes idle or
the daemon restarts before the user clicks, the click is still honored when it
arrives. Completed sibling tool results are journaled per call, so recovery
re-drives unresolved calls rather than replaying the whole batch. The only case
where a click does nothing is a genuinely expired prompt (the turn already
failed or was superseded); the session then posts a visible "approval prompt has
expired" notice rather than silently dropping the click. If a user reports a
stale button, ask them to re-issue the request.
Why you may not see a prompt at all. If the user invokes a read-only verb
(say grep) with a path argument under a tree the operator has previously
trusted, the safe-verb short-circuit applies and there is no prompt. This
is intended behavior — read-only inspection of declared work surfaces is
implicit. Mutating verbs in the same directory still prompt.
When the prompt offers fewer buttons. Two cases:
- Complex commands (bash control-flow like
for/while/done, unbalanced
quotes/brackets) get only Once and Deny. The matcher cannot extract a
clean verb chain to remember, so persistence is structurally impossible.
- Shallow cwd (e.g.
/etc/, /) hides Always here only. Persisting a
too-shallow root would grant the verb across most of the filesystem;
This chat and Always anywhere remain available.
If a user keeps getting prompted in their repo on read-only verbs, the
likely cause is the commands they're running don't carry a path argument
(e.g. git status with no -C). Suggest they call
set_working_directory <path> so the safe-verb short-circuit treats that
tree as a safe space. If they keep getting prompted for the same mutating
verb (e.g. git push), suggest Always here to persist
(git push, effective directory).
When auditing repeated prompts, check both the tool audit trail and daemon
logs. A later call satisfied by an existing grant records
ApprovalDecision=PreviouslyApproved and an ApprovalPattern like
git push [persistent: git push in /home/user/repo]. If the daemon prompts
despite a same-verb persisted grant, it logs an approval near-miss with the
candidate directory, cwd, persisted grant, creation time, and mismatch reason.
Inspecting, revoking, and pre-approving grants
Use the netclaw approvals CLI rather than hand-editing
tool-approvals.json. The daemon reads the file on every approval check, so
mutations take effect on the next prompt without a daemon restart.
netclaw approvals
netclaw approvals list
netclaw approvals list --audience personal --tool shell_execute
netclaw approvals list --json
netclaw approvals revoke "git remote in /home/user/repos/foo/"
netclaw approvals revoke "freshdesk anywhere"
netclaw approvals trust-verb freshdesk
netclaw approvals trust-verb gh --audience team
netclaw approvals revoke --tool shell_execute --all
netclaw approvals revoke --tool shell_execute --all --audience personal
revoke of a non-existent pattern exits non-zero with a clear message — the
CLI never silently succeeds. trust-verb is idempotent — re-running it on an
existing entry exits zero with "no changes."
Pre-approving for unattended tasks (load-bearing)
Reminders and webhooks fire without a human present and cannot answer prompts.
When you (the agent) are helping the user set up an unattended task that needs
shell commands, identify the verbs the task will need and proactively suggest
pre-approving them as global wildcards before the schedule fires.
Example dialogue when the user asks you to schedule a daily Freshdesk report:
"I'll set up a daily reminder that calls freshdesk --since=24h. Since
reminders run unattended and can't prompt for approval, I need to pre-approve
the freshdesk verb globally — that's a (freshdesk, null) entry, meaning
it will auto-allow in any cwd. Mind if I do that with
netclaw approvals trust-verb freshdesk?"
On confirmation, run the trust-verb command via shell_execute, then create
the reminder. The grant persists across daemon restarts.
Last-resort recovery
If the approval file gets corrupted (the daemon will quarantine it to
tool-approvals.json.invalid and warn loudly), or if a v1 store gets detected
during upgrade (the daemon quarantines it to tool-approvals.json.v1.bak),
the active file is reset and the v2 store starts empty.
To wipe every persistent grant and start clean, delete the file directly:
macOS/Linux:
rm ~/.netclaw/config/tool-approvals.json
PowerShell:
Remove-Item "$HOME/.netclaw/config/tool-approvals.json" -Force
Restart the daemon so in-memory session approvals are cleared too.
Skill Management
Skills load on demand; manage skills and sources via the skill tools. Full guidance:
skill_read_resource('netclaw-operations', 'references/skills.md').
Webhooks & Inbound Attachments
Inbound webhooks are configured per route; route files are secret-bearing and
protected. Attachment handling is covered alongside. Full setup + rules:
skill_read_resource('netclaw-operations', 'references/webhooks.md').
Secret Management
Secrets live in ~/.netclaw/config/secrets.json — never print raw secret values
in chat, issues, PRs, or logs. Set them via CLI (netclaw secrets set <Path> <value>),
never by direct file edit. Protected paths (secrets.json, .netclaw/keys,
config/webhooks) are always access-denied. Full rotation guidance:
skill_read_resource('netclaw-operations', 'references/secrets.md').
LLM & Search Providers
Add or switch model providers (including OAuth login) and configure search backends
(e.g. SearXNG) via provider config. Full setup:
skill_read_resource('netclaw-operations', 'references/providers.md').
Diagnostics, Kill Switches & Self-Maintenance
When something is broken, start with netclaw status, then netclaw doctor. Feature
kill switches and self-update/health are covered in the reference. Full guidance:
skill_read_resource('netclaw-operations', 'references/diagnostics.md').
Identity
Your identity is defined by layered files loaded into the session prompt:
| Layer | Source | Audience |
|---|
| SOUL.md | ~/.netclaw/identity/SOUL.md (filesystem) | All |
| AGENTS.md | Embedded in the Netclaw binary (audience-specific) | Team/Personal get full version; Public gets stripped version |
| TOOLING.md | ~/.netclaw/identity/TOOLING.md (filesystem) | Team/Personal only |
| Project instructions | .netclaw/AGENTS.md etc. in project directory | Team/Personal only |
AGENTS.md is binary-owned. The full AGENTS (Team/Personal) contains operating
rules, autonomy guidance, grounding, search policy, scheduling, background shell,
subagent delegation, skill reference, identity file paths, and memory triage. The
Public AGENTS contains only basic operating rules, autonomy, grounding, and media
attachment guidance.
SOUL.md and TOOLING.md remain editable on disk:
- To edit: read the file first with
file_read, then write with file_write.
- Detail subdirectories:
identity/soul/, identity/tooling/.
Identity vs memory — what goes where:
- Identity files define the agent: persona, tone, communication style, operating
rules, and the foundational user grounding set at init (the user's name, timezone).
Edit these only to change how the agent itself operates.
- Durable facts and preferences about the user learned or stated over time
(favorite things, family, history, working preferences) → memory
(
store_memory); they are recalled when relevant. A user asking you to "remember"
a preference is a memory write, not a SOUL.md edit.
When unsure: does it change who the agent is or how it operates? → identity file.
Is it a fact about the user to recall later? → memory.
Device Pairing
Pair remote devices and manage their access via the pairing flow. Full steps:
skill_read_resource('netclaw-operations', 'references/devices.md').
Demo AppHost
To demo or kick the tires on Netclaw end-to-end locally:
skill_read_resource('netclaw-operations', 'references/demo-apphost.md').
