Voice

Omx Discord Bridge

Name: Omx Discord Bridge
Rating: 3.5 (1 reviews)
Author: lex1ng

By lex1ng 👁 37 views ▲ 0 votes

OpenClaw plugin that turns a Discord thread into a local OMX/Codex tmux workspace, with session control, auto-answer routing, and reply callbacks.

GitHub

Install

npm install
npm

README

# OpenClaw OMX Discord Bridge

Turn a Discord thread into a local **OMX / Codex tmux workspace**.

This plugin lets you:

- start and bind local OMX sessions from Discord
- talk to a bound OMX session directly from a Discord thread
- route OMX replies back into the same thread
- use a **1 thread = 1 session** workflow that feels like a lightweight remote coding console

---

## Why this exists

If you already use:

- **OpenClaw** as your Discord / messaging entrypoint
- **OMX / Codex CLI** as your coding runtime
- **tmux** as your local session manager

then this bridge gives you a practical control plane:

```text
Discord thread
  ↕
OpenClaw plugin
  ↕
local tmux session
  ↕
OMX / Codex
```

You can create a session in Discord, keep working in that same thread, and receive OMX output back in-thread.

---

## Features

### Session control

- `/omx start`
- `/omx status`
- `/omx tail`
- `/omx stop`
- `/omx bind`
- `/omx unbind`
- `/omx doctor`

### Direct interaction with OMX

- `/omx answer <text>` sends text into the bound tmux session
- optional **auto-answer mode** sends ordinary thread messages directly into OMX

### Reply delivery

- OMX replies are routed back to the same Discord thread
- long replies are no longer limited to tiny previews
- idle callback delivery includes audit + dedupe protection

### Operational safety

- guild / channel / user allowlists
- repo allowlist enforcement
- safe tmux session-name normalization
- hook-token requirement for hooked sessions
- audit trail for control actions and callback delivery

---

## Workflow model

This plugin is intentionally opinionated:

> **One Discord thread = one OMX session**

That means:

- a thread can have at most one active binding
- ordinary messages in a bound thread can be treated as input to OMX
- the thread becomes a persistent work lane for that coding task

This is a better fit for long-running engineering work than stateless slash-command usage.

---

## Requirements

You should already have all of these on the same machine:

- OpenClaw
- Discord channel integration working in OpenClaw
- `omx` / oh-my-codex installed
- `tmux`
- access to:
  - `~/.openclaw/openclaw.json`
  - `~/.codex/.omx-config.json`

Recommended environment:

- a trusted single-user or tightly controlled workstation/server
- repo directories under an explicit allowlist such as:
  - `/home/<user>/github.com`
  - `/home/<user>/workspace`

---

## Quick start

### 1. Clone

```bash
git clone <YOUR_GITHUB_URL>/openclaw-omx-discord-bridge.git
cd openclaw-omx-discord-bridge
npm install
npm test
```

### 2. Set allowlists

```bash
export OMX_BRIDGE_ALLOWED_GUILDS="1485685652791230730"
export OMX_BRIDGE_ALLOWED_CHANNELS="1485685653898395650"
export OMX_BRIDGE_CONTROLLER_USERS="1458036641393541285"
export OMX_BRIDGE_ADMIN_USERS="1458036641393541285"
```

Optional defaults:

```bash
export OMX_BRIDGE_REPO_ALLOWLIST="/home/$USER/github.com,/home/$USER/workspace"
export OMX_BRIDGE_DEFAULT_MODEL="gpt-5.4"
export OMX_BRIDGE_DEFAULT_EFFORT="high"
export OMX_BRIDGE_TMUX_PREFIX="omx-"
```

### 3. Preview install changes

```bash
npm run bridge:enable:dry-run
```

### 4. Install config

```bash
npm run bridge:enable
systemctl --user restart openclaw-gateway.service
```

---

## Usage

In a Discord thread:

### Start a new OMX session

```text
/omx start repo=/home/xai/github.com/my-repo name=omx-my-repo-01
```

Default launch shape for new sessions:

```text
omx --model gpt-5.4 --madmax --high
```

### Inspect the binding

```text
/omx status
/omx mode
```

### Send explicit input

```text
/omx answer 继续修这个问题
```

### Use auto-answer mode

If `autoAnswer=on` (default), ordinary thread messages can go straight into OMX:

```text
继续修这个问题
```

Equivalent to:

```text
/omx answer 继续修这个问题
```

Control commands still work normally:

```text
/omx status
/omx mode off
/omx stop
```

### Disable direct chat temporarily

```text
/omx mode off
```

Re-enable it:

```text
/omx mode on
```

### Unbind the thread

```text
/omx unbind
```

---

## What gets installed

The config helper touches only local config/state files:

- `~/.openclaw/openclaw.json`
- `~/.codex/.omx-config.json`
- `~/.openclaw/state/omx-discord-bridge/`

It does **not** patch OpenClaw core source code.

Every config write creates timestamped backups first.

---

## State & audit files

By default:

```text
~/.openclaw/state/omx-discord-bridge/
```

Important files:

- `bindings.json`
- `leases.json`
- `audit.jsonl`
- `idle-latest-dispatch.jsonl`
- `idle-latest-delivery.json`
- `auto-answer-recent.json`
- `auto-answer-dedupe.json`

These files are your first stop when debugging behavior.

---

## Disable / uninstall

Disable but keep config:

```bash
npm run bridge:disable
systemctl --user restart openclaw-gateway.service
```

Remove config entries entirely:

```bash
npm run bridge:uninstall
systemctl --user restart openclaw-gateway.service
```

Also purge state:

```bash
node scripts/omx-bridge-config.mjs uninstall --purge-state
systemctl --user restart openclaw-gateway.service
```

---

## Reversibility

This integration is designed to be reversible.

The helper script creates backups like:

- `~/.openclaw/openclaw.json.omx-discord-bridge.<timestamp>.bak`
- `~/.codex/.omx-config.json.omx-discord-bridge.<timestamp>.bak`

So enable / disable / uninstall is reversible by restoring the backup files.

---

## Current maturity

This is a strong fit for:

- power users already running OpenClaw + Discord + OMX locally
- trusted machines and controlled workspaces
- long-running engineering threads where thread context matters

It is already usable for real workflows, but before broad public release you may still want:

- a final OSS/commercial license decision
- example configs with placeholders
- optional standalone Discord-bot adapter (non-OpenClaw path)
- more polished Discord long-output presentation

---

## Repository structure

```text
src/        core bridge logic
scripts/    install/config/runtime helper scripts
tests/      runtime/script tests
tests-ts/   TypeScript behavior tests
docs/       architecture and operations notes
```

---

## License

Currently marked as **UNLICENSED** until the owner chooses a public license.

If you plan to publish this repository broadly, choose a real license before announcing it.

voice