grix-connector/openclaw-plugin/skills/grix-update/SKILL.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.

---
name: grix-update
description: Handles subsequent version maintenance of the Grix plugin. Applicable for checking new versions, performing plugin upgrades, completing post-upgrade validation and restart, and silently or notifying the main agent according to rules; not responsible for initial installation, account registration, local binding, or install private chat flows.
---

# Grix Update

This skill is solely responsible for **Grix plugin version maintenance**.  
The goal is to enable `grix-connector`, once installed into OpenClaw, to perform update checks, upgrade acceptance, and failure alerts according to fixed rules.

## Role Boundary

1. This skill only performs plugin update-related actions: check, upgrade, validate, restart, notify.
2. This skill does not perform initial installation, account registration, or agent binding.
3. This skill does not take over install private chats; if the current context is still in an egg install flow, stop and hand back to `grix-egg` / `grix-admin`.
4. Only use the official OpenClaw CLI; do not manually edit `openclaw.json` or write temporary scripts to modify the plugin install directory.

## Applicable Scenarios

1. User requests "check if grix has a new version".
2. User requests "upgrade the grix plugin".
3. Need to provide a standalone maintenance skill for subsequent automation.
4. Scheduled tasks want to silently check, only notifying the main agent on failure.

## Input Parameters

### Common Parameters

1. `mode` (required)
   - `check-only`
   - `apply-update`
   - `check-and-apply`
2. `plugin_id` (optional)
   - Default: `grix`
3. `notify_on` (optional)
   - `failure` (default)
   - `always`
   - `never`
4. `main_agent` (optional)
   - Primarily used for cron's `--agent <main_agent>` or upper-level workflow marking "who is responsible for maintaining this machine"
   - It is not itself a directly deliverable `to` / `session_id` target for Grix messages; if there is no explicit deliverable session, do not guess a notification target just because you have `main_agent`
5. `allow_restart` (optional)
   - Default: `true`

### Recommended Default Input

```json
{
  "mode": "check-and-apply",
  "plugin_id": "grix",
  "notify_on": "failure",
  "allow_restart": true
}
```

## Completion Standard

Only when all of the following conditions are met is the task considered complete:

1. Confirmed whether the target plugin exists.
2. Confirmed whether the current installation method supports automatic updates.
3. Executed the check action and provided a clear result: no update / upgraded / failed / unsupported.
4. If an upgrade was performed, completed:
   - `openclaw plugins doctor`
   - `openclaw gateway restart` (only when `allow_restart=true`)
   - `openclaw health`
5. If notification rules are configured, completed notification or silently ended according to the rules.

## Execution Rules

### 0. Context Guard First

1. If the current context is clearly an egg install private chat, or the context contains install-related fields like `install_id`, `egg`, `install.route`, do not perform the update — state that the current scenario is not suitable for plugin upgrade and stop.
2. Do not trigger plugin upgrades during an ongoing installation conversation.

### 1. Confirm Plugin Exists First

Execute first:

```bash
openclaw plugins info <plugin_id> --json
```

Rules:

1. If the plugin does not exist, return `failed/not_installed` and stop.
2. If the command fails, return the failure reason; do not continue guessing.

### 2. Confirm Whether Automatic Update Is Supported

Execute first:

```bash
openclaw plugins update <plugin_id> --dry-run
```

Rules:

1. If dry-run explicitly indicates the current plugin cannot be updated, is not tracked, or is not an npm install, return `unsupported/not_npm_install` and stop.
2. Only proceed with subsequent steps when updates are supported.
3. Do not force local directory installs, `--link` installs, or manual copy installs to be treated as auto-updatable.

### 3. `check-only`

Only check, do not upgrade.

Rules:

1. Run dry-run.
2. If no new version:
   - Return `no_update`
   - Silently end by default
3. If a new version is found:
   - Return `update_available`
   - Do not perform the actual upgrade

### 4. `apply-update`

Assumes the caller has already decided to upgrade; execute the upgrade directly.

Execution order:

```bash
openclaw plugins update <plugin_id>
openclaw plugins doctor
openclaw gateway restart
openclaw health
```

Rules:

1. If `allow_restart=false`, skip `openclaw gateway restart`, but clearly state that the upgrade has not been restarted and the runtime may still be the old version.
2. If any step fails, stop immediately and return the failure point.
3. Do not automatically retry consecutively after failure.

### 5. `check-and-apply`

This is the most suitable mode for automation.

Rules:

1. Run dry-run first.
2. If no new version:
   - Return `no_update`
   - Silently end
3. If a new version is found:
   - Execute the full `apply-update` flow

## Validation Order

If an upgrade was performed, validation must follow this order:

1. `openclaw plugins doctor`
2. `openclaw gateway restart` (if allowed)
3. `openclaw health`

Do not claim success immediately after writing the upgrade command.

## Notification Rules

The behavior of `notify_on` is fixed as follows:

1. `never`
   - Never send notifications
2. `failure`
   - Only notify the main agent on failure
3. `always`
   - Notify the main agent on both success and failure

Supplementary rules:

1. `main_agent` only represents the maintenance responsibility owner; it does not automatically equate to a message-deliverable session target.
2. If the current context has no explicit maintenance session or reusable notification target, just return the result and let the upper-level cron / caller handle notification; do not guess `to`, `session_id`, or private chat targets on your own.
3. Cron scenarios should prefer `notify_on=never`; let the cron run records handle convergence.

Default is `failure`.

## Notification Content Requirements

Notifications must be brief, stating only the result without expanding on technical details.

Recommended copy style:

1. Success:
   - `Grix plugin upgrade completed, current checks are normal.`
2. No update:
   - `Grix plugin checked, no new version available.`
3. Failure:
   - `Grix plugin auto-update failed, stuck at <step>.`
4. Auto-update not supported:
   - `Grix is not installed in an auto-updatable way; switch to npm install before enabling auto-update.`

## Return Results

The skill should return clear, stable result states, recommended to converge to these categories:

1. `no_update`
2. `update_available`
3. `updated`
4. `failed`
5. `unsupported`

If failed, must specify which step the failure belongs to:

1. `plugins info`
2. `plugins update --dry-run`
3. `plugins update`
4. `plugins doctor`
5. `gateway restart`
6. `health`

## Guardrails

1. Do not modify initial installation logic; do not replace `grix-register`, `grix-admin`, `grix-egg`.
2. Do not perform plugin upgrades during install private chats.
3. Only use official commands:
   - `openclaw plugins info`
   - `openclaw plugins update`
   - `openclaw plugins doctor`
   - `openclaw gateway restart`
   - `openclaw health`
4. Do not directly modify the plugin directory or manually overwrite npm package contents.
5. Do not write bypass logic to "accommodate" old installation methods; unsupported means unsupported.
6. If the upgrade has not been restarted, do not claim the runtime has completed the switch.
7. Do not automatically retry at high frequency; after failure, hand off to the next scheduled cycle or manual intervention.

## Recommended Automation Integration

When used for scheduled tasks, prefer:

```json
{
  "mode": "check-and-apply",
  "plugin_id": "grix",
  "notify_on": "failure",
  "main_agent": "main",
  "allow_restart": true
}
```

Recommended frequency:

1. Once per day
2. Or once every 6 hours

Default strategy:

1. No update: silent
2. Update successful: silent
3. Update failed: notify main agent

## Recommended Cron Setup

If you want automatic maintenance after plugin installation, it is recommended to create an isolated cron task directly, rather than embedding the upgrade action into the main session heartbeat.

Recommended command:

```bash
openclaw cron add \
  --name "grix auto update" \
  --every "6h" \
  --agent <main_agent> \
  --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.'
```

Rules:

1. `--session isolated`: Do not bind to the main session to avoid updates and restarts interrupting the current chat.
2. `--no-deliver`: Stay silent on success.
3. `notify_on` in cron scenarios should be fixed to `never`; let the cron's own run records handle troubleshooting.
4. `main_agent` should use the main agent responsible for maintaining this machine.
5. Recommended frequency starts at `6h`; if you want to be more conservative, change to once per day.

If a task with the same name already exists, do not create a duplicate; use edit instead:

```bash
openclaw cron edit <job_id> \
  --every "6h" \
  --agent <main_agent> \
  --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.'
```

After creation, it is recommended to verify:

```bash
openclaw cron list
openclaw cron status
```

## Division of Responsibilities with Other Skills

1. `grix-register`
   - Only responsible for cloud account and API agent parameters
2. `grix-admin`
   - Only responsible for local configuration and binding
3. `grix-egg`
   - Only responsible for the install private chat flow
4. `grix-update`
   - Only responsible for subsequent version maintenance

## References

1. [references/update-contract.md](references/update-contract.md)
2. [references/cron-setup.md](references/cron-setup.md)