grix-connector/README.md

Connect local AI coding agents (Claude, Codex, Gemini, Qwen, DeepSeek, Cursor, OpenCode, Pi, OpenHuman, Reasonix) to the Grix scheduling platform. Also serves as an OpenClaw plugin for Grix channel transport.

# grix-connector

A command-line daemon that connects your local AI coding agents to the [Grix](https://grix.im) platform.

## What is Grix?

Grix is an AI Agent scheduling platform. It lets you manage and interact with multiple AI coding agents through a unified chat interface. Register at [grix.im](https://grix.im) to get started.

## Supported Agents

Set `client_type` in your config to one of the values below. Each `client_type` maps to a built-in adapter and CLI command — you only need the corresponding CLI installed locally.

| `client_type` | Agent | Adapter | Required CLI |
|---|---|---|---|
| `claude` | Claude Code (Anthropic) | claude | `claude` |
| `codex` | Codex (OpenAI) | codex | `codex` |
| `gemini` | Gemini (Google) | acp | `gemini` |
| `qwen` | Qwen (Alibaba) | acp | `qwen` |
| `copilot` | GitHub Copilot | acp | `copilot` or `gh` |
| `kiro` | Kiro | acp | `kiro-cli` |
| `reasonix` | Reasonix | acp | `reasonix` |
| `cursor` | Cursor Agent | cursor | `agent` |
| `codewhale` | CodeWhale | codewhale | `codewhale` |
| `opencode` | OpenCode | opencode | `opencode` |
| `pi` | Pi | pi | `pi` |
| `openhuman` | OpenHuman | openhuman | `openhuman-core` |
| `agy` | Agy (Antigravity) | agy | `agy` |
| `hermes` | [Hermes](https://github.com/askie/grix-hermes-python) | external | `hermes` |

The ACP adapter (Agent Client Protocol over JSON-RPC) backs Gemini, Qwen, Copilot, Kiro and Reasonix. Hermes is an external agent maintained in a separate project — see [grix-hermes-python](https://github.com/askie/grix-hermes-python) for setup.

You need to have the corresponding CLI tool installed locally before connecting an agent.

## Install

```bash
npm install -g grix-connector
```

Requires Node.js >= 18.

On Windows, `grix-connector` uses the built-in Task Scheduler with a hidden WScript launcher (no extra dependency required).

## Quick Start

### 1. Register a Grix account

Go to [grix.im](https://grix.im), sign up and get your API key.

### 2. Create agent config

Create `~/.grix/config/agents.json`. Choose the `ws_url` for your region — the two regions use different WebSocket domains:

- China mainland: `wss://grix.dhf.pub/v1/agent-api/ws`
- Global: `wss://ws.grix.im/v1/agent-api/ws`

China mainland example:

```json
{
  "agents": [
    {
      "name": "my-agent",
      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
      "agent_id": "your-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "claude"
    }
  ]
}
```

Global example:

```json
{
  "agents": [
    {
      "name": "my-agent",
      "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
      "agent_id": "your-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "claude"
    }
  ]
}
```

Change `client_type` to match the agent you want to connect (see table above). You can define multiple agents in one file, or use separate files under `~/.grix/config/`.

### Config Reference

Each agent entry uses one flat structure:

| Field | Required | Description |
|---|---|---|
| `name` | yes | Display name for this agent |
| `ws_url` | yes | WebSocket endpoint URL (region-specific). China mainland: `wss://grix.dhf.pub/v1/agent-api/ws`; Global: `wss://ws.grix.im/v1/agent-api/ws` |
| `agent_id` | yes | Agent ID from Grix platform |
| `api_key` | yes | API key for authentication |
| `client_type` | yes | See Supported Agents table above |
| `prompt_timeout_ms` | no | Prompt execution timeout (ms) |
| `pool.maxSize` | no | Max adapter pool size (default 20) |
| `pool.idleTimeoutMs` | no | Idle adapter eviction timeout (default 300000 = 5 min) |

Adapter command/args/options are built in and resolved from `client_type`. To connect a different agent, simply change `client_type` — no other config changes needed.

### Multi-agent Example

China mainland region (swap the `ws_url` domain to `ws.grix.im` for the global region):

```json
{
  "agents": [
    {
      "name": "my-claude",
      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
      "agent_id": "your-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "claude"
    },
    {
      "name": "my-gemini",
      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
      "agent_id": "another-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "gemini"
    }
  ]
}
```

### 3. Start the daemon

```bash
grix-connector start
```

The daemon connects to Grix via WebSocket and starts routing chat messages to your agents.

### Commands

```bash
grix-connector start     # Start as system service (auto-installs on first run)
grix-connector stop      # Stop the service
grix-connector restart   # Restart the service
grix-connector status    # Check service status
```

### Ports

The daemon binds two local loopback ports (127.0.0.1 only):

| Purpose | Default | Override (env) | Override (CLI) |
|---|---|---|---|
| Health check (`/healthz`) | `19579` | `GRIX_HEALTH_PORT` | `--health-port <port>` |
| Admin API (used by the local CLI) | `19580` | `GRIX_ADMIN_PORT` | `--admin-port <port>` |

If a port is already in use, the daemon refuses to start and writes a clear message to `~/.grix/service/daemon.err.log` and the main log, and marks `~/.grix/daemon-status.json` as `state: "failed"` with a `reason` like `port_bind_in_use:health:19579`.

To pick different ports:

```bash
# via environment
GRIX_HEALTH_PORT=29579 GRIX_ADMIN_PORT=29580 grix-connector restart

# or via CLI flags (when running the daemon directly)
grix-connector --health-port 29579 --admin-port 29580
```

To find what is occupying a port:

```bash
# macOS / Linux
lsof -nP -iTCP:19579 -sTCP:LISTEN

# Windows (PowerShell or cmd)
netstat -ano | findstr :19579
```

## OpenClaw Plugin

grix-connector can also be installed as an [OpenClaw](https://openclaw.io) plugin, providing a Grix channel transport with admin tools and operator CLI.

### Install

```bash
openclaw plugin install grix-connector
```

Or manually add to your OpenClaw project:

```bash
npm install grix-connector
```

### Plugin Features

- **Channel**: Grix chat transport — routes messages between OpenClaw and your Grix deployment
- **Tools**: `grix_query`, `grix_group`, `grix_admin`, `grix_egg`, `grix_register`, `grix_update`, `grix_message_send`, `grix_message_unsend`, `openclaw_memory_setup`
- **CLI**: `openclaw grix` — agent management and admin commands
- **Skills**: 9 bundled skills for admin, group, query, registration, update, messaging, memory setup, and egg orchestration

### Requirements

- OpenClaw >= 2026.4.8
- A Grix account with agent ID and API key

## License

MIT