openclaw/openclaw · error · AgentHarnessPreflightError

Codex app-server local execution is unavailable because effe

Error message

Codex app-server local execution is unavailable because effective tools.exec.mode=${mode}. Execution-host approvals are authoritative. For gateway turns, inspect them with `openclaw approvals get --gateway` and update that same target with `openclaw approvals set --gateway --stdin`; for local `agent exec`, omit `--gateway`. Intentionally align that host policy before retrying.

What it means

An AgentHarnessPreflightError thrown during harness preflight when the effective tools.exec.mode is 'deny' or 'allowlist'. Under those modes the Codex app-server cannot perform local execution because execution-host approvals are authoritative. The message instructs the operator to inspect and align host approvals before retrying.

Source

Thrown at extensions/codex/src/app-server/config-exec-policy.ts:154

    return params.execPolicy.mode;
  }
  return params.execMode;
}

export function resolveCodexPolicyModeForOpenClawExecMode(
  mode: OpenClawExecMode | undefined,
): CodexAppServerPolicyMode | undefined {
  if (!mode || mode === "full") {
    return undefined;
  }
  return "guardian";
}

export function assertCodexAppServerAllowedForOpenClawExecMode(
  mode: OpenClawExecMode | undefined,
): void {
  if (mode === "deny" || mode === "allowlist") {
    throw new AgentHarnessPreflightError(
      `Codex app-server local execution is unavailable because effective tools.exec.mode=${mode}. ` +
        "Execution-host approvals are authoritative. For gateway turns, inspect them with `openclaw approvals get --gateway` and update that same target with `openclaw approvals set --gateway --stdin`; for local `agent exec`, omit `--gateway`. Intentionally align that host policy before retrying.",
      { scope: "harness" },
    );
  }
}

function createDefaultOpenClawExecPolicy(): OpenClawExecPolicy {
  return {
    security: "full",
    ask: "off",
    touched: false,
  };
}

function applyOpenClawExecPolicyLayer(
  base: OpenClawExecPolicy,
  exec?: { mode?: unknown; security?: unknown; ask?: unknown },

View on GitHub (pinned to 01804a7531)

Solutions

Inspect execution-host approvals for gateway turns: `openclaw approvals get --gateway`.
Align the host policy: `openclaw approvals set --gateway --stdin` with the corrected target.
For local `agent exec`, omit --gateway so the local approvals target is used.
Change tools.exec.mode to full, auto, or ask if local execution is intended.

Defensive patterns

Strategy: validation

Validate before calling

// Check exec mode before invoking the harness preflight
import { assertCodexAppServerAllowedForOpenClawExecMode } from './config-exec-policy.js';
function isAllowedForLocalExec(mode) { return mode !== 'deny' && mode !== 'allowlist'; }
if (!isAllowedForLocalExec(execMode)) {
  // align approvals via CLI before retrying instead of letting preflight throw
}

Try / catch

try {
  assertCodexAppServerAllowedForOpenClawExecMode(mode);
} catch (error) {
  if (error instanceof AgentHarnessPreflightError) {
    // surface operator-facing guidance; do not silently retry the same mode
  }
  throw error;
}

Prevention

Inspect execution-host approvals with `openclaw approvals get --gateway` before gateway turns.
Keep tools.exec.mode aligned with the host approvals target.
For local `agent exec`, omit --gateway so the correct local target is consulted.

When it happens

Trigger: assertCodexAppServerAllowedForOpenClawExecMode(mode) in config-exec-policy.ts called with mode === 'deny' or mode === 'allowlist'. Triggered during harness/preflight checks before local app-server execution.

Common situations: Operator or an approvals file set tools.exec.mode to deny or allowlist; attempting local `agent exec` or gateway turns under a restrictive host policy that blocks local execution; stale approvals targeting the wrong scope.

Related errors

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/cc7a94ea186553a2. Report an issue: GitHub.