openclaw/openclaw · error · CodexSupervisionPolicyError

Codex write controls are disabled for this codex plugin supe

Error message

Codex write controls are disabled for this codex plugin supervision config.

What it means

Thrown by requireWriteAccess() when the resolved Codex supervision tool policy denies write controls. resolveToolPolicy() grants write controls only when config.supervision.allowWriteControls === true OR the legacy env var is set to "1" while useLegacyMcpPolicyEnv is enabled. This guards mutation tools (steer, interrupt) so they cannot run against a thread unless the operator explicitly opted in.

Source

Thrown at extensions/codex/src/supervision-tools.ts:949

      (options.useLegacyMcpPolicyEnv === true &&
        env[LEGACY_CODEX_SUPERVISOR_WRITE_CONTROLS_ENV] === "1"),
  };
}

function requireRawTranscriptAccess(
  options: CodexSupervisionToolsOptions,
  pluginConfig: unknown,
): void {
  if (!resolveToolPolicy(options, pluginConfig).allowRawTranscripts) {
    throw new CodexSupervisionPolicyError(
      "Codex session reads are disabled for this codex plugin supervision config.",
    );
  }
}

function requireWriteAccess(options: CodexSupervisionToolsOptions, pluginConfig: unknown): void {
  if (!resolveToolPolicy(options, pluginConfig).allowWriteControls) {
    throw new CodexSupervisionPolicyError(
      "Codex write controls are disabled for this codex plugin supervision config.",
    );
  }
}

function requireLiveToolPolicy(
  options: CodexSupervisionToolsOptions,
  policy: CodexSupervisionRequestPolicy,
): { pluginConfig: unknown; endpoints: ResolvedSupervisionEndpoint[] } {
  requireOwnerAccess(options);
  const pluginConfig = options.getPluginConfig();
  requireSupervisionEnabled(pluginConfig);
  if (policy === "raw-transcripts") {
    requireRawTranscriptAccess(options, pluginConfig);
  } else if (policy === "write-controls") {
    requireWriteAccess(options, pluginConfig);
  }
  return {

View on GitHub (pinned to 01804a7531)

Solutions

Set plugins.entries.codex.config.supervision.allowWriteControls to true in openclaw.json if you intend to steer or interrupt codex turns.
Confirm plugins.entries.codex.config.supervision.enabled is also true; supervision must be on for any policy field to take effect.
If using the legacy env path, set the CODEX supervisor write-control env var to "1" and ensure useLegacyMcpPolicyEnv is enabled in the plugin options.
If write control is intentionally off, use read-only session tools instead of steer/interrupt.

Example fix

// before
"codex": { "supervision": { "enabled": true, "allowRawTranscripts": true } }
// after
"codex": { "supervision": { "enabled": true, "allowRawTranscripts": true, "allowWriteControls": true } }

Defensive patterns

Strategy: validation

Validate before calling

function canWriteControls(pluginConfig) {
  const supervision = pluginConfig?.codex?.supervision;
  return supervision?.enabled === true && supervision?.allowWriteControls === true;
}
// before calling steer/interrupt:
if (!canWriteControls(cfg.plugins.entries)) {
  throw new Error("Enable codex supervision allowWriteControls before using write tools.");
}

Try / catch

try {
  await codexSessionSteer(...);
} catch (err) {
  if (err instanceof CodexSupervisionPolicyError && /write controls are disabled/.test(err.message)) {
    // surface a config guidance message, do not retry until config is fixed
  } else throw err;
}

Prevention

Set allowWriteControls: true in supervision config at setup time if you plan to steer or interrupt.
Gate write-tool UI actions on a capability check that reads the resolved policy.
Document that read-only supervision does not include steer/interrupt.

When it happens

Trigger: Calling codex_session_steer or codex_session_interrupt while plugins.entries.codex.config.supervision is absent, set to { enabled: true } without allowWriteControls, or allowWriteControls: false. Also occurs when the legacy CODEX supervisor write-control env var is unset and useLegacyMcpPolicyEnv is not enabled.

Common situations: Operator enabled supervision for read-only session inspection (allowRawTranscripts: true) but forgot allowWriteControls: true. Config migrated by doctor without preserving the write-control flag. Legacy env-based setup dropped after upgrading to config-based policy.

Related errors

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