docs(cost): add upstream safety rules to cost optimization plan

Hard constraints: no dist edits, no undocumented config keys, no middleware.
Safe: documented openclaw.json knobs + workspace files only.
Includes update workflow and pre-implementation verification checklist.
This commit is contained in:
zap
2026-03-05 20:25:59 +00:00
parent 6642964ae6
commit c2fe8155e3

View File

@@ -282,6 +282,40 @@ Add a section documenting when to use which model tier for subagents, so the con
---
## Upstream Safety Rules
These are hard constraints. Any implementation that violates them is out of scope.
### ❌ Never do
- Edit files under `~/.npm-global/lib/node_modules/openclaw/` directly (dist, src, docs)
- Patch or monkey-patch OpenClaw's runtime code, even for emergencies (exception: the existing TUI patch has a tracked upstream PR — document any new ones immediately)
- Add config keys not documented in OpenClaw's own docs (guessing at undocumented keys can silently break on upgrade)
- Modify `~/.openclaw/openclaw.json` in a way that would be overwritten or invalidated by `openclaw update`
- Introduce any middleware, proxy, or hook that intercepts OpenClaw's internal request path
### ✅ Safe to do
- Edit `~/.openclaw/openclaw.json` using documented config knobs (agents, models, diagnostics, contextPruning, etc.)
- Add/edit workspace files (`~/.openclaw/workspace/`) freely — these are never touched by OpenClaw updates
- Install/update skills via `clawhub` — skills are workspace-local
- Run `openclaw gateway restart` after config changes
- Use `openclaw update status` / `scripts/openclaw-update-safe.sh` to check for upstream updates
### Checking before applying
Before implementing any config change:
1. Verify the key exists in `/home/openclaw/.npm-global/lib/node_modules/openclaw/docs/` or `https://docs.openclaw.ai`
2. If undocumented: skip it or open a question/issue — don't guess
3. After `openclaw update`, re-verify config keys still work (check gateway logs for config parse errors)
### Update workflow
```bash
# Before updating OpenClaw
openclaw update status # check what version is available
# Review changelog for breaking config changes
openclaw update # update (safe scripts handle local compat)
openclaw gateway restart # restart to pick up new version
# Verify gateway health + session model still resolves correctly
```
## What This Does NOT Change
- **No OpenClaw code changes**: Everything is config-only in `openclaw.json`