# 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.

> **Reading this as an AI agent doing the install?** Everything here is terminal-only. Account registration included — you collect the user's email and the emailed verification code in chat and call the API yourself ([step 1](#1-register-a-grix-account-and-create-an-agent)). Never send the user off to a website to sign up.

> **Bringing your own agent?** If it speaks the [Agent Client Protocol](https://agentclientprotocol.com), it connects with configuration only — no code change on either side. Read **[Connecting your own agent to Grix over ACP](docs/guide-acp-agent-integration.md)**, which ships inside this npm package.

## Get the Client

After installing grix-connector, download the Grix client from [grix.im](https://grix.im) to chat with your agents. Clients are available for iOS, Android, macOS, Windows, and Linux.

## 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` |
| `deepseek` | DeepSeek Harness | deepseek-harness | `dsh` |
| `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` |
| `acp` | Any Agent Client Protocol CLI | acp | your own (`command`) |

The ACP adapter (Agent Client Protocol over JSON-RPC) backs Gemini, Qwen, Copilot, Kiro, Kimi 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.

`client_type: "acp"` is the generic entry: if your CLI speaks the Agent Client Protocol over stdio JSON-RPC, connect it with configuration only — no code change, no new release. Give it the executable in `command`, and put the CLI's own ACP subcommand or flag in `args` (nothing is injected for you):

```json
{
  "name": "my-acp-agent",
  "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
  "agent_id": "your-agent-id",
  "api_key": "your-grix-api-key",
  "client_type": "acp",
  "command": "my-cli",
  "args": ["acp"],
  "cwd": "/srv/my-agent"
}
```

The generic entry never asks the owner to pick a working directory. ACP's `session/new` requires a `cwd`, so the connector supplies one from the config: `cwd` if you set it, the home directory otherwise. It is fixed for the agent — `/grix open` and `/grix unbind` are rejected for `client_type: "acp"`, and the toolbar offers no binding entry. To move the agent, edit `cwd` and restart the connector. A `cwd` that does not exist is logged as an error and falls back to the home directory, so a typo cannot strand the agent. Every other `client_type` keeps the existing flow where the owner binds a directory per session.

The generic entry ships the shared ACP surface (permission prompts, model/mode switching, file browsing). Per-agent extras — an installation guide, a dedicated toolbar, session usage parsing — still require a registered `client_type`.

**[Connecting your own agent to Grix over ACP](docs/guide-acp-agent-integration.md)** is the full developer guide: asking the user a question and receiving the answer, what the toolbar can show and how the user's choice reaches you, the Grix MCP tools your agent gets for free, the card format, and the limits of the generic entry.

Two limits of the generic entry are deliberate and will not be changed. Skill discovery for `client_type: "acp"` falls back to the Gemini layout, so it reads `~/.gemini/skills` and shares that directory with a real Gemini agent on the same machine. `get_session_usage` is not declared for it, because there is no parser for an unknown CLI's usage output. A CLI that needs its own skill directory or usage parsing must be registered as its own `client_type`.

For DeepSeek Harness, install the official CLI and complete its login/profile setup before starting the connector:

```bash
npm install -g @deepseek-ai/dsh@latest
dsh web
```

Then set `client_type` to `deepseek`; the connector uses the configured default DeepSeek Harness profile.

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).

### After the install: you still need a Grix account

Installing the CLI is not enough — the daemon refuses to start without a Grix account and an agent credential. The install is step 0 of four:

1. **Register a Grix account.** This is where you need the user: **ask them for an email address**, because a verification code is mailed to it and they have to read it back to you. → [step 1](#1-register-a-grix-account-and-create-an-agent)
2. Create the agent and collect `agent_id` / `api_key` / `ws_url`. → [step 1.4](#14-create-the-api-agent)
3. Write `~/.grix/config/agents.json`. → [step 2](#2-create-agent-config)
4. `grix-connector start`. → [step 3](#3-start-the-daemon)

So the very first thing to ask the user for, right after the install, is **an email address**.

The registration flow is also packaged as a skill, `grix-register`. In OpenClaw plugin mode it is loaded automatically; after a global npm install any agent can read it directly:

```bash
cat "$(npm root -g)/grix-connector/openclaw-plugin/skills/grix-register/SKILL.md"
```

Running that skill and following step 1 below are the same thing — the same API calls, described once as a skill and once as plain curl. Use whichever your runtime supports.

## Quick Start

### 1. Register a Grix account and create an agent

This whole step is HTTP API calls — no browser, no dashboard. The user only has to give you two things in chat: **their email address**, and **the 6-digit verification code** that lands in their inbox. You do the rest.

**API base:** `https://grix.dhf.pub/v1` — this is the auth/agent API for both regions (`ws.grix.im` serves the WebSocket only, it has no auth routes). A private deployment replaces the host.

**Response envelope:** every endpoint returns `{"code": 0, "msg": "success", "data": {...}}`. A HTTP 200 with a non-zero `code` is still a failure — always branch on `code`, not on the HTTP status.

#### 1.1 Ask for the email, send the verification code

Ask the user for the email address they want the account under, then:

```bash
curl -s -X POST https://grix.dhf.pub/v1/auth/send-code \
  -H 'Content-Type: application/json' \
  -d '{"email":"<user-email>","scene":"register"}'
```

On `code: 0`, tell the user to check their inbox (and the spam folder) and ask them to paste the 6-digit code back to you.

| `code` | Meaning | What to do |
|---|---|---|
| `10003` | Invalid parameter — the email failed validation | Re-check the address with the user |
| `10005` | Rate limited: a code was already sent | Do **not** retry in a loop. Tell the user to wait ~5 minutes, or ask them for the code that was already sent |

#### 1.2 Register

**Generate the password yourself** — do not make the user invent one. Use a random 12+ character password mixing upper case, lower case, digits and symbols. Then:

```bash
curl -s -X POST https://grix.dhf.pub/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "<user-email>",
    "password": "<generated-password>",
    "email_code": "<code the user gave you>",
    "device_id": "cli_<random-uuid>",
    "platform": "cli"
  }'
```

Returns `data.access_token` (plus `refresh_token`, `expires_in`, `user.id`). Keep the token in memory for the next call.

**After a successful registration, show the user the generated password and tell them to save it** — it is their account password and it is not recoverable from anywhere else.

Failures you will actually hit — note that both of them come back as `code: 10001`, so **read the `msg`, not just the code**:

| `msg` | Meaning | What to do |
|---|---|---|
| `邮箱验证码错误或已过期` (code wrong or expired) | The code really is wrong | Ask the user to re-read it, or re-send it (1.1) |
| `注册失败，请检查邮箱验证码后重试` (registration failed, check the code) | **Almost always: the email is already registered.** The message blames the code, but the code already passed validation | Do **not** re-send the code in a loop — go to 1.3 and log in |

#### 1.3 Existing account — log in instead

Only when the user **gives you their existing password**:

```bash
curl -s -X POST https://grix.dhf.pub/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"account":"<user-email>","password":"<password>","device_id":"cli_<random-uuid>","platform":"cli"}'
```

Same `data.access_token` as register. If the user does not remember their password, do not guess and do not pretend to recover it — ask them to reset it in the Grix client, then come back with the password.

#### 1.4 Create the API agent

This is where `agent_id` and `api_key` come from. Ask the user what to name the agent (or reuse a name already agreed in the conversation):

```bash
curl -s -X POST https://grix.dhf.pub/v1/agents/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{"agent_name":"<agent-name>","provider_type":3,"is_main":true}'
```

`provider_type: 3` is the Agent API type — the only type this connector can drive. `is_main: true` gives the first agent the full initial permission scope.

Returns in `data`:

| Field | Use |
|---|---|
| `id` | the `agent_id` for your config |
| `api_key` | the `api_key` for your config — **shown exactly once, it is never retrievable again** |
| `api_endpoint` | the `ws_url` for your config |
| `api_key_hint` | last few characters, for later identification |

**If the name is already taken** by a `provider_type: 3` agent, reuse it instead of inventing a new name — list the agents, find the exact-name entry with `provider_type == 3` and `status != 3`, and rotate its key:

```bash
curl -s -H 'Authorization: Bearer <access_token>' https://grix.dhf.pub/v1/agents/list

curl -s -X POST -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  https://grix.dhf.pub/v1/agents/<agent-id>/api/key/rotate -d '{}'
```

Rotation returns a fresh `api_key` and the same `api_endpoint`. The old key stops working immediately, so only rotate an agent the user actually wants to re-point at this machine.

#### 1.5 Map the fields into the config

| From the API | Into `agents.json` |
|---|---|
| `data.id` | `agent_id` |
| `data.api_key` | `api_key` |
| `data.api_endpoint` | `ws_url` — drop any `?agent_id=…` query string, keep only the part before `?` |

If `api_endpoint` comes back empty, fall back to the regional URL in step 2. Write the `api_key` into `~/.grix/config/agents.json` and nowhere else — never into a log, a shell history file, or a repository.

### 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) |
| `codex_config_overrides` | no | Codex-only app-server config overrides. The connector serializes this JSON object into validated `-c` flags. |
| `provider.quota_api_key` | no | OpenCode only. Console service key (`oc_sk_…`) used to read the Go plan's 5-hour, weekly, and monthly usage plus the credits balance, and show them on the toolbar. This is not the inference key. |
| `command` | `acp` only | Executable to spawn for `client_type: "acp"`. Required for that type, ignored by every other type (their command is built in). |
| `cwd` | no | `acp` only: the fixed working directory passed to ACP `session/new`. Defaults to the home directory. The owner cannot change it from chat. |
| `args` | no | Extra CLI arguments appended to the adapter's built-in ones. For `client_type: "acp"` these are the only arguments passed. |

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. The one exception is `client_type: "acp"`, where the command comes from your config.

For an OpenCode agent, `provider.quota_api_key` is optional. Set it to an [OpenCode Console](https://opencode.ai/console) service key that starts with `oc_sk_`. The connector calls the console usage APIs with that key and puts the Go windows and credits balance on the toolbar. The key that actually runs the model stays wherever OpenCode already stores it; do not put the inference key in `quota_api_key`. Restart the connector after changing it. If this field is omitted, the connector also accepts `OPENCODE_CONSOLE_TOKEN`, or an `oc_sk_` key already present in OpenCode's `auth.json` / `opencode.json`. A session pointed at another recognized provider keeps that provider's quota.

```json
{
  "name": "OpenCode",
  "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
  "agent_id": "your-agent-id",
  "api_key": "your-grix-api-key",
  "client_type": "opencode",
  "provider": {
    "quota_api_key": "oc_sk_..."
  }
}
```

For Codex context trimming, disable plugin suggestions without changing the user's own Codex CLI profile:

```json
{
  "name": "my-codex",
  "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
  "agent_id": "your-agent-id",
  "api_key": "your-grix-api-key",
  "client_type": "codex",
  "codex_config_overrides": {
    "features.tool_suggest": false
  }
}
```

Use JSON object nesting for plugin IDs instead of quoted dotted TOML keys:

```json
{
  "codex_config_overrides": {
    "plugins": {
      "browser@openai-bundled": { "enabled": false }
    }
  }
}
```

### 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.

> The daemon refuses to start when the config directory holds no valid agent config, so on a first-time setup the config file must be written **before** `start`.

### Adding an agent to an existing setup

If `~/.grix/config/agents.json` already exists and other agents are running, **do not overwrite the file** — merge the new entry into it.

**1. Merge the entry.** Read the file as JSON and look through the `agents` array for an entry whose `agent_id` matches the one you are adding:

- found → replace that entry
- not found → append the new entry
- every other entry must be left exactly as it was

Edit it with a script (`node`, `python3`), not by hand — a truncated or re-indented file silently drops the agents you did not intend to touch. If the file does not exist yet, create it with a single-element `agents` array.

**2. Apply the change.** Check whether the daemon is already running:

```bash
grix-connector status
```

- not running (or it reports `daemon is not running`) → `grix-connector start`
- already running → `grix-connector reload`

`reload` hot-loads the new agent and leaves every already-running agent untouched — their live sessions are not interrupted. Do not use `restart` to add an agent: it reconnects everything and drops all in-flight conversations.

**3. Verify.** `grix-connector status` reports the daemon only — it does not list agents. To confirm the new agent is connected, query the local admin API (give it a few seconds after `start`/`reload`):

```bash
curl -s http://127.0.0.1:19580/api/agents
```

The entry for your agent should report `"alive": true`. `19580` is the default admin port; if it was overridden (`--admin-port` or `GRIX_ADMIN_PORT`), the port actually in use is written to `~/.grix/data/admin-port`.

If it never connects, read the newest log under `~/.grix/log/`. In practice it is almost always one of three things:

- the CLI for that `client_type` is not on `PATH`
- the CLI is installed but not logged in
- the `api_key` was truncated when it was copied

**Credentials.** `api_key` is a one-time secret: write it into `~/.grix/config/agents.json` and nowhere else. Do not echo it into logs or commit it to a repository.

### 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 reload    # Hot-reload agent configs without restarting the daemon
grix-connector status    # Check service status
```

### Reloading config (`reload`)

`reload` applies changes to your config files **without restarting the daemon**. It re-reads `~/.grix/config/*.json`, diffs against what's currently running, and acts per agent:

| Change in config | What happens |
|---|---|
| Agent added | Started and connected |
| Agent removed | Stopped and disconnected |
| Agent config changed | That agent restarts (stop old, start new) |
| Agent unchanged | **Left running untouched** — its sessions are not interrupted |

**When to use it.** You run a multi-agent setup and want to add, remove, or re-key one agent — or tweak one agent's settings — without dropping the live sessions of the *other* agents. A full `restart` would reconnect every agent and interrupt all in-flight conversations; `reload` only touches the agents whose config actually changed.

**Safety.** If any config file fails to parse (e.g. you're mid-edit and the JSON is broken), or no valid agent config is found, the reload aborts and the running agents are left exactly as they are — nothing is torn down on a bad config.

Three equivalent ways to trigger it:

```bash
grix-connector reload                          # CLI (sends SIGHUP to the daemon)
kill -HUP "$(cat ~/.grix/grix-acp.pid)"        # raw signal (Unix)
curl -XPOST http://127.0.0.1:19580/api/reload  # Admin API — returns the per-agent result as JSON
```

The CLI/signal form is fire-and-forget; the per-agent result is written to the daemon log. The Admin API form returns the result (added/removed/restarted/unchanged/failed) synchronously.

### Ports

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

| Purpose | Default | Override (env) | Override (CLI) |
|---|---|---|---|
| Health check (`/healthz`, alias `/health`) | `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 plugins install grix-connector
```

Or manually add to your OpenClaw project:

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

### Connecting an agent (plugin mode)

Plugin mode does **not** use `~/.grix/config/agents.json`. The credentials live in OpenClaw's own config (`openclaw.json`) under `channels.grix`, and the field names are camelCase — `wsUrl` / `agentId` / `apiKey` — not the snake_case names used by the daemon.

Write them with `openclaw config set`. **Do not hand-edit `openclaw.json`.**

```bash
openclaw config set channels.grix.accounts.<account-id> \
  '{"name":"my-agent","enabled":true,"wsUrl":"wss://grix.dhf.pub/v1/agent-api/ws","agentId":"your-agent-id","apiKey":"your-grix-api-key"}' \
  --strict-json
```

`<account-id>` is a name you choose (lowercase letters, digits, hyphens). Use the `ws.grix.im` domain instead for the global region. If `channels.grix.enabled` was explicitly turned off before, also run `openclaw config set channels.grix.enabled true --strict-json`.

Then check it:

```bash
openclaw config validate
openclaw grix doctor      # the account should report configured: true, enabled: true
```

Finally send a message to the agent from Grix and confirm the reply really comes from it. Only if the config validates but messages do not route should you run `openclaw gateway restart` — once — and then re-send the message.

### 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 doctor` — local diagnostics (the only subcommand; configuration goes through `openclaw config set`)
- **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 — get them with the API flow in [step 1](#1-register-a-grix-account-and-create-an-agent); it works the same in plugin mode

Plugin mode and the standalone daemon can coexist on one machine — they use separate configs and separate processes. Do not, however, bring the **same** `agent_id` online in both at once; give each mode its own agent.

## License

[Apache License 2.0](LICENSE)
