Netclaw Operations

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.

File and Shell Selection

When available, use file_read for a known local file read. When available, use file_list for a known local directory listing. Use file_search for bounded recursive name or literal text search. Use file_read for image metadata. Use attach_file with the authorized source path. The tool copies it into the session when necessary. A linked or protected destination causes a denial. Do not use shell to bypass that denial. Issue independent file_read calls in parallel when several paths are known. Use tool_output_read to continue a spilled result by call id. When available, use file_write or file_edit for a known local file change. When available, use web_search for external discovery and web_fetch for a known external page. When available, use shell_execute for local search, VCS, builds, tests, processes, or requested shell behavior. Do not substitute shell commands when a listed first-party tool satisfies the task. Do not delegate a known file operation that an available file tool can complete. After a successful file tool result, do not use shell only to verify it unless the user requests shell behavior. For disposable text, use file_write in temp_dir, then use file_read; do not attempt a shell redirect first. Standard temporary APIs use temp_dir in each shell process. Use load_tool directly for a known exact tool name. Use search_tools when the capability is known but its exact tool name is not.

Keep shell approval friction bounded:

1. Start with the smallest single shell operation that directly answers the request.
2. Use one operation per call. Keep independent searches and diagnostics separate; do not join them with separators or labels.
3. Add a pipeline only when the requested result requires it.
4. Do not use shell only to verify a successful structured tool result.
5. If approval is required but no interactive requester is available, do not retry or substitute the call during that turn.
6. After an access denial, do not retry that call during the same user turn.
7. Do not change its scope or substitute another tool to evade the denial.
8. A later explicit user request can start a new call. Apply the normal approval policy to that call.
9. Apply all compatible advice in a correction response before the next call.
10. A shell call can return correction advice under Auto. Auto removes approval prompts; it does not remove corrections.
11. Advice grants no authority. Every replacement call passes current policy.
12. If you require the exact platform path, retry unchanged once through normal policy.
13. Reviewed diagnostics without file output do not receive temporary relocation advice. Normal approval and denial rules still apply.

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').

Choose directories in this order:

1. For declared-project work, omit WorkingDirectory; the shell uses project_dir.
2. For one call in a named child directory, set typed WorkingDirectory.
3. Use temp_dir for disposable files. Standard temporary APIs already use this directory.
4. Use an inline directory change only when the task requests that behavior.

Typed WorkingDirectory and absolute operands give exact scope but add no safe-space root. Program-specific directory options do not replace WorkingDirectory. If shell advice names use_shell_working_directory, remove the leading cd from a new call. Set WorkingDirectory to the suggested child directory. The original call did not run. The new call passes normal approval policy. If the task needs the original shell directory behavior, keep the command and set WorkingDirectory to project_dir. That explicit project scope skips repeated advice. The original command still passes normal approval policy.

When available, call set_working_directory before the first tool call for another user-named project. This rule applies to shell tools, file tools, subagents, and absolute path operands. Do not repeat the call when [working-context] already names that project. If the tool rejects a path, declare the user-provided fallback before other tools. Do not probe a named project path before declaring it. Use the task's first project path exactly; do not substitute its parent first. Honor a request to keep the current project unchanged. A denied child-directory call does not permit a project change.

Managed Session Storage

The [session] block separates five paths:

• session_dir is the workspace and the relative-path fallback.
• temp_dir is run-local storage for disposable files.
• artifact_dir is the run-owned output area.
• worktree_dir is the session area for Git worktrees.
• log_path is the exact raw audit log for the current run.

Use file_read to read the exact log_path for the current run. Public and Team cannot access other sessions without explicit configured roots. Versioned parent and child runs share the current session envelope. Legacy runs can read their own exact log, but not separate parent or child logs. Use a legacy child's summary and shared-workspace artifacts instead. Directory list and search require directory authority; an exact log grants none. Do not use shell to find session logs. Normal audience and operation policy applies to every session path. Attachment copies and fetched files must pass destination checks before Netclaw saves them. A permitted copy or fetch does not enable general file-write access. If a save fails, report the tool error; do not claim that the file exists. Netclaw does not automatically remove managed temporary files or worktrees.

Use shell_execute to run Git with a destination below worktree_dir. After Git succeeds, use set_working_directory to adopt the created path. A failed Git command does not change project scope.

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.

Every tool call requires a non-empty _rationale string. State the call intent and reason in one sentence. Apply this rule to each parallel call and each later tool iteration. If a correction reports a missing rationale, fix every call before the retry.

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.

A repeated action-and-outcome correction means that no requested call ran. Choose a different action or finish the task from the available evidence. Do not repeat the blocked batch. Netclaw disables tools for the turn if the same blocked batch appears again. Report incomplete work and do not claim that the blocked operation succeeded. If validation rejects metadata, repair the reported value before the retry. A valid metadata repair is not the same rejected action. A new user message starts a fresh cycle window; compaction alone does not. If a text-only response contains tool calls, Netclaw rejects those calls and reports a provider failure. This failure does not prove that the turn exhausted its tool budget.

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 retains the full redacted output inside the current session. Use tool_output_read with the returned CallId, Start, and Limit values. Do not request a path or rerun the source tool to read 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. Netclaw deletes a terminal job's definition and logs 24 hours after completion.

Use bounded continuation before 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 load_tool(name) when an exact deferred tool name is known. Use search_tools(query) to find tools by capability when the name is unknown. Full guidance: skill_read_resource('netclaw-operations', 'references/tools.md').

MCP servers can also supply workflow skills. These skills use names such as mcp__gigatron__month_over_month. Review the normal skill index first. Use skill_load(name, arguments) when one of these workflows matches the request.

The argument hint marks values that the MCP server requires. Supply those values exactly. Do not invent a missing value. A loaded prompt can name MCP tools, but it does not grant them. Use the normal search_tools and load_tool flow for each required tool.

MCP OAuth

For HTTP/SSE MCP servers, the Model Context Protocol .NET SDK owns PKCE, authorization-code exchange, token refresh, and the related HTTP calls. Netclaw owns protected-resource discovery and dynamic client registration (DCR), presents the authorization URL, brokers the browser callback, and durably stores active credentials. Do not fetch metadata or token endpoints by hand, build PKCE requests, or create or repair mcp-oauth-metadata.json; legacy metadata files are ignored.

Netclaw requests JSON token responses from providers that negotiate the response format, including GitHub. This request keeps the response compatible with the MCP SDK token decoder.

Netclaw registers rather than letting the SDK do it because the SDK hard-codes token_endpoint_auth_method: "client_secret_post" and ignores what the authorization server advertises, which fails against servers that accept public clients only. Netclaw registers with the method the server advertises first. Registration happens only during netclaw mcp auth <name>, never on a background reconnect.

Authorize a server

Run this with the daemon active:

netclaw mcp auth <name>

The command starts an unpublished client candidate, opens the authorization URL when possible, always prints it, and waits up to five minutes. Complete the browser flow normally. If the callback cannot reach this machine, paste the full redirect URL into the command. Netclaw keeps exchanged credentials local to the candidate, then commits them once and publishes the client only after tool discovery succeeds. A failed replacement does not alter durable credentials or displace an existing healthy connection.

The SDK redirect URI is http://127.0.0.1:{Daemon.Port}/api/mcp/oauth/callback. If the provider requires a pre-registered redirect URI, use the configured Daemon.Port, not a fixed default port.

A configured Authorization header takes precedence over SDK OAuth. Netclaw sends that header unchanged, does not start SDK OAuth after a challenge, and rejects netclaw mcp auth <name> until the header is removed. Check or rotate the configured header instead of trying to layer OAuth on top of it.

OAuth credentials are bound to the server's canonical configured resource identity. If the same profile name is pointed at another resource, Netclaw withholds its old tokens and dynamically registered client credentials, reports AwaitingAuth, and preserves the old durable record until replacement succeeds.

A token record written before resource binding existed is migrated in place when its legacy resource describes the configured endpoint, so upgrading does not force reauthorization. A trailing slash, path case, and a bare-origin resource indicator all still match; a different scheme, host, port, query, or sibling path does not, and those report AwaitingAuth with both bindings written to the daemon log. An explicitly configured static OAuth client ID remains authoritative.

If a server rejects the stored client identity as invalid_client — usually because the registration was deleted on their side — Netclaw discards that identity, keeps the tokens, and registers a new client on the next netclaw mcp auth <name>. No manual cleanup is needed.

If a server's authorization server publishes no registration_endpoint, or rejects registration, the error names the remedy: register a client manually with that provider and set it with netclaw mcp add --client-id <id> ....

Read connection states

At startup, the daemon connects enabled MCP servers concurrently. It waits for each initial attempt before it reports ready. A failed server has its own status; other server tools remain available. Use netclaw mcp list to inspect each result.

Diagnose failures

netclaw mcp list    # configured servers plus live daemon connection states
netclaw doctor      # MCP config and health checks
netclaw status      # daemon connector health, including MCP

netclaw doctor uses live daemon state when available. If the daemon is down, it can probe connectivity but cannot verify SDK-managed OAuth; start the daemon for an authoritative auth result.

OAuth failures return safe structured errors with an error, an operation, and, when known, an HTTP status. The CLI prints the useful message rather than raw JSON. A blank provider body still produces a structured daemon error from its HTTP status. If the daemon response body is blank or malformed, the CLI falls back to HTTP <code> <reason> instead of showing an empty error. Check daemon logs for full server context; operator-facing errors omit authorization codes, tokens, PKCE data, and client secrets.

Credential persistence fails loudly. If the durable secrets write fails, authorization fails, active credentials do not change, and the candidate is not published. Fix the filesystem or secrets-store error shown in daemon logs, then run netclaw mcp auth <name> again; browser success alone does not mean the MCP connection is ready.

Approval Prompts

MCP approval prompts show a bounded, redacted preview of the call arguments. Actual path- and URL-shaped values appear first and receive a larger preview so the operator can verify location context without guessing from argument names. URL credentials, query values, and fragments are redacted. Large strings, binary data, and nested collections are summarized by size; secret-like fields and token-shaped values are always redacted. Argument names and values are escaped before display so server-controlled schema text cannot break or spoof the approval prompt. MCP grants are tool-wide rather than directory-scoped, so these prompts omit the misleading Always here option and label the persistent choice Always allow this tool rather than the shell-oriented Always anywhere. Other non-shell tools also omit Always here because their approval matchers do not consume directory scope.

Shell approvals store a typed phrase and a scope 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 path field for folder and global grants. Netclaw sets it from:
  • 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.

This repository stores a distinct Git repository scope. It applies to registered worktrees of one repository. Netclaw checks Git registration for each use. A folder grant keeps its path scope. An unapproved verb or a path outside the worktree still needs approval. The scope supports an ordinary .git directory and registered linked worktrees. A main checkout with --separate-git-dir does not receive this choice.

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.

For a complete static Bash list with an exact directory change, Netclaw checks each command in each reachable exact directory. A failed cd can leave a later command in the original directory. Each unapproved verb still needs approval. Dynamic effects and linked directories retain exact approval.

The approval gate runs three layers in order:

The directory order reserves temp_dir for disposable output. Preserve an explicitly required platform temporary path. Netclaw does not automatically clean managed temporary storage yet.

1. Hard-deny list — system-protected paths. Always blocks.
2. 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.
3. Interactive prompt — everything else. A registered worktree can show six choices:
   • 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.
   • This repository — persist a grant for this Git repository. Registered sibling worktrees can use it for the same phrase.
   • 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.

# Interactive TUI: see everything grouped by audience and tool
netclaw approvals

# List — human-readable. Entries print as "<verb> in <dir>" or "<verb> anywhere",
# each followed by when the grant was added ("added 3 days ago"; "added —" for
# grants saved before timestamps were tracked).
netclaw approvals list
netclaw approvals list --audience personal --tool shell_execute

# Scriptable JSON output (audiences → tools → typed entries)
netclaw approvals list --json

# Revoke by user-visible form (the same labels list emits)
netclaw approvals revoke "git remote in /home/user/repos/foo/"
netclaw approvals revoke "freshdesk anywhere"

# Pre-approve a verb as a global wildcard for unattended/scheduled tasks
netclaw approvals trust-verb freshdesk
netclaw approvals trust-verb gh --audience team

# Clear every entry for a tool (optionally scoped to one audience)
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

Headless COMPACTION records expose summarized and tool_results_cleared phase evidence. A true summary flag does not prove that the summary retains every task requirement. Older daemon or CLI versions can omit these flags from the transport and report false. Check the actor log before you conclude that an older run skipped a phase.

When something is broken, start with netclaw status, then netclaw doctor. Feature kill switches and self-update/health are covered in the reference. Memory embeddings can be backfilled with netclaw memory backfill-embeddings [--force]; doctor checks memory embedding availability. Full guidance: skill_read_resource('netclaw-operations', 'references/diagnostics.md').

Identity

Your identity is defined by layered files loaded into the session prompt:

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').