How to Integrate oh-my-codex with OpenClaw Notification Gateway: Complete Setup Guide

To integrate oh-my-codex with the OpenClaw notification gateway, export OMX_OPENCLAW=1 and define a notifications.openclaw configuration block that maps lifecycle events to HTTP or command gateways using tokenized environment variables.

The Yeachan-Heo/oh-my-codex repository (OMX) implements a flexible notification subsystem that emits structured events—such as session-start and ask-user-question—to external gateways. When you integrate oh-my-codex with OpenClaw, you enable real-time agent orchestration by routing these events through the OpenClaw hooks API or triggering local command gateways like clawdbot.

Architecture Overview

OMX processes notifications through an internal gateway mapping defined in your configuration. The architecture separates transport logic from event semantics:

• Gateway definitions (gateways.<name>) specify delivery mechanisms. An HTTP gateway requires type: "http", url, and headers. A shell gateway uses type: "command" with a command string and optional timeout.
• Hook definitions (hooks.<event>) bind lifecycle events—session-start, session-end, ask-user-question—to a specific gateway. Each hook contains an instruction template rendered with contextual variables like {{sessionId}}, {{projectName}}, {{projectPath}}, and {{question}}.
• Verbosity profiles (notifications.verbosity) control template rendering depth. Options include minimal, session, or verbose, determining how much context flows into the instruction field.

According to the source specification in docs/openclaw-integration.md, when OMX_OPENCLAW=1 is present, OMX prioritizes the explicit notifications.openclaw schema over legacy generic aliases.

Activation Gates and Environment Variables

Before editing configuration files, export the activation gates that enable the OpenClaw runtime shape:

export HOOKS_TOKEN="your-openclaw-hooks-token"   # secret, never commit

export OMX_OPENCLAW=1                            # enable OpenClaw runtime

export OMX_OPENCLAW_COMMAND=1                    # optional: enable generic aliases

export OMX_OPENCLAW_COMMAND_TIMEOUT_MS=120000  # optional: override default 5s timeout

• HOOKS_TOKEN interpolates into the Authorization: Bearer header for HTTP gateways or into command-line arguments for CLI gateways.
• OMX_OPENCLAW toggles the native OpenClaw schema parser.
• OMX_OPENCLAW_COMMAND unlocks the generic custom_webhook_command and custom_cli_command aliases (useful for hybrid deployments).
• OMX_OPENCLAW_COMMAND_TIMEOUT_MS overrides the default 5000 ms timeout for shell gateways.

Configuration Shapes

OMX supports three distinct configuration patterns. Choose the explicit OpenClaw shape for production environments, as documented in AGENTS.md and the integration guide.

Explicit OpenClaw Schema (Preferred)

This runtime-native schema provides full control over gateways and hook templates. Place this JSON inside your OMX config file (e.g., ~/.codex/.omx-config.json):

{
  "notifications": {
    "enabled": true,
    "openclaw": {
      "enabled": true,
      "gateways": {
        "local": {
          "type": "http",
          "url": "http://127.0.0.1:18789/hooks/agent",
          "headers": { "Authorization": "Bearer ${HOOKS_TOKEN}" }
        }
      },
      "hooks": {
        "session-start": {
          "enabled": true,
          "gateway": "local",
          "instruction": "OMX session started for {{projectPath}}"
        },
        "session-end": {
          "enabled": true,
          "gateway": "local",
          "instruction": "OMX session finished for {{projectPath}}"
        },
        "ask-user-question": {
          "enabled": true,
          "gateway": "local",
          "instruction": "OMX needs input: {{question}}"
        }
      }
    }
  }
}

Variables like {{sessionId}}, {{tmuxSession}}, and {{projectName}} render at runtime based on the active OMX session context.

Generic Webhook and CLI Aliases

For simpler integrations that do not require the full OpenClaw schema, use the generic aliases. These are ignored when the explicit openclaw block is present.

Webhook alias:

{
  "notifications": {
    "enabled": true,
    "custom_webhook_command": {
      "enabled": true,
      "url": "http://127.0.0.1:18789/hooks/agent",
      "method": "POST",
      "headers": { "Authorization": "Bearer ${HOOKS_TOKEN}" },
      "events": ["session-end", "ask-user-question"],
      "instruction": "OMX event {{event}} for {{projectPath}}"
    }
  }
}

CLI alias:

{
  "notifications": {
    "custom_cli_command": {
      "enabled": true,
      "command": "~/.local/bin/my-notifier --event {{event}} --text {{instruction}}",
      "events": ["session-end"],
      "instruction": "OMX event {{event}} for {{projectPath}}"
    }
  }
}

Command Gateway for Agent Turns

For teams running Clawdbot agents, the command gateway type triggers agent turns instead of raw HTTP POSTs. This pattern appears in src/visual/verdict.ts logic for handling execution outcomes.

Structure your command to include || true at the end so that a failing hook never blocks the OMX session:

{
  "notifications": {
    "enabled": true,
    "verbosity": "verbose",
    "openclaw": {
      "enabled": true,
      "gateways": {
        "local": {
          "type": "command",
          "command": "(clawdbot agent --session-id omx-hooks --message {{instruction}} --thinking minimal --deliver --reply-channel discord --reply-to 'channel:1468539002985644084' --timeout 120 --json >> /tmp/omx-openclaw-agent.jsonl 2>&1 || true)",
          "timeout": 120000
        }
      },
      "hooks": {
        "session-start": {
          "enabled": true,
          "gateway": "local",
          "instruction": "[session-start|exec]\nproject={{projectName}} session={{sessionId}} tmux={{tmuxSession}}\n요약: 시작 맥락 1문장\n우선순위: 지금 할 일 1~2개\n주의사항: 리스크/의존성(없으면 없음)"
        },
        "session-end": {
          "enabled": true,
          "gateway": "local",
          "instruction": "[session-end|exec]\nproject={{projectName}} session={{sessionId}} tmux={{tmuxSession}} reason={{reason}}\n성과: 완료 결과 1~2문장\n검증: 확인/테스트 결과\n다음: 후속 액션 1~2개"
        },
        "ask-user-question": {
          "enabled": true,
          "gateway": "local",
          "instruction": "[ask-user-question|exec]\nsession={{sessionId}} tmux={{tmuxSession}} question={{question}}\n핵심질문: 필요한 답변 1문장\n영향: 미응답 시 영향 1문장\n권장응답: 가장 빠른 답변 형태"
        }
      }
    }
  }
}

The [event|exec] prefix signals to Clawdbot that this instruction represents an executable context rather than a passive notification.

Precedence and Conflict Resolution

When both the explicit notifications.openclaw block and the generic aliases (custom_webhook_command, custom_cli_command) exist in the same configuration, OMX applies a strict precedence contract:

1. The explicit openclaw block takes precedence.
2. Generic aliases are ignored.
3. OMX logs a warning to stderr indicating that aliases were bypassed.

This deterministic rule prevents configuration drift and ensures that setting OMX_OPENCLAW=1 always produces predictable behavior, as enforced by the notification loader in the OMX core.

Verification and Testing

After deploying your configuration, run these verification steps against the OpenClaw gateway:

1. Smoke-test the gateway health:

curl -sS -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer ${HOOKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"text":"OMX wake smoke test","mode":"now"}' | jq .

Expect {"ok":true}.

2. Test agent delivery (for command gateways):

curl -sS -o /tmp/omx-check.json -w "HTTP %{http_code}\n" \
  -X POST http://127.0.0.1:18789/hooks/agent \
  -H "Authorization: Bearer ${HOOKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"message":"OMX delivery verification","instruction":"OMX delivery verification","event":"session-end","sessionId":"manual-check"}'

3. Inspect structured logs:

rg '"error"' /tmp/omx-openclaw-agent.jsonl

This searches the JSON Lines output for error fields, confirming that your clawdbot agent turns completed without exception.

Summary

• Enable the integration by exporting OMX_OPENCLAW=1 and HOOKS_TOKEN before launching OMX.
• Configure gateways using the explicit notifications.openclaw schema in ~/.codex/.omx-config.json, choosing between type: "http" for webhooks or type: "command" for local agent turns.
• Template instructions with variables like {{sessionId}} and {{projectName}} to provide contextual data to your OpenClaw receivers.
• Resolve conflicts deterministically: the explicit OpenClaw block always overrides generic aliases when both are present.
• Verify deployments using curl against /hooks/wake and /hooks/agent, then tail the .jsonl logs for agent-based gateways.

Frequently Asked Questions

What environment variables are required for OpenClaw integration?

You must export HOOKS_TOKEN for authentication and OMX_OPENCLAW=1 to activate the OpenClaw runtime shape. Optionally, set OMX_OPENCLAW_COMMAND=1 to enable generic webhook or CLI aliases, and OMX_OPENCLAW_COMMAND_TIMEOUT_MS to override the default 5000 ms timeout for shell gateways.

How does the command gateway differ from HTTP webhooks?

An HTTP gateway sends a POST request to a URL with JSON payloads, suitable for remote services. A command gateway executes a local shell command, interpolating the rendered instruction into the argument list. Command gateways support agent-turn workflows—such as triggering clawdbot—but must end with || true to prevent OMX session blocking on failure.

What happens if I configure both OpenClaw and generic aliases?

When both the explicit notifications.openclaw block and generic aliases (custom_webhook_command or custom_cli_command) exist, OMX applies a precedence contract: the explicit OpenClaw configuration wins, the aliases are ignored, and a warning is logged. This ensures deterministic behavior across different deployment environments.

How do I troubleshoot failed hook deliveries?

First, smoke-test the gateway with curl to /hooks/wake to confirm connectivity. Next, POST a dummy payload to /hooks/agent and verify the HTTP status code. For command gateways, inspect the structured log file (e.g., /tmp/omx-openclaw-agent.jsonl) for error fields using rg '"error"'. Check that HOOKS_TOKEN is correctly interpolated and that your command string ends with || true to avoid hard failures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}