# OpenClaw Operations

This document covers OpenClaw-specific installation choices, optional tool
routing, configuration, approval policy, recovery, and diagnostics. For
ordinary AKK commands and cross-Host reliability semantics, use the
[Operator Guide](operator-guide.md). AKK 0.14.0 introduces the Codex CLI
backend, Desktop, and backend Recovery support described here.

## Requirements and compatibility

- Node.js supported by the installed OpenClaw release; Node.js 24 LTS is
  recommended.
- OpenClaw `2026.6.5` or newer for normal packaged installation.
- Plugin API and Gateway `2026.5.12` or newer. The adjacent tested boundary,
  `2026.5.10-beta.2`, lacks the required session workflow API.
- An existing supported coding-agent environment running under the same OS
  user as OpenClaw and AKK; choose its setup below.

| Coding-agent environment | Requirement |
| --- | --- |
| Codex CLI shared backend | An authenticated, loaded main CLI conversation on a compatible local backend; [CLI backend guide](codex-cli-native-compatibility.md). No tmux or Herdr required. |
| Codex Desktop | The supported local app and the intended conversation open in its original owner; [Desktop guide](codex-desktop-compatibility.md). No tmux or Herdr required. |
| Codex or Claude Code terminal | An authenticated CLI in tmux or local Herdr `0.8.0` using socket protocol 19; [tmux](quickstart-tmux.md) or [Herdr](quickstart-herdr.md) setup. |

OpenClaw and AKK inspect local processes, private backend endpoints, and any
selected terminal provider. Workspace is not a routing boundary: exact current
conversation identity and explicit user selection are. Terminal setup
instructions apply only when using the terminal route.

## Choose one installation path

Use one AKK installation per OpenClaw profile: ClawHub, npm, or a linked local
checkout. ClawHub is the normal OpenClaw path; npm also provides the standalone
CLI. A [local development build](#local-development-build) is optional.

### ClawHub

This installs the OpenClaw plugin with the 0.14 backend, Desktop, and terminal
capabilities:

```bash
openclaw plugins install clawhub:@scotthuang/agent-knock-knock
openclaw gateway restart
```

ClawHub installs the plugin, bundled AKK skill, and package-local relay CLI.
The plugin always uses that bundled relay. It does not add the standalone
`agent-knock-knock` command to the shell `PATH`.

### npm

Use npm only when the standalone shell CLI is also wanted:

```bash
npm install -g @scotthuang/agent-knock-knock
agent-knock-knock install-openclaw --verify
```

`install-openclaw` detects whether the installed OpenClaw supports capability
consent. When supported, this explicit installation command passes
`--accept-capabilities` to both fresh and replacement plugin installs and
reports `capability_consent: "accepted"` in its result. Older OpenClaw versions
continue through the same installation path without the unsupported option.

Do not run `install-openclaw` after a ClawHub installation. These are
alternative installation paths. For a nonstandard OpenClaw executable:

```bash
agent-knock-knock install-openclaw --verify \
  --openclaw-bin /absolute/path/to/openclaw
```

## Local development build

Use a reviewed checkout when developing AKK or evaluating source changes.
This optional source installation is not required for the 0.14 backend or
Desktop features. Choose an OpenClaw profile with no other AKK installation,
or remove its existing installation
through OpenClaw's plugin management before linking this checkout. Do not
layer the link on top of a ClawHub or npm-installed plugin in the same profile.

From the reviewed repository checkout, build and link the plugin:

```bash
npm ci
npm run build
openclaw plugins install --link .
openclaw plugins enable agent-knock-knock
openclaw gateway restart
```

Keep the checkout available while the plugin is linked. After changing its
source, rebuild and restart the Gateway so it loads the new compiled code.
For CLI backend or Desktop use, start with a fresh AKK List, select the intended
conversation, and inspect its Status and advertised capabilities. These paths
use their own setup guides above; a terminal session is not a prerequisite.
`/akk doctor` checks the terminal-oriented installation environment. Missing
terminal prerequisites in that result do not establish that a backend or
Desktop conversation is unavailable. See [Contributing](../CONTRIBUTING.md)
for development checks.

## Optional natural-language routing

Direct `/akk ...` commands bypass model tool selection and require no tool
policy change. To let OpenClaw decide to call AKK from natural language, grant
the optional `agent-knock-knock` tools.

With the default `coding` profile and no existing `tools.allow`:

```json5
{
  tools: {
    profile: "coding",
    alsoAllow: ["agent-knock-knock"]
  }
}
```

If a restrictive `tools.allow` already exists at that scope, add
`"agent-knock-knock"` to it instead. Do not configure `allow` and `alsoAllow`
at the same scope. Restart the Gateway after changing tool policy.

## Configuration

AKK requires no project-specific plugin configuration. Optional settings live
under `plugins.entries.agent-knock-knock.config`:

| Option | Default | Purpose |
| --- | --- | --- |
| `storeDir` | `~/.agent-knock-knock/store` | Stable AKK Session, Turn, Watch, receipt, and callback-outbox Store. |
| `openclawBin` | Auto-detected | OpenClaw CLI used by the callback adapter. |
| `codexHome` | Auto-detected | Optional Codex home used for native-session discovery. |
| `idleTimeoutMinutes` | `10080` | Retention checked during controlled reconciliation. |
| `agentTimeoutMinutes` | `60` | Terminal inactivity timeout. |
| `agentHardTimeoutMinutes` | `720` | New Send/Watch hard lifetime across backend and terminal routes starting in AKK 0.14.1; also the default backend Renew duration. AKK 0.14.0 backend Send/Watch used 60 minutes when this setting is omitted. |

A custom `storeDir` must be a dedicated private directory. AKK initializes a
missing or empty path and refuses a non-empty manifestless directory instead
of guessing how to write it. The complete schema is in
[`openclaw.plugin.json`](../openclaw.plugin.json).

## Manual approval

AKK preserves the coding agent's existing permission mode. An approval
callback is not authorization: the Host must refresh Status, show the current
request, obtain explicit human confirmation, and invoke only the approval
action advertised for that exact prompt.

CLI backend and Desktop approvals use the current typed interaction in the
original native task and controller session. Copy the advertised interaction
and decision; do not translate terminal approval keys into backend requests.
See the [CLI backend](codex-cli-native-compatibility.md) and
[Desktop](codex-desktop-compatibility.md) guides for supported request types.

Terminal approval has separate boundaries. Claude Code manual approval is
deliberately narrow. It supports the current AKK-managed Turn only and
requires an exact one-time Bash **Yes** choice
correlated with the owner-private transcript. Persistent permission choices,
unknown dialogs, and changed evidence remain manual in the TUI.

Codex may also advertise terminal-scoped approval when the exact visible prompt
is known but managed foreground UUID attribution is unavailable. The action is
prefilled with the exact `terminal_id`; never construct or guess it. Both paths
retain the confirmation offer and prompt fence privately and recapture them
under lock immediately before sending one key.

## Automatic approval

Trusted Codex and supported hookless Claude terminal commands can optionally
be auto-approved with a deterministic, default-disabled policy:

```json5
autoApprove: {
  enabled: true,
  rules: [{
    id: "project-read-status",
    agents: ["codex", "claude"],
    workspaces: [
      "/absolute/path/to/project-a",
      "/absolute/path/to/project-b"
    ],
    commands: [["pwd"], ["git", "status"], ["git", "diff", "--stat"]]
  }]
}
```

Place `autoApprove` inside the plugin `config`. Each rule may authorize
multiple canonical workspace roots; `autoApprove.rules[].workspaces` is the
sole workspace boundary for automatic approval and does not limit discovery or
manual control. Rules match only the configured agents and exact argument
vectors. Shell composition, substitutions, globs, environment assignments,
unparseable commands, and paths outside every authorized root remain manual.
Terminal Watch approval notifications never participate in auto-approval.

## Supervisor and callbacks

OpenClaw starts one non-overlapping AKK supervision cycle at startup and after
each previous cycle completes. Terminal managed-Turn monitors, Terminal
Watches, CLI backend Watches, and Desktop Watches have independent recovery
phases and error boundaries, so a failure in one does not starve the others.

For terminal managed Turns, with a writable Store, healthy Gateway, successful
reconciliation, and an unchanged Turn binding, AKK prepares one immutable
completion message and outbox entry within 30 seconds after reliable native completion evidence
becomes stable. External transport and wake acknowledgement are outside that
bound. Status remains the manual recovery path when presentation is delayed.

For CLI backend and Desktop work, retain the exact task ID returned by Send
or Watch. Use [backend task recovery](backend-task-recovery.md) for Recover,
Renew, Close, Unwatch, and Retry Callback. These operations target that original
task and controller session without terminal input. Close releases Send
management; it does not cancel Codex. Unwatch stops observation. A callback
accepted by OpenClaw does not prove delivery by a downstream chat channel, and
an uncertain callback is not eligible for manual replay.

Terminal binding and menu recovery remain separate; see
[terminal recovery and diagnostics](operator-guide.md#terminal-recovery-and-diagnostics).

## Troubleshooting

For CLI backend and Desktop, start with fresh List and Status for the selected
conversation or exact task. For terminal installation diagnostics, use:

```text
/akk doctor
```

With the standalone npm CLI installed, `agent-knock-knock doctor` additionally
checks the executable environment directly. Doctor's readiness result includes
tmux/Herdr and CLI prerequisites; a missing terminal requirement is not a
backend or Desktop health result.

| Symptom | Recovery |
| --- | --- |
| CLI backend conversation is missing | Check that the intended main CLI conversation is loaded under the selected local Codex home, then refresh List; see the [CLI backend guide](codex-cli-native-compatibility.md). |
| Desktop row has no live owner | Open that exact conversation in the supported Desktop app, then refresh List. Catalog membership alone does not grant Send capability. |
| No eligible terminal, when terminal control is intended | Start authenticated Codex or Claude Code inside tmux or supported Herdr as the same OS user, then refresh `/akk list`. |
| Plugin or callbacks cannot find OpenClaw | Configure `openclawBin`; for npm installation, pass the matching `--openclaw-bin` to `install-openclaw`. |
| Linked source changes do not appear | Run `npm run build` in the linked checkout and restart the Gateway; see [Local development build](#local-development-build). |
| Backend observation is stale, stopped, or expired | Inspect Status for the original `watch_id`, then use the action advertised for its state; [backend recovery](backend-task-recovery.md) distinguishes Recover from Renew. |
| Backend callback failed | Use only an advertised Retry Callback action for an eligible notification; select its exact `notification_id` when several are eligible. Accepted, in-flight, and uncertain deliveries cannot be replayed. |
| Terminal Turn is `stalled` | Inspect Status and the exact pane; use the advertised Renew action only if the same Turn is still live. |
| Terminal Turn is `callback_failed` | Use the advertised Retry Callback action; it reuses the original message identity. |
| Human native-thread switch conflicts with active terminal work | Ask the user whether to keep the old work or take over the current thread. Use only the nested fresh action returned by List. |
| Terminal List reports orphaned dispatch or transition state | Inspect the pane, then run only the exact Close recovery command returned by List. It leaves the coding agent and terminal running. |
| Claude approval is not offered | Resolve unsupported, persistent, stale, or uncorrelated dialogs in the TUI. |
| Claude request was not auto-approved | Check the enabled rule, agent, canonical workspace, exact argv, and current screen/transcript evidence. |

Terminal diagnostics:

```bash
agent-knock-knock status --conversation latest --trace
agent-knock-knock list --terminal-debug
```

For backend tasks, use the exact returned task ID instead of `latest`, for
example `agent-knock-knock status --watch '<watch_id>'`. Status for that task
reads its original backend without terminal input. List never types into a
terminal; a targeted conversation Status for an unbound, idle physical Codex
terminal may perform the closed identity inspection described in the
[Operator Guide](operator-guide.md#akk-status-and-native-inspection).

Trace and logs must not expose agent reasoning, raw callback payloads,
credentials, tokens, passwords, or proxy secrets.

## Trust and privacy

AKK has no hosted control plane or telemetry. Ordinary Send preserves the
coding agent's permission settings; an explicit supported permission action
applies the user's selected mode. Terminal, Session, Turn, Watch, receipt, and
log state stay on the local machine. Claude approval callbacks omit raw commands; Codex
may include bounded visible command detail so the Host can present it for
review.

Task content is still processed by OpenClaw and the coding-agent or model
providers configured by the user. Keep secrets out of prompts and review every
agent's permission mode.

For Store migration, filesystem permissions, retention, and log settings, see
[Storage and Logging](storage-and-logging.md). For development and release
workflows, see [Contributing](../CONTRIBUTING.md) and [Testing](testing.md).