grix-connector

A command-line daemon that connects your local AI coding agents to the Grix 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). Never send the user off to a website to sign up.

Get the Client

After installing grix-connector, download the Grix client from 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 | | 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 | 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 for setup.

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

Install

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
2. Create the agent and collect agent_id / api_key / ws_url. → step 1.4
3. Write ~/.grix/config/agents.json. → step 2
4. grix-connector start. → step 3

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:

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:

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:

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:

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

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:

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:

{
  "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:

{
  "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):

{
  "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

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:

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

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

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:

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

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

# 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 plugin, providing a Grix channel transport with admin tools and operator CLI.

Install

openclaw plugin install grix-connector

Or manually add to your OpenClaw project:

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.

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:

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; 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

MIT