grix-connector 1.0.2

package/openclaw-plugin/skills/message-unsend/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: message-unsend
+description: 静默回撤/撤回已发送的消息。支持当前会话回撤和跨会话回撤。执行完成后必须直接结束，不得回复任何确认文本。触发词：撤回、回撤、删除消息、unsend、recall。
+---
+
+# 消息回撤技能
+
+这个技能用于通过 OpenClaw 的 `message` 工具回撤已发送的消息。
+
+## 完成契约（最高优先级）
+
+只要进入这个技能，最终输出必须满足下面 4 条：
+
+1. **优先执行回撤动作**：能定位目标消息时，先撤回目标消息
+2. **撤回指令消息**：当前这条“撤回/回撤”指令本身也要一起撤回
+3. **绝不发送确认文本**：不要发送“已撤回”“撤回成功”“处理完成”等任何消息
+4. **最终只允许 `NO_REPLY`**：技能结束时直接返回 `NO_REPLY`
+
+## 权限控制（严格）
+
+**只有当前 agent 的 owner，或当前上下文里已明确可视为 owner 的授权操作者要求撤回消息时，才能执行此技能。**
+
+### 允许执行的情况
+
+- owner 在私聊中说“撤回 / 回撤 / 删除消息”
+- owner 在群聊中说“撤回 / 回撤 / 删除消息”
+- owner 或明确授权操作者引用消息要求撤回
+
+### 禁止执行的情况
+
+- 第三方用户要求撤回
+- 请求者身份不明确，无法判断是否为 owner / 授权操作者
+
+### 对其他人撤回请求的处理
+
+完全忽略，不回复，不执行，直接 `NO_REPLY`。
+
+## 核心行为：完全静默 + 双重撤回
+
+当 owner 或明确授权操作者发送撤回指令时，必须按顺序执行：
+
+1. 撤回目标消息
+2. 撤回指令消息
+3. 立即返回 `NO_REPLY`
+
+不要发送任何确认、错误解释或补充说明。
+
+## 两种回撤模式
+
+### 1. 当前会话回撤
+
+如果目标消息就在当前 Grix 会话中，必须给出 `messageId`；`sessionId` / `to` / `topic` 可以省略。
+
+```json
+{
+  "action": "unsend",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "messageId": "18889990099"
+}
+```
+
+### 2. 跨会话回撤
+
+如果目标消息不在当前会话中，优先使用 `sessionId` 指向目标会话。`to` 和 `topic` 只是兼容别名，不要作为主写法。
+
+```json
+{
+  "action": "unsend",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "messageId": "18889990099",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950"
+}
+```
+
+## 参数规则
+
+1. `messageId` 必填，且必须是数字字符串
+2. 当前 Grix 会话里，可以省略 `sessionId` / `to` / `topic`
+3. 跨会话时，优先传准确 `sessionId`
+4. `to` / `topic` 只是兼容别名；如果使用 `topic`，传裸 `session_id` 即可
+5. 不要硬编码 `accountId=default`，始终使用当前准确账号 ID
+
+## 使用场景
+
+- 用户在当前对话中说“把刚才那条撤回”
+- 需要静默清理自己刚发错的消息
+- 需要跨会话回撤某条已知消息
+
+## 实际调用示例
+
+### 示例 1：当前会话回撤
+
+```json
+{
+  "action": "unsend",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "messageId": "2033329436849868800"
+}
+```
+
+### 示例 2：跨会话回撤
+
+```json
+{
+  "action": "unsend",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "messageId": "2033474284277993472",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950"
+}
+```
+
+## 重要说明
+
+1. Grix 渠道可以回撤 agent 和用户发送的消息
+2. 跨会话时必须先拿到准确目标会话，不要传用户 ID、agent ID 或旧的其他渠道会话格式
+3. `messageId` 可以从 inbound context、之前发送结果或消息记录中获取
+4. 当前指令消息如果能定位，会一起被静默回撤
+
+## 错误处理
+
+常见错误只做内部判断，不要转成对用户的回复：
+
+- `messageId` 不存在：直接 `NO_REPLY`
+- 无法解析目标会话：直接 `NO_REPLY`
+- 权限不足：直接 `NO_REPLY`
+- 消息已删除：直接 `NO_REPLY`
+
+## Grix 实测结果（2026-03-16 更新）
+
+**状态**：可用
+
+### 示例：撤回 agent 发送的消息
+
+```json
+{
+  "action": "unsend",
+  "channel": "grix",
+  "accountId": "primary",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950",
+  "messageId": "2033371385615093760"
+}
+```
+
+返回：
+
+```json
+{
+  "ok": true,
+  "deleted": true,
+  "unsent": true,
+  "messageId": "2033371385615093760",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950"
+}
+```
+
+### 示例：撤回用户发送的消息
+
+```json
+{
+  "action": "unsend",
+  "channel": "grix",
+  "accountId": "primary",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950",
+  "messageId": "2033474284277993472"
+}
+```
+
+返回：
+
+```json
+{
+  "ok": true,
+  "deleted": true,
+  "unsent": true,
+  "messageId": "2033474284277993472",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950"
+}
+```
+
+## 收尾要求
+
+只要执行了这个技能，最后一行必须是 `NO_REPLY`。不要留下任何确认文本。

package/openclaw-plugin/skills/message-unsend/flowchart.mermaid

@@ -0,0 +1,27 @@
+```mermaid
+flowchart TD
+    Start([收到撤回请求]) --> CheckSender{请求者是当前 agent 的 owner / 已授权操作者?}
+    CheckSender -->|否或不明确| End1[直接 NO_REPLY]
+    CheckSender -->|是| ResolveTarget{能定位目标消息?}
+
+    ResolveTarget -->|否| End2[直接 NO_REPLY]
+    ResolveTarget -->|是| PrepareTarget[准备目标消息参数<br/>action=unsend<br/>channel=grix<br/>accountId=current<br/>sessionId=目标会话或省略(当前会话)<br/>messageId=目标消息]
+
+    PrepareTarget --> UnsendTarget[执行目标消息撤回]
+    UnsendTarget --> TargetResult{成功或已删除?}
+    TargetResult -->|否| End3[直接 NO_REPLY]
+    TargetResult -->|是| PrepareCommand[准备指令消息参数<br/>action=unsend<br/>channel=grix<br/>accountId=current<br/>sessionId=当前会话(必要时解析)<br/>messageId=当前指令消息]
+
+    PrepareCommand --> UnsendCommand[执行指令消息撤回]
+    UnsendCommand --> End4[返回 NO_REPLY]
+
+    style Start fill:#e1f5e1
+    style End1 fill:#ffe1e1
+    style End2 fill:#ffe1e1
+    style End3 fill:#ffe1e1
+    style End4 fill:#e1f5e1
+    style CheckSender fill:#fff4e1
+    style ResolveTarget fill:#fff4e1
+    style UnsendTarget fill:#e1f0ff
+    style UnsendCommand fill:#e1f0ff
+```

package/openclaw-plugin/skills/openclaw-memory-setup/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: openclaw-memory-setup
+description: Configure OpenClaw memory on the target machine from either user-provided provider settings or a measured local-model choice. Use when Codex needs to apply direct memory parameters such as `provider=openai` or `provider=ollama`, compare local Ollama embedding models by real machine speed, update one or more OpenClaw profiles, rebuild indexes after a model change, or verify that memory is healthy on resource-constrained hosts.
+---
+
+# OpenClaw Memory Setup
+
+## Overview
+
+Use this skill to either apply user-supplied memory provider settings directly or take a machine from readiness check through Ollama and OpenClaw installation, then choose a local embedding model by measurement and apply it to OpenClaw profiles safely.
+
+Read [host-readiness.md](references/host-readiness.md) before working on a fresh machine.
+
+## Request Handling
+
+Start by sorting the request into one of these paths:
+
+- Direct config path:
+  - use when the user already gives the target profiles, target model, provider choice, machine facts, or existing install state
+  - do not force a full readiness survey first
+- Guided config path:
+  - use when the user has partial information and needs a few missing parameters filled in
+- Fresh machine path:
+  - use when the user has not installed the stack yet or cannot tell what exists
+
+Ask only for the minimum missing inputs when the user already knows what they want. Do not make them re-prove that `ollama` exists if they already supplied enough concrete parameters to proceed safely.
+
+## Completion Standard
+
+- Confirm the machine is supported and identify what is missing.
+- If the chosen path uses local Ollama memory, install or verify Ollama with the official method for that OS.
+- If the target machine still lacks OpenClaw, install or verify it with the official Ollama integration path.
+- If the chosen path uses local Ollama memory, pull or confirm the candidate models on the target machine.
+- If the chosen path uses local Ollama memory, benchmark the candidates on the target machine with [bench_ollama_embeddings.ts](scripts/bench_ollama_embeddings.ts).
+- Write the chosen model into each target `openclaw.json`.
+- Validate the config, restart the profile, and rebuild memory.
+- Confirm that `memory status` and `status` both look healthy for every target profile.
+
+## Fast Rules
+
+- Benchmark on the target machine. Do not benchmark locally and assume the same result remotely.
+- If the user already provides enough concrete parameters to edit the config safely, skip the readiness survey and move straight to config update, validation, restart, and rebuild.
+- If the user already provides a provider, model, and any required provider-specific settings, prefer direct configuration over local-model benchmarking.
+- On a fresh machine or an unclear host, start with [survey_host_readiness.ts](scripts/survey_host_readiness.ts).
+- If `ollama` is missing, install it first with the official download or install script for that OS.
+- If OpenClaw itself or a usable OpenClaw management entrypoint is missing, install OpenClaw through `ollama launch openclaw` instead of inventing a custom path.
+- Treat Windows as a special case: native Windows and WSL2 are both supported, but WSL2 remains the more stable and recommended path for the full CLI, Gateway, and tooling flow. If the machine already runs OpenClaw natively and the requested work stays within supported native CLI/Gateway paths, do not force a WSL migration.
+- If the user has nothing set up and wants to save money, prefer local Ollama deployment instead of cloud-first suggestions.
+- On resource-constrained hosts, start with `embeddinggemma:300m-qat-q8_0`, `nomic-embed-text:latest`, and `qwen3-embedding:0.6b`.
+- Treat `qwen3-embedding:latest` as a last resort on slow hardware.
+- If the same maintenance window also upgrades `grix`, upgrade `grix` first and rebuild memory once at the end.
+- Update `agents.defaults.memorySearch.provider` and `agents.defaults.memorySearch.model` at the profile level unless one agent truly needs a different model.
+- Restart the profile after a config change, then reindex memory.
+- Treat `0/0 files` or `no memory files found` as normal for empty agents. Treat `config validate` failure, crashed services, or missing indexed files as actual failures.
+- If reindex progress keeps moving, let it finish. Large session logs can take minutes on older machines.
+
+## 1. Choose The Right Entry Path
+
+### Direct config path
+
+Use this path when the user already provides most of these:
+
+- target profile names or config paths
+- target provider such as `openai` or `ollama`
+- target memory model
+- whether the machine already has Ollama and OpenClaw
+- whether the goal is just to switch memory settings
+
+In this path:
+
+- skip the readiness survey unless something important is still unclear
+- skip installation checks that do not affect the requested change
+- if the provider is not `ollama`, skip local model benchmarking unless the user explicitly asks for it
+- update the config directly
+- validate, restart, and rebuild
+
+### Fresh machine path
+
+Use this path when the user says they have nothing set up yet, or wants a cheap setup from scratch.
+
+In this path:
+
+- recommend local Ollama first if the user wants to save money
+- survey the machine
+- install missing pieces through the official path
+- if the host is native Windows, prefer WSL for the full setup and heavier automation/tooling path, but do not falsely claim native Windows is unsupported when the requested steps already fit supported native CLI/Gateway flows
+- then benchmark and configure memory
+
+### Provider-specific shortcut
+
+If the user directly gives provider settings such as `provider=openai`, API base, model, and target profiles:
+
+- do not route them through local Ollama setup unless they ask for a local option
+- write the memory settings directly
+- validate, restart, and rebuild
+
+## 2. Survey The Machine
+
+Run [survey_host_readiness.ts](scripts/survey_host_readiness.ts):
+
+```bash
+node scripts/survey_host_readiness.ts
+```
+
+This checks:
+
+- OS, architecture, CPU count, and total RAM
+- whether the current shell is macOS native, Linux native, WSL, or native Windows
+- whether `ollama`, `openclaw`, a usable OpenClaw management entrypoint, `node`, and `npm` exist
+- whether the local Ollama API is reachable
+- a starting shortlist of memory models based on a conservative RAM heuristic
+
+If the machine is clearly undersized for your original plan, downgrade the candidate list before pulling large models.
+
+## 3. Install Missing Pieces
+
+Follow [host-readiness.md](references/host-readiness.md) for the official path.
+
+Use these rules:
+
+- If `ollama` is missing:
+  - install Ollama first
+- If `ollama` exists but OpenClaw or a usable OpenClaw management entrypoint is missing:
+  - run `ollama launch openclaw` for interactive setup
+  - or run `ollama launch openclaw --model <model> --yes` for headless setup
+- If the machine is only being prepared and should not start the TUI:
+  - run `ollama launch openclaw --config`
+
+If the user wants the cheapest practical setup from scratch:
+
+- recommend local Ollama for memory embeddings
+- start with smaller local embedding models
+- avoid steering them toward cloud models unless they explicitly want stronger remote models or their hardware cannot carry the workload
+
+Do not patch OpenClaw internals to skip the official setup flow.
+
+Skip this whole installation step when the user is only asking to apply already-known remote provider settings and the machine already has OpenClaw.
+
+## 4. Pick Candidate Models
+
+On resource-constrained hosts, start with these candidates:
+
+```bash
+ollama pull embeddinggemma:300m-qat-q8_0
+ollama pull nomic-embed-text:latest
+ollama pull qwen3-embedding:0.6b
+```
+
+Only try `qwen3-embedding:latest` when the machine already handles the smaller models comfortably and a long rebuild window is acceptable.
+
+Use the readiness script output as the first filter on other machines:
+
+- low-memory hosts: start with the smallest shortlist it recommends
+- mid-range hosts: start with `embeddinggemma`, `nomic-embed-text`, and `qwen3-embedding:0.6b`
+- strong hosts: add larger candidates only if there is a real reason
+
+## 5. Benchmark On The Target Machine
+
+Use [bench_ollama_embeddings.ts](scripts/bench_ollama_embeddings.ts):
+
+```bash
+node scripts/bench_ollama_embeddings.ts \
+  embeddinggemma:300m-qat-q8_0 \
+  nomic-embed-text:latest \
+  qwen3-embedding:0.6b
+```
+
+Use `--rounds 2` for a cleaner comparison. Use `--batch-size 2` for a quicker smoke test.
+
+Prefer the fastest model that succeeds cleanly. On smaller or older hosts, these rough bands work well:
+
+- Excellent: single <= 5s and batch-of-4 <= 15s
+- Acceptable: single <= 20s and batch-of-4 <= 60s
+- Poor: slower than that, or painful to repeat during rebuilds
+
+## 6. Write The Chosen Provider Settings Into OpenClaw Config
+
+Preview the change first:
+
+```bash
+node scripts/set_openclaw_memory_model.ts \
+  --model embeddinggemma:300m-qat-q8_0 \
+  <profile-dir-1> \
+  <profile-dir-2>
+```
+
+Apply it only after the preview looks right:
+
+```bash
+node scripts/set_openclaw_memory_model.ts \
+  --write \
+  --model embeddinggemma:300m-qat-q8_0 \
+  <profile-dir-1> \
+  <profile-dir-2>
+```
+
+The script creates a timestamped backup beside each `openclaw.json`.
+Its preview output redacts common secret-like fields such as API keys, tokens, and authorization headers.
+
+For a direct remote-provider setup, change the provider flag and supply the target model:
+
+```bash
+node scripts/set_openclaw_memory_model.ts \
+  --write \
+  --provider openai \
+  --model text-embedding-3-small \
+  <profile-dir>
+```
+
+If the provider needs extra keys, pass them in the same command with repeated `--set KEY=VALUE` flags. Keys are relative to `agents.defaults.memorySearch`, support dotted paths, and parse JSON values when possible.
+When the provider changes, the script replaces the previous `memorySearch` object before writing the new provider settings so that stale fields do not leak across providers.
+
+Examples:
+
+```bash
+node scripts/set_openclaw_memory_model.ts \
+  --write \
+  --provider openai \
+  --model text-embedding-3-small \
+  --set apiKey=env:OPENAI_API_KEY \
+  --set baseURL=https://api.openai.com/v1 \
+  <profile-dir>
+```
+
+```bash
+node scripts/set_openclaw_memory_model.ts \
+  --write \
+  --provider custom \
+  --model my-embed-model \
+  --set 'headers.Authorization=Bearer token-value' \
+  --set timeoutSeconds=30 \
+  <profile-dir>
+```
+
+## 7. Validate, Restart, And Rebuild
+
+Use the official `openclaw` CLI by default on unknown hosts. If a local wrapper exists on a specific machine, adapt locally, but keep the skill examples on the official CLI. The shell examples below are for macOS, Linux, or WSL.
+
+```bash
+openclaw --profile <profile> config validate
+openclaw --profile <profile> gateway restart
+openclaw --profile <profile> memory index --force
+openclaw --profile <profile> memory status
+openclaw --profile <profile> status
+```
+
+For multiple profiles:
+
+```bash
+for p in <profile-1> <profile-2>; do
+  openclaw --profile "$p" config validate || break
+  openclaw --profile "$p" gateway restart || break
+  openclaw --profile "$p" memory index --force || break
+  openclaw --profile "$p" memory status
+  openclaw --profile "$p" status
+done
+```
+
+If a given machine exposes only a wrapper around `openclaw`, map the same five actions onto that wrapper locally: validate config, restart, rebuild memory, inspect memory status, and inspect runtime status.
+
+Use `memory status --deep` when counts do not match what you expect.
+
+## 8. Judge The Result Correctly
+
+A rollout is done when:
+
+- `config validate` passes
+- the service is running
+- the chosen model appears in `memory status`
+- indexed counts match real memory and session files for agents that actually have content
+- large agents finish eventually instead of bouncing forever
+
+Not a failure by itself:
+
+- empty agents showing `0/0 files`
+- empty agents showing `no memory files found`
+- one or two very large session logs taking much longer than the rest
+
+## Reference
+
+Read [host-readiness.md](references/host-readiness.md) for the generic install and readiness path.
+Read [case-study-macpro.md](references/case-study-macpro.md) only as one measured example on an older machine.

package/openclaw-plugin/skills/openclaw-memory-setup/references/case-study-macpro.md

@@ -0,0 +1,52 @@
+# MacPro Case Study
+
+Date of run: April 5, 2026
+
+This page is one measured example on an older machine. Do not treat it as the default plan for all hosts.
+
+Environment:
+
+- old MacPro-class machine reached over SSH
+- Ollama used for OpenClaw memory embeddings
+- OpenClaw profiles stored under a shared profile directory on the host
+
+## Model Results
+
+| Model | Approx size | Single embed | Batch-of-4 embed | Main rebuild | Result |
+| --- | --- | ---: | ---: | ---: | --- |
+| `embeddinggemma:300m-qat-q8_0` | 338 MB | 3.11 s | 8.54 s | 59 s | Best overall choice on this machine |
+| `qwen3-embedding:0.6b` | 639 MB | 16.53 s | 61.86 s | 421 s | Works, but much slower |
+| `nomic-embed-text:latest` | 274 MB | 19.48 s | 76.69 s | not run end-to-end | Viable fallback, slower than `embeddinggemma` here |
+| `qwen3-embedding:latest` | 4.7 GB | over 4 min for one request in testing | not practical | rebuild timed out in practice | Not suitable for this old machine |
+
+## Operational Lessons
+
+- Pick the model by measured speed on the target machine, not by size or reputation.
+- `embeddinggemma:300m-qat-q8_0` was the clear winner on this MacPro.
+- Upgrade `grix` first if that work is part of the same maintenance window, then rebuild memory once.
+- Reindex jobs can look slow but still be healthy. Large session logs were the main reason:
+  - one `xiaoli` session file was about 320 KB
+  - one `gema` session file was about 721 KB
+- Empty agents can legitimately show `0/0 files` or `no memory files found`.
+- Real failures were configuration errors, services not running, or indexed counts lower than the actual memory and session file counts.
+
+## Final Deployed State
+
+These standalone profiles were moved to `embeddinggemma:300m-qat-q8_0` and verified healthy:
+
+- `main`
+- `lwq`
+- `lsx`
+- `zmy`
+- `jy`
+- `zx`
+- `ly`
+- `jk`
+- `zpf`
+
+`main` subagents with real memory content were also rebuilt successfully:
+
+- `main`
+- `xiaoli`
+- `gema`
+- `carousel-growth-engine`

package/openclaw-plugin/skills/openclaw-memory-setup/references/host-readiness.md

@@ -0,0 +1,147 @@
+# Host Readiness
+
+Use this page when the target machine is not already prepared.
+
+## Official Current Install Path
+
+As of April 8, 2026:
+
+- Ollama is available on macOS, Windows, and Linux.
+- The Ollama quickstart exposes `ollama launch openclaw` as the official way to start OpenClaw from Ollama.
+- The OpenClaw integration page says Ollama will prompt to install OpenClaw via npm if OpenClaw is missing.
+- The current Ollama tutorial for OpenClaw says you need:
+  - Ollama 0.17 or later
+  - Node.js
+  - Mac or Linux for the smoothest direct setup
+  - Windows users can use WSL for the OpenClaw setup path
+- The current OpenClaw Windows docs say native Windows and WSL2 are both supported; WSL2 is the more stable and recommended path for the full experience.
+
+## OS Split
+
+- macOS:
+  - install and run Ollama natively
+  - install and run OpenClaw natively
+- Linux:
+  - install and run Ollama natively
+  - install and run OpenClaw natively
+- Windows:
+  - native Ollama installation is fine
+  - native OpenClaw CLI/Gateway flows can work
+  - WSL2 is still the recommended path for the full CLI, Gateway, and tooling experience
+  - do not write the skill as if WSL were mandatory for every Windows task, but also do not present native Windows as the preferred path for shell-heavy automation and repo work
+
+## Readiness Checklist
+
+- Confirm the OS and architecture.
+- Confirm whether you are in native macOS, native Linux, WSL, or native Windows.
+- Confirm enough RAM or unified memory for the candidate models you plan to test.
+- Confirm `ollama` is installed.
+- Confirm `node` and `npm` exist before expecting OpenClaw installation through Ollama to succeed.
+- Confirm the local Ollama API responds on `http://127.0.0.1:11434`.
+- Confirm whether OpenClaw itself and a usable management entrypoint already exist.
+
+## When To Skip The Survey
+
+Skip the full readiness survey when the user already gives enough information to do a direct config change safely, for example:
+
+- exact target profile names or config paths
+- exact memory model to use
+- confirmation that Ollama and OpenClaw are already installed
+- a request that is only about switching memory configuration, not installing the stack
+
+In that case, go straight to config update, validation, restart, and rebuild.
+
+## Official Commands
+
+### Install or verify Ollama
+
+Linux:
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+macOS:
+
+- use the official app download, or
+- use the same official install script if that matches the environment policy
+
+Windows:
+
+- install Ollama from the official Windows download
+- if the goal is a fresh full OpenClaw rollout, prefer WSL2 for the setup flow
+- when documenting commands in the skill, prefer the path that matches the current machine: WSL shell commands for WSL setups, native CLI commands only when the host already uses a supported native Windows flow
+
+### Install or configure OpenClaw through Ollama
+
+Interactive:
+
+```bash
+ollama launch openclaw
+```
+
+Configure only:
+
+```bash
+ollama launch openclaw --config
+```
+
+Headless:
+
+```bash
+ollama launch openclaw --model kimi-k2.5:cloud --yes
+```
+
+Notes:
+
+- `--yes` requires `--model`
+- if OpenClaw is missing, Ollama prompts to install it via npm
+- if the gateway is already running, changing the model through `ollama launch openclaw --config` restarts it automatically
+
+## Management Entry Point
+
+Do not assume one machine-specific wrapper across all machines.
+
+- The generic, documented CLI is `openclaw`.
+- Some machines may also expose a local wrapper.
+- A reusable skill should prefer the documented `openclaw` CLI in its examples, then adapt only if the current machine exposes a different wrapper.
+
+## Direct Provider Configs
+
+If the user already knows the remote memory provider settings, do not force a local Ollama path first.
+
+- You may go straight to updating `agents.defaults.memorySearch`.
+- `provider` and `model` are the minimum fields.
+- Provider-specific fields such as API base, headers, or key references should be written at the same time instead of leaving the config half-finished.
+- If you are switching providers, replace the old provider-specific settings instead of leaving stale fields behind.
+- Only benchmark local Ollama models when the user wants a local memory provider or asks for a speed comparison.
+
+## Choosing Memory Embedding Candidates
+
+This is a heuristic for the first pass only. The final choice must come from a benchmark on the target machine.
+
+- If the user has nothing yet and wants to save money:
+  - prefer local Ollama deployment
+  - prefer smaller local embedding models first
+  - keep cloud suggestions optional, not default
+- very constrained hosts:
+  - start with `nomic-embed-text:latest`
+  - add `embeddinggemma:300m-qat-q8_0` if the machine is still responsive
+- older or mid-range hosts:
+  - start with `embeddinggemma:300m-qat-q8_0`
+  - compare with `nomic-embed-text:latest`
+  - add `qwen3-embedding:0.6b` only if you can afford a slower rebuild
+- stronger machines:
+  - still benchmark the smaller models first
+  - only add larger models when there is a clear quality reason
+
+## When To Stop And Re-Scope
+
+- If `ollama` will not install cleanly through the official method, stop and resolve that first.
+- If `node` or `npm` is missing and the machine needs OpenClaw installation, install Node.js before retrying OpenClaw setup.
+- If local embedding models are too slow, keep the smaller local memory model and move only the main assistant model to cloud if needed.
+- If the machine is Windows without WSL, do not invent a Linux-only path. If the requested work already fits supported native Windows CLI/Gateway flows, continue there; otherwise set up WSL2 or use a Mac/Linux host.
+
+## Optional Example
+
+See [case-study-macpro.md](case-study-macpro.md) for one measured old-machine rollout. Treat it as an example, not a universal baseline.