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:
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user