npm package: @m64/nats-channel
Description: NATS messaging channel plugin for [OpenClaw](https://openclaw.ai). Registers your agent as a [NATS microservice](https://nats.io) — discoverable, addressable, and streaming responses over NATS infrastructure.
Latest version: 0.2.0

# @m64/nats-channel

NATS messaging channel plugin for [OpenClaw](https://openclaw.ai). Registers your agent as a [NATS microservice](https://nats.io) — discoverable, addressable, and streaming responses over NATS infrastructure.

### Subject convention

Your agent listens on a NATS subject based on its name and optional org namespace:

| Config | Subject |
|--------|---------|
| `agentName: "echo"` | `agents.oc.echo` |
| `agentName: "echo"`, `org: "acme"` | `agents.oc.acme.echo` |

Use `org` on shared servers (like `demo.nats.io`) to isolate your agents from others.

## Install

```bash
openclaw plugins install @m64/nats-channel
```

Or use the one-line installer with a guided config wizard:

```bash
curl -fsSL https://m64.io/nats-channels/openclaw.sh | bash
```

## Configure

Run the built-in setup wizard:

```bash
openclaw configure --section channels
```

Select **NATS Agent Network** and follow the prompts.

Or set individual fields via CLI:

```bash
openclaw config set channels.nats.accounts.default.agentName "my-agent"
openclaw config set channels.nats.accounts.default.url "nats://demo.nats.io"
openclaw config set channels.nats.accounts.default.description "My agent"
openclaw config set channels.nats.accounts.default.org "acme"
```

Or add the config manually to `~/.openclaw/openclaw.json`:

```json
{
  "channels": {
    "nats": {
      "accounts": {
        "default": {
          "url": "nats://demo.nats.io",
          "agentName": "my-agent",
          "description": "My OpenClaw agent"
        }
      }
    }
  }
}
```

Then restart the gateway:

```bash
openclaw gateway restart
```

### Config fields

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `url` | no | `nats://localhost:4222` | NATS server URL |
| `agentName` | yes | — | Agent name on the network (letters, numbers, dashes, underscores) |
| `description` | no | `"OpenClaw agent"` | Shown when other agents discover you |
| `credentials` | no | — | Path to `.creds` file for NATS authentication |
| `org` | no | — | Organization namespace for subject isolation on shared servers |

### Environment variables (Docker / containers)

All config fields can be overridden via environment variables, useful for Docker deployments where you don't want a config file. Each env var independently overrides its matching config field:

| Env Var | Overrides | Example |
|---------|-----------|---------|
| `NATS_URL` | `url` | `nats://prod.example.com:4222` |
| `NATS_AGENT_NAME` | `agentName` | `my-agent` |
| `NATS_DESCRIPTION` | `description` | `Production agent` |
| `NATS_ORG` | `org` | `acme` |
| `NATS_CREDENTIALS` | `credentials` | `/run/secrets/nats.creds` |

```yaml
# docker-compose.yml
environment:
  NATS_AGENT_NAME: my-agent
  NATS_URL: nats://nats:4222
  NATS_DESCRIPTION: Production agent
  NATS_ORG: acme
```

No `openclaw.json` config is needed when env vars are set. Env vars take precedence over any config file values.

## Verify

```bash
nats micro list                              # agent should appear
nats micro info my-agent                     # service details + endpoints
```

## Send a message

Responses stream as chunks, terminated by an empty payload. Plain text or JSON envelope:

```bash
# Plain text — sender defaults to "anonymous"
nats req agents.oc.my-agent 'Hello!' --wait-for-empty --timeout 60s

# JSON envelope — identify yourself
nats req agents.oc.my-agent '{"from":"cli","body":"Hello!"}' --wait-for-empty --timeout 60s
```

### Example with org namespace on demo.nats.io

Config:
```json
{
  "channels": {
    "nats": {
      "accounts": {
        "default": {
          "url": "nats://demo.nats.io",
          "agentName": "my-agent",
          "description": "My OpenClaw agent",
          "org": "acme"
        }
      }
    }
  }
}
```

```bash
nats req agents.oc.acme.my-agent '{"from":"cli","body":"Hello!"}' --server demo.nats.io --wait-for-empty --timeout 60s
```

## How it works

Your agent registers as a NATS microservice. Incoming messages are JSON envelopes (`{"from":"sender","body":"text"}`) dispatched through the OpenClaw pipeline. Responses stream back as chunks published to the caller's reply subject, with an empty payload signaling completion.

The agent is discoverable via standard NATS service introspection (`$SRV.PING`) and exposes an INSPECT endpoint at `agents.oc.{name}.inspect` (or `agents.oc.{org}.{name}.inspect` with org).

## License

MIT