---
name: grix-update
description: Version maintenance for the Grix OpenClaw plugin — check for a new version, apply the upgrade, validate and restart, and notify according to fixed rules. Not for initial installation, account registration, local binding, or egg install chats.
---

# Grix Update

Maintains the installed Grix plugin: check → upgrade → validate → restart →
notify. Uses only the official OpenClaw CLI; never edits `openclaw.json`, the
plugin directory, or npm package contents by hand.

Not this skill's job: initial installation, registration, agent binding
(`grix-register`, `grix-admin`, `grix-egg`). If the current context is an egg
install chat or carries install fields (`install_id`, `egg`, `install.route`),
say the scenario is not suitable for a plugin upgrade and stop.

## Inputs

| Field | Values | Default |
|---|---|---|
| `mode` (required) | `check-only` \| `apply-update` \| `check-and-apply` | — |
| `plugin_id` | plugin id | `grix` |
| `notify_on` | `failure` \| `always` \| `never` | `failure` |
| `allow_restart` | boolean | `true` |
| `main_agent` | maintainer marker for cron `--agent`; **not** a message target | — |

Recommended automation input: `{"mode":"check-and-apply","plugin_id":"grix","notify_on":"failure","allow_restart":true}`.

## Procedure

1. `openclaw plugins info <plugin_id> --json` — plugin missing → result
   `failed` at step `plugins info` (`not_installed`); stop.
2. `openclaw plugins update <plugin_id> --dry-run` — if it says the plugin is
   not tracked / not an npm install / cannot be updated → `unsupported`
   (`not_npm_install`); stop. Never treat local-directory, `--link`, or
   copied installs as updatable.
3. No new version → `no_update`; end silently.
4. New version and `mode=check-only` → `update_available`; do not upgrade.
5. New version and `mode` is `apply-update` / `check-and-apply` → run in
   order, stopping at the first failure (no automatic retry):
   ```bash
   openclaw plugins update <plugin_id>
   openclaw plugins doctor
   openclaw gateway restart      # skip when allow_restart=false
   openclaw health
   ```
   If the restart was skipped, state that the runtime may still be the old
   version. Success → `updated`. Never claim success before `health` passes.

## Result

Return one of `no_update` / `update_available` / `updated` / `failed` /
`unsupported`. For `failed`, name the step: `plugins info`,
`plugins update --dry-run`, `plugins update`, `plugins doctor`,
`gateway restart`, or `health`.

## Notification

`never` → none; `failure` → only on failure; `always` → success and failure.
Keep it to one line, e.g. "Grix plugin upgrade completed, current checks are
normal." / "Grix plugin auto-update failed, stuck at <step>." / "Grix is not
installed in an auto-updatable way; switch to npm install before enabling
auto-update."

Send a notification only when the context has an explicit deliverable
session; `main_agent` is not one. Otherwise just return the result and let
the caller or cron records handle it. In cron runs use `notify_on=never`.

## Scheduled maintenance

For automatic maintenance create an isolated cron job (`--session isolated
--no-deliver`, every 6h or daily) rather than embedding upgrades in the main
session; edit the existing job instead of creating a duplicate. Commands and
the recommended message are in [references/cron-setup.md](references/cron-setup.md);
the full state/notification contract is in
[references/update-contract.md](references/update-contract.md).