When something is wrong.

setupclaw runs four things in order: download the orbit-hook binary, store your API key in the OS keychain, write the Claude Code hook config, run a self-test. A failure in any of the four is reported plainly, with the next command to run.

The two failures we see most:

• Download fails. Usually a network policy or a corporate proxy.curl and wget both work. If both are restricted in your environment, email support@orbitauthority.com and we will get you the binary URL and checksum directly so you can pull it through your own proxy.
• Keychain write fails. Common on stripped-down server installs without a desktop keychain service. setupclaw assumes a keychain. For server or headless installs, email support@orbitauthority.com. We have an env-var setup path we will walk you through.

Guardian only texts the verified number on file at /settings/phone. If approval requests are not arriving, walk this list:

1. Confirm the verified number on /settings/phone matches the phone you are watching. We have seen multi-line setups where the verified number is the work line and the user is checking the personal one.
2. Confirm the action matched an Ask me first rule. Open /audit for the recent action; the row shows which rule matched and its mode. Guardian only sends SMS when the matched rule is Ask me first. If the matched rule is Allow or Block, no SMS was sent. Guardian had a definitive verdict and did not need to ask you.
3. Check your SMS filter. Some carriers route short-code SMS to a separate folder; iOS “Filter Unknown Senders” sometimes hides ORBIT messages until the sender is approved.
4. Try replying STOP then STARTfrom the verified number. That re-arms the carrier’s opt-in state if it ever drifted.

If the audit shows Ask me first actions and the carrier is delivering nothing, email support with the action ID; we can look at the SMS provider logs.

Three things have to be true for a Claude Code action to land in your dashboard: the hook is installed, the hook can find your API key, and the hook can reach the ORBIT API. Test each:

orbit-hook whoami

Prints the account the hook authenticated as. If you get an account name, the hook is installed, the API key is reachable, and the network path is open. The dashboard should start receiving actions on the next Claude Code call.

If whoami errors:

• “command not found”. The orbit-hook binary is not on your PATH. setupclaw puts it at ~/.local/bin/orbit-hook by default; confirm that directory is in your shell PATH.
• “no API key”. The hook cannot find the key. setupclaw stores it in the OS keychain; if the keychain failed silently or the key was deleted, reissue a key at /keys and re-run setupclaw.
• “unauthorized”. The key the hook is sending is not recognized by the API. Most often this means the key was rotated and the hook still has the old one. Reissue at /keys; setupclaw refresh stores the new one.
• “network unreachable”. Firewall or proxy in the way. The hook talks to https://api.orbitgrc.com over HTTPS. Allow that hostname.

An API key’s plaintext is shown once, at issue time, and never again. After that the /keys page shows a prefix only.

There is no recovery path. Issue a new key from the same page and update the hook (re-run setupclaw, or for manual installs update the env var or keychain entry). The old key keeps working until you explicitly revoke it, so you do not have to coordinate the rotation perfectly.

Guardian only blocks an action if the matching rule is set to Block. If you expected a specific action to be stopped and it was not:

What audit can and cannot prove: /audit shows what ORBIT observed and how it decided on the actions it saw. Absence of a row is not proof the agent did nothing. If Guardian was offline, the hook was not loaded, or the action took a path Guardian does not intercept, the action will not appear here.

1. Find the action in /audit. Note the rule that matched (or that no rule matched).
2. Open /dashboard/agent-policy, find that rule, and check its current verdict. If it is Allow, that is by design. Change it to Ask me first or Block; the next call follows the new rule.
3. If no rule matched, the action falls outside the 50 default rules. Either add a custom rule for that action shape from the cockpit, or accept that this risk class is not in the catalog yet (file a request at support).

Symmetric to the above. The same coverage caveat applies: /audit records what ORBIT observed; it is not a canonical log of every agent attempt. The most common path:

1. Find the action in /audit. The verdict will say Block; the rule that triggered is named.
2. If the rule’s verdict is Block but you wanted Ask me first, change it in the cockpit at /dashboard/agent-policy.
3. If the verdict was Block because an Ask-me-first rule timed out, you missed the SMS. See the No SMS arriving section above; the timeout default is Block by design (fail-closed).
4. If the action was blocked by a custom rule you forgot you wrote, the audit row links to that rule; open it and adjust.

The free Guard tier caps governed actions per month and burst rate per minute. The exact numbers are on /orgunder Plan & Limits.

If your hook is getting 429 Too Many Requestsresponses, you have hit the per-minute burst cap. The hook backs off and retries; if you hit the cap repeatedly, the monthly cap is approaching. Check Plan & Limits.

If you hit the monthly cap, every governed action returns 429 until the first of the next month. Upgrade to Guard from /billing to lift the cap. Receipts for the rate-limited actions are not generated; the actions did not enter the governance loop.

Check your installed version:

orbit-hook --version

The hook prints a one-line warning if it detects a newer published version. The warning does not block; the hook keeps working. Update on your schedule by re-running the setupclaw binary you already have locally:

setupclaw

setupclaw is idempotent: re-running it overwrites the orbit-hook binary in place, leaves your API key and Claude Code config alone, and runs the self-test again. We do not recommend re-fetching the install script over the network as an update path; the orbit-hook binary mediates agent actions, so the update path should not introduce a new unverified network fetch. If your local setupclaw is also out of date or missing, email support@orbitauthority.com for the signed binary URL and sha256 checksum.

The offline verifier checks a .orbitprooffile’s signature against ORBIT’s pinned public key. A mismatch means one of three things:

• The receipt was edited after ORBIT signed it. Even a single byte change breaks the signature. Re-download the receipt from your /audit page; that copy will verify.
• The pinned public key on your machine is older than the receipt. ORBIT rotates the signing key periodically. The CLI reports the signer ID it expected and the signer ID on the receipt. If they differ, fetch the current public key from /verify (the page shows it inline) and update your pin.
• The file is not actually a .orbitproof. Schema check fails before the signature check. The CLI prints the schema reason; the file may be JSON but not match the receipt schema.

If the file is a real ORBIT receipt and verification still fails after fetching the current public key, that is unexpected. Email support@orbitauthority.com with the receipt ID (visible in the audit), the CLI signer ID it expected, and the signer ID on the receipt. Do not attach the .orbitproof file by email. Receipts are private to the owning account; we will request the file through a secure path if needed.

Email support@orbitauthority.com when:

• The audit shows Ask me first actions but no SMS is arriving on the verified number.
• orbit-hook whoami succeeds, your agent is making calls, and the dashboard still shows nothing.
• A real .orbitproof from your audit fails to verify offline after you fetched the current public key.
• You hit a 5xx response from the API that does not clear on retry.
• Anything that looks like a security issue. Use the same address.

Include the action ID or receipt ID where relevant. Reply latency is human-fast at launch volume.