#About OpenClaw maintenance agent

24 messages · Page 1 of 1 (latest)

dusk sparrow Apr 15, 2026, 3:59 AM

Hey Krill, I'm planning to set up a specialized ACP agent for openclaw infra ops — basically an autonomous agent that handles issue resolving in the openclaw directory, similar to what you do day-to-day. Before I build it out, I have a few questions across different areas. Could you answer in markdown code blocks so I can drop them straight into my notes?

Deployment & Environment

Should I run the ACP agent against a forked openclaw repo (PR-based workflow), or directly inside the running openclaw directory (immediate effect)? What's your recommended setup?
For reference docs — should the agent fetch them live from https://docs.openclaw.ai/llms.txt each session, or store a local copy? Any preference on freshness vs reliability tradeoff?

Permissions & Safety

What permissionMode do you recommend? approve-all for full autonomy, or something scoped down like approve-reads with specific write paths?
What guardrails should be in place for destructive operations — things like git reset --hard, service restarts, or direct openclaw.json modifications? What's the acceptable blast radius?
If running inside the live directory, how do you handle mutation risk — i.e., the agent's changes breaking the currently running instance? Hot-reload, staged restart, or something else?

Workflow & Scope

How should the agent receive issues? Discord thread binding, GitHub Issues webhook, manual dispatch via sessions_spawn, or some other trigger?
Should it commit fixes directly to the running branch, or work on feature branches and create PRs for human review?
What's the scope boundary — config changes only? Code patches? Dependency upgrades? At what point should it escalate to a human?

Context & Memory

Does the agent need access to openclaw's memory system (past issues, resolutions, known gotchas), or should it start fresh each session?
Should it be aware of changelog / release notes (e.g., v2026.4.11 changes) to distinguish new behavior from regressions?

SSH & Remote Execution

For running the ACP harness over SSH — any known issues with file I/O, the non-interactive constraint, or SSH session stability (latency, dropped connections)?

Thanks!

slim surgeBOT Apr 15, 2026, 4:04 AM

## Recommended setup for an OpenClaw infra-ops ACP agent

### 1) Repo target: fork/PR workflow, or live running directory?

**My recommendation:** neither as the default. Use a **separate local clone or git worktree** of the same repo, on a **feature branch per issue**.

- **Best default**
  - Keep the running OpenClaw checkout clean/stable.
  - Let the ACP agent work in a sibling worktree/clone.
  - Validate there, then promote the change with a human-reviewed merge/deploy.
- **Forks**
  - Good if you want GitHub-native PR review, cross-machine collaboration, or clear separation from upstream.
  - Not required if this is internal infra work on one host.
- **Live running directory**
  - Only for narrow, reversible ops changes.

  - I would **not** make this the default for a mutation-capable autonomous agent.

**Short version:** use a **worktree**, not the live tree.

---

### 2) Docs source: live `llms.txt` every session, or local copy?

**Primary:** use a **local checked-out docs copy plus `CHANGELOG.md`**, pinned to the deployed version/commit.  
**Secondary:** use `<https://docs.openclaw.ai/llms.txt>` as a **freshness check / fallback / index**, not as the only source.

Why:

- **Local docs win on reliability**
  - no network dependency

  - match the code you actually deployed
  - safer for version-specific behavior
- **Live docs win on freshness**
  - useful when debugging something that may already be fixed on `main`
  - useful for newly landed ACP behavior

**Practical rule**
- refresh local docs on deploy, upgrade, or at least daily
- fetch `llms.txt` only when:
  - local docs look stale
  - you are checking latest `main`
  - you suspect docs drift

---

### 3) `permissionMode`: `approve-all` or `approve-reads`?

Important nuance: **`permissionMode` is coarse**, not path-scoped.

From the ACP docs:
- ACP sessions are **non-interactive**
- default is `permissionMode=approve-reads` + `nonInteractivePermissions=fail`
- that means writes/exec can die with  
  `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`

So my recommendation is:

#### Option A, safer 2-agent pattern
- **Triage agent**
  - `permissionMode: approve-reads`

  - `nonInteractivePermissions: deny`
  - read/debug only
- **Remediation agent**
  - `permissionMode: approve-all`
  - `nonInteractivePermissions: fail`
  - but only inside a **fenced workspace/sandbox**

#### Option B, single trusted ops agent
Use `approve-all`, **but only if all of these are true**:
- dedicated agent
- dedicated workspace
- narrow tool policy
- `tools.fs.workspaceOnly: true`
- `tools.exec.applyPatch.workspaceOnly: true`
- narrow sandbox/workspace root

- not exposed to untrusted issue intake

**Bottom line:** if the agent is meant to actually fix things autonomously, `approve-all` is usually required, but the real safety needs to come from **workspace/sandbox boundaries**, not from `permissionMode`.

---

### 4) Guardrails for destructive operations, and acceptable blast radius

I would explicitly forbid or gate these:

#### Hard no, or human approval only
- `git reset --hard`
- force checkout over dirty work
- deleting branches/worktrees
- deleting session/state/config directories

- dependency upgrades with broad lockfile churn
- multi-host restarts
- credential/auth changes
- anything under `~/.openclaw/credentials/`

#### Allowed with guardrails
- **service restarts**
  - only one gateway at a time
  - only after health/status capture
  - only with rollback plan
- **`openclaw.json` changes**
  - prefer `openclaw config set` or `config.patch`
  - record previous hash/value first
- **small code patches**
  - only in repo workspace

  - branch first
  - test first

#### Acceptable blast radius
Keep it to:
- **one repo checkout**
- **one gateway instance**
- **one agent workspace**
- **one host**

And it should be reversible within minutes.

If a change can affect:
- shared credentials
- multiple users

- multiple bots/channels
- persistent state/data migration
- production auth/security posture

that is **human-review territory**.

---

### 5) Mutation risk in the live directory: hot-reload, staged restart, or what?

**Recommendation:** use **staged restart**, not blind live mutation.

Important split:

- **Config changes**

  OpenClaw supports config hot reload, and `gateway.reload.mode: "hybrid"` is the default. That is fine for many `openclaw.json` changes.
- **Code changes**  
  I would **not** rely on live mutation of the running source tree as the normal workflow.

#### Good pattern
1. patch in worktree/staging checkout
2. run checks/tests
3. verify `openclaw status` / `openclaw health --json`
4. promote change
5. do an explicit restart if needed
6. verify again

#### If you absolutely must run in the live tree
- keep changes tiny
- disable "edit and instantly restart everything" style loops

- do not let the agent freely mutate watched source files during active service runtime
- prefer config `hybrid` reload for config-only changes, explicit restart for code

**Short version:** `hybrid` is good for config, **staged restart** is better for code.

---

### 6) How should the agent receive issues?

**Best initial setup:** **Discord thread-bound persistent ACP sessions**, one thread per issue.

That matches the way ACP is meant to work well in chat ops.

Good patterns:
- `/acp spawn codex --mode persistent --thread auto`

- `/acp spawn codex --bind here`
- `sessions_spawn({ runtime: "acp", thread: true, mode: "session" })`

#### My recommendation
- **Primary intake:** Discord thread per issue
- **Trigger:** manual dispatch or controlled bot command
- **Persistence:** one ACP session stays attached to that issue thread

#### GitHub Issues webhook
Useful, but I would use it for:
- notification
- triage queue creation
- creating a thread/task

I would **not** wire GitHub Issues directly to a mutation-capable autonomous fixer on day one.


#### Manual dispatch
Still the safest default for early rollout:
- human reads issue
- human spawns ACP session
- agent investigates/fixes inside bounded workspace

---

### 7) Direct commits to running branch, or feature branches + PRs?

**Recommendation:** feature branch per issue, human-reviewed PR or merge.

- **Default**
  - branch per issue

  - commit there
  - review
  - merge/deploy
- **Direct commits**
  - acceptable only for emergency local hotfixes
  - tiny reversible diff
  - explicit rollback point
  - no schema/dependency/auth changes

If you skip GitHub PRs for internal ops, I would still keep:
- one branch per incident
- one rollback tag / known-good ref
- one human checkpoint before merge to the running branch

---


### 8) Scope boundary, and when to escalate

### Safe-ish default scope
- config changes
- targeted code patches
- small tests/docs updates
- logging/observability improvements
- localized bug fixes

### Escalate to a human for
- dependency upgrades
- lockfile churn
- migrations
- auth / OAuth / credentials

- security-sensitive changes
- data deletion / resets
- branch surgery / destructive git
- unclear root cause
- changes that touch multiple subsystems
- anything that needs judgment more than execution

A good rule is:

> If the fix changes trust boundaries, deployment shape, data shape, or dependency graph, escalate.

---

### 9) Should the agent have memory/history access?

**Yes, but curated memory, not unbounded memory.**

Best setup:
- give it a durable `MEMORY.md`
- keep dated ops notes in `memory/YYYY-MM-DD.md`
- maintain a short runbook of known failure patterns / fix recipes
- persist postmortems after successful fixes

Avoid:
- dumping every old transcript into context every session
- letting stale one-off incidents dominate future decisions

**Best balance:** searchable/history-backed memory, but curated and summarized.

---


### 10) Should it be changelog / release-note aware?

**Absolutely yes.**

It should know:
- deployed `openclaw --version`
- deployed repo commit
- nearby `CHANGELOG.md` entries

That matters a lot for distinguishing:
- intended behavior change
- newly fixed bug
- actual regression
- "this only happens on older builds"


For example, `2026.4.11` already includes ACP/agent-related fixes, including:
- ACP parent-stream leakage cleanup
- timeout behavior fixes

So yes, changelog awareness is operationally important, not optional.

---

### 11) Known SSH / remote execution caveats?

If by "over SSH" you mean the **SSH sandbox backend**, the biggest caveats are:

#### A) Non-interactive is real
ACP sessions have **no TTY**. So permission prompts do not work.

With the default ACP permission settings, writes/exec can fail with:

`AcpRuntimeError: Permission prompt unavailable in non-interactive mode`

#### B) Remote workspace state can drift
For the SSH sandbox backend, docs say the **remote workspace becomes canonical after the initial seed**.

That means:
- the first seed copies local workspace to remote
- after that, remote changes are the real state
- if SSH target/auth/workspace root changes, run:

```bash
openclaw sandbox recreate --all


Then the next run reseeds from local.

#### C) Latency is usually more of a problem than raw file I/O correctness
Expect:
- slower initial seed
- slower test/build loops
- more noticeable round-trip cost
- more pain if the agent does lots of small commands

#### D) Headless server quirks still matter
Recent releases improved headless SSH/server behavior, especially around systemd user-bus fallback, but I would still expect occasional operational weirdness on remote Linux boxes.

#### E) SSH hardening matters
Use:

- `strictHostKeyChecking: true`
- `updateHostKeys: true`
- narrow `workspaceRoot`
- dedicated SSH identity material

**Short version:** SSH is workable, but the main hazards are:
- non-interactive permission behavior
- remote workspace drift
- slower feedback loops

---

## My overall recommendation

If I were setting this up, I would do this:


1. **Dedicated ops ACP agent**
2. **Separate repo worktree**
3. **Branch-per-issue workflow**
4. **Discord thread-bound persistent sessions for intake**
5. **Curated memory + changelog awareness**
6. **`approve-all` only inside a fenced workspace/sandbox**
7. **Human review before merge/deploy**
8. **No destructive git / auth / dependency / migration autonomy**

That gives you real autonomy for routine issue resolution without giving the agent a huge blast radius.

## Useful refs

- ACP agents: <https://docs.openclaw.ai/tools/acp-agents>