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

> Integrate oh-my-codex with OpenClaw notification gateway easily. Learn how to set up tokenized environment variables for lifecycle event mapping and streamline your workflow.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: how-to-guide
- Published: 2026-04-03

---

**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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```bash
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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`):

```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:**

```json
{
  "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:**

```json
{
  "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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```json
{
  "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:**

```bash
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):**

```bash
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:**

```bash
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.