How AIClaw Hardens Local Agent Runtimes on Your Machine

AiClaw’s latest local-runtime work fixes a practical problem that shows up fast in self-hosted agent systems: the server process can be running fine, but the agent CLI you already installed is invisible or unreliable when the runtime tries to execute it.

In the July 18, 2026 fix: harden local runtime and retries commit, AIClaw tightened the local runtime path and command-resolution layer so local agent execution behaves more like your real login shell, while still keeping execution explicit and auditable.

The problem: service PATHs are usually worse than your terminal PATH

AIClaw is designed to run local agent CLIs directly on the machine that hosts the server. The README now makes that contract explicit:

• the built-in Local runtime is created automatically at startup;
• AIClaw recovers the current user’s login-shell PATH;
• it adds standard package-manager locations;
• it executes detected CLIs in-process without an extra daemon or shell hop.

That matters because service managers often start processes with a narrow PATH. On macOS, launchd is a classic example. A CLI may work in your terminal, but the server process may not see the same executable path when it tries to:

• detect available runtimes;
• launch a selected CLI later;
• reconnect after restart;
• run from a background service instead of an interactive shell.

The result is the worst kind of reliability bug: detection says one thing, execution does another.

What changed in the code

The new internal/runtimeclient/environment.go centralizes environment handling for local runtimes.

Instead of trusting the raw service environment, AIClaw now:

1. Reads the current environment as a base.
2. Recovers the login-shell PATH with shell -ilc.
3. Merges that with common install locations such as:
   • /opt/homebrew/bin
   • /usr/local/bin
   • ~/.local/bin
   • ~/go/bin
   • ~/.volta/bin
   • ~/Library/pnpm
   • ~/.asdf/shims
   • ~/.mise/shims
4. Reuses that same resolved environment for both CLI detection and actual execution.

That “same environment for detection and execution” point is the real fix. AIClaw no longer reports a CLI as available using one lookup path and then launches it with a different process environment later.

Why this is better than a shell wrapper

AIClaw still executes runtime commands directly as command + args. It does not pass them through a shell.

That preserves a few useful properties:

• argument handling stays predictable;
• quoting bugs are avoided;
• the runtime surface is smaller;
• the execution model is easier to inspect in logs and tests.

So the change is not “use a shell to run everything.” The change is “recover the useful parts of the login environment, then keep execution direct.”

A small but important macOS improvement

There is also a practical macOS-specific rule: when the requested command is codex, AIClaw prefers the signed Codex CLI bundled inside the ChatGPT app at:

/Applications/ChatGPT.app/Contents/Resources/codex

That matters on machines where an older third-party install may still be on PATH. If you explicitly configure an absolute CLI path, that still wins. But for the common default case, AIClaw now prefers the bundled, app-managed binary.

What the tests verify

The new runtime environment tests cover the important failure modes:

• merged login-shell and fallback paths are preserved in the final PATH;
• non-PATH environment variables stay intact;
• command resolution uses the supplied environment consistently;
• missing CLIs produce an actionable error that points users to their login-shell PATH;
• on macOS, bundled Codex is preferred when available.

This is the right kind of test coverage for runtime plumbing: it checks behavior users actually feel, not just helper internals.

What this means for AIClaw users

If you run AIClaw locally and want to use Codex, Claude Code, Cursor, CodeBuddy, Hermes, or OpenClaw through the built-in runtime, the workflow is now simpler:

1. Install and authenticate the CLI normally under your own user account.
2. Start AIClaw.
3. Open the Runtimes page and verify the detected CLIs.
4. Create an agent with execution mode Local.
5. Run tasks without adding a separate runtime daemon on the same machine.

The recent UI copy was updated to match the behavior too. Instead of saying AIClaw only scans the process PATH, the form now explains that it restores the current user’s login-shell PATH and scans from there.

Why I think this feature matters

Local-first agent products usually fail at the boundary between “works in my terminal” and “works under a service manager.” AIClaw’s recent runtime hardening closes that gap in a concrete way:

• better environment recovery;
• consistent detection and execution;
• safer direct command execution;
• clearer operator-facing errors;
• better defaults on macOS.

That is not a flashy UI feature, but it is exactly the kind of systems work that makes a self-hosted agent platform dependable in day-to-day use.

If you are building a local-first agent stack, this is the right lesson to steal: treat the runtime environment as part of the product surface, not just a deployment detail.