OpenClaw Grix Plugin

This plugin connects OpenClaw to Grix. It lets OpenClaw agents talk in Grix private chats and group chats, and gives you a clean way to run a main agent plus other worker agents from mobile or desktop.

• Connect OpenClaw agents to Grix
• Support private chat, group chat, and multi-agent collaboration
• Support send/receive, streaming replies, react, unsend, and delete
• Support raw session lookup through grix_query.message_history and grix_query.message_search
• Recommended global tools: message, grix_query, grix_group, grix_register, grix_message_send, grix_message_unsend
• Recommended main-agent-only tools: grix_admin, grix_egg, grix_update, openclaw_memory_setup
• Built-in skills live in skills/

Compatibility

• OpenClaw >= 2026.4.8

Choose A Setup Path

Use one path only:

• Recommended: in-chat installation
• Fallback: manual installation

If your current OpenClaw / Claude / Codex environment can follow install instructions in chat, use the in-chat path first. Only use the manual path when you need to prepare the config yourself.

Recommended Installation

Send this sentence directly to OpenClaw, Claude, or Codex:

Install the @dhf-openclaw/grix plugin for OpenClaw and configure the Grix channel.

In the normal flow, the agent can install the plugin, prepare the Grix channel, and create or update the grix auto update cron job for you.

If that path is not available in your current environment, continue with the manual steps below.

Manual Installation

Before You Start

For a first setup, keep these 3 names the same:

• the local OpenClaw agent name
• the local config key under channels.grix.accounts.<name>
• the remote Grix API agent name

Recommended first-time name:

• grix-main

Manual setup also assumes you already have, or can separately create, a matching remote Grix API agent. Before you begin the config steps, prepare these 4 values from Grix:

• agent_name
• agent_id
• api_key
• api_endpoint

If you do not already have those values, go back to the in-chat install flow instead of continuing with the README manual path.

1) Install and enable the plugin

openclaw plugins install @dhf-openclaw/grix
openclaw plugins enable grix

2) Create the local OpenClaw main agent

For a first setup, use grix-main unless you already have a different planned name:

openclaw agents add grix-main --workspace ~/.openclaw/workspace-grix-main

If you use a different name here, replace every later grix-main with your own name everywhere in this README.

3) Prepare the matching remote Grix API agent

Before you continue, make sure you already have a Grix API agent with the same name as the local OpenClaw agent from step 2.

For the first setup example in this README, that means:

• local OpenClaw agent: grix-main
• remote Grix API agent: grix-main

Keep these values ready:

• agent_name
• agent_id
• api_key
• api_endpoint

The remaining manual steps should keep using that same name.

4) Write the Grix account config into OpenClaw

Write the remote Grix values into OpenClaw:

openclaw config set channels.grix.accounts.grix-main '{"name":"grix-main","enabled":true,"wsUrl":"<api_endpoint>","agentId":"<agent_id>","apiKey":"<api_key>"}' --strict-json

Notes:

• use the api_endpoint from step 3 as wsUrl
• the account key channels.grix.accounts.grix-main should match the same name you used in step 2 and step 3

5) Bind that Grix account to the local OpenClaw agent

openclaw agents bind --agent grix-main --bind grix:grix-main

This binding should use the same name on both sides for a first setup.

6) Set the global tool defaults

Run these in your OpenClaw config:

openclaw config set tools.profile '"coding"' --strict-json
openclaw config set tools.alsoAllow '["message","grix_query","grix_group","grix_register","grix_message_send","grix_message_unsend"]' --strict-json
openclaw config set tools.sessions.visibility '"agent"' --strict-json

Recommended split:

• Give every agent: grix_query, grix_group, grix_register, grix_message_send, grix_message_unsend
• Keep only on the main agent: grix_admin, grix_egg, grix_update, openclaw_memory_setup

Why this split is easier to manage:

• grix_query, grix_group, grix_register, grix_message_send, and grix_message_unsend are the normal day-to-day Grix tools.
• grix_admin, grix_egg, grix_update, and openclaw_memory_setup can change local config, remote agent state, install state, update state, or memory state, so they are safer on the main agent only.

7) Add the workflow tools to the main agent only

First check which entry in agents.list is your main agent:

openclaw config get --json agents.list

Then add the extra workflow tools only to that main-agent entry. Example below uses agents.list[0]; replace 0 with the actual index of your main agent:

openclaw config set agents.list[0].tools.alsoAllow '["grix_admin","grix_egg","grix_update","openclaw_memory_setup"]' --strict-json

Important:

• do not put these 4 tools into the global tools.alsoAllow
• if that agent already has a tools.alsoAllow list, merge these names into the existing array instead of replacing it

8) Validate the config

openclaw config validate
openclaw config get --json channels.grix.accounts.grix-main
openclaw config get --json tools.alsoAllow
openclaw config get --json agents.list[0].tools.alsoAllow
openclaw agents bindings --agent grix-main --json

You should now be able to confirm all of these:

• the grix-main account exists under channels.grix.accounts
• the global tools.alsoAllow contains the normal Grix tools
• the main agent entry contains the workflow tools
• openclaw agents bindings shows grix:grix-main

9) Restart only if the running state is still stale

按 OpenClaw 官方流程，先完成上面的 config set / agents bind / config validate。如果实际运行结果仍然没刷新，再执行：

openclaw gateway restart

统一出站端到端测试

统一出站 E2E 测试代码在 AIBot 后端仓库中。由于 OpenClaw 是宿主运行时，grix-openclaw 是插件而非独立进程，测试假设 OpenClaw 进程已启动且 grix 插件已加载并连接到后端。

前置条件：

• AIBot 后端已启动（在后端仓库执行 make dev-up）
• OpenClaw 已安装、grix 插件已启用、并已连接到后端

运行：

cd <aibot-backend-repo>

GRIX_ADAPTER_E2E=1 \
GRIX_ADAPTER_OPENCLAW_AGENT_ID=<agent-id> \
GRIX_ADAPTER_E2E_USER_ACCOUNT=<account> \
GRIX_ADAPTER_E2E_USER_PASSWORD=<password> \
go test ./e2e/ -run TestLiveAdapterOpenClawRoundtrip -v -timeout 10m

测试流程：查找在线的 OpenClaw agent（client_type=openclaw），打开会话，发送带 marker 的消息，验证 OpenClaw 的回复包含 marker。不会启动或停止 OpenClaw 进程。

10) Verify the result

openclaw plugins info grix --json
openclaw grix doctor
openclaw skills list

Expected result:

• The grix plugin is enabled
• doctor shows the configured account
• skills list shows the built-in skills from this plugin

After that, do one real message test in Grix and confirm the bound agent can receive and reply normally.

11) Add the auto-update cron job

Add this after the plugin is working. This keeps future grix updates automatic:

openclaw cron add \
  --name "grix auto update" \
  --every "6h" \
  --agent grix-main \
  --session isolated \
  --light-context \
  --no-deliver \
  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'

Then check the scheduler:

openclaw cron list
openclaw cron status

If you used the in-chat grix-egg install flow, this cron job should usually be created or updated for you. If you used the README manual path, add it yourself.

Done Checklist

Your setup is in a good state when all of these are true:

• the plugin is installed and enabled
• openclaw grix doctor shows the configured account
• the Grix account is bound to the intended OpenClaw agent
• the agent can actually receive and reply to a real Grix message
• the grix auto update cron job exists

Common Notes

The easiest first setup is:

• use one name everywhere, preferably grix-main
• finish the single-agent path first
• confirm real message flow works
• only then move on to multi-agent or other advanced setup

Most manual-install confusion comes from mixing up these 4 values:

• agent_name
• agent_id
• api_key
• api_endpoint

And these 3 local places:

• the OpenClaw agent name
• the channels.grix.accounts.<name> key
• the openclaw agents bind --bind grix:<name> target

For a first setup, keep all of them aligned to the same name.

Optional Feature

Streaming Reply Tuning

The plugin streams replies chunk-by-chunk into the chat. The following account-level parameters control streaming behavior:

openclaw config set channels.grix.accounts.grix-main.streaming true
openclaw config set channels.grix.accounts.grix-main.streamChunkChars 48
openclaw config set channels.grix.accounts.grix-main.streamChunkDelayMs 0
openclaw config set channels.grix.accounts.grix-main.maxChunkChars 1200

| Parameter | Type | Default | Description | |---|---|---|---| | streaming | boolean | true | Whether to stream replies chunk-by-chunk. Set to false to send the entire reply at once after generation completes. | | streamChunkChars | number | 48 | Max characters per streaming delta chunk. Larger values send fewer, bigger chunks. Only effective when streaming is true. | | streamChunkDelayMs | number | 0 | Delay in milliseconds between consecutive stream chunks. Increase to slow down the visual streaming speed. Only effective when streaming is true. | | maxChunkChars | number | 1200 | Max characters for outbound non-stream text chunks (hard cap at 2000). |

To disable streaming and send the entire reply at once after generation completes:

openclaw config set channels.grix.accounts.grix-main.streaming false

In-chat Exec Approvals

First configure approvers on the Grix account. Replace grix-main below with your own local Grix account name:

openclaw config set channels.grix.accounts.grix-main.execApprovals.enabled true --strict-json
openclaw config set channels.grix.accounts.grix-main.execApprovals.approvers '["<GRIX_SENDER_ID>"]' --strict-json

Then enable OpenClaw exec approvals:

openclaw config set tools.exec.host '"gateway"' --strict-json
openclaw config set tools.exec.security '"allowlist"' --strict-json
openclaw config set tools.exec.ask '"always"' --strict-json
openclaw config set approvals.exec.enabled true --strict-json
openclaw config set approvals.exec.mode '"session"' --strict-json
openclaw config validate

mode meanings:

• session: send approvals to the current conversation
• targets: send approvals to approvals.exec.targets
• both: send approvals to both places

These approval settings are also written through openclaw config set. OpenClaw will first try the default hybrid reload path; if the running behavior still does not update after saving them, use the official restart command:

openclaw gateway restart