zhi
5a8f490cc2
Plugin development reference and workflows based on real development experience (Dirigent, ContractorAgent, PrismFacet). Docs: structure, entry-point, hooks, tools, state, config, debugging Workflows: create-plugin, add-hook Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
62 lines
1.6 KiB
Markdown
62 lines
1.6 KiB
Markdown
# Config Schema & Install Scripts
|
|
|
|
## openclaw.plugin.json
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://openclaw.ai/schemas/plugin-config.json",
|
|
"configSchema": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"myToken": { "type": "string" },
|
|
"myFlag": { "type": "boolean", "default": false }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Rules
|
|
|
|
- `additionalProperties: false` is mandatory — OpenClaw validates config against schema
|
|
- Removing a config field requires removing it from schema too (or gateway fails to start)
|
|
- Sensitive fields (tokens, keys): no `default`, user must configure manually
|
|
|
|
## Install Script (scripts/install.mjs)
|
|
|
|
### Install does:
|
|
|
|
1. Build dist (compile TypeScript)
|
|
2. Clean and copy to `~/.openclaw/plugins/<id>/`
|
|
3. Update `openclaw.json`:
|
|
- Add to `plugins.allow`
|
|
- Add to `plugins.load.paths`
|
|
- Set `plugins.entries.<id>.enabled = true`
|
|
- Set default config via `setIfMissing` (never overwrite existing values)
|
|
4. Never set sensitive fields (tokens) — add comments for manual configuration
|
|
|
|
### Uninstall does:
|
|
|
|
1. Remove from `plugins.allow`
|
|
2. Delete `plugins.entries.<id>`
|
|
3. Remove from `plugins.load.paths`
|
|
4. Delete install directory
|
|
|
|
### setIfMissing pattern
|
|
|
|
```javascript
|
|
function setIfMissing(obj, key, value) {
|
|
if (obj[key] === undefined || obj[key] === null) {
|
|
obj[key] = value;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Config field changes
|
|
|
|
When renaming or removing config fields:
|
|
1. Update `openclaw.plugin.json` schema first (source of truth)
|
|
2. Update `normalizeConfig()` in index.ts
|
|
3. Update install script `setIfMissing` calls
|
|
4. Document migration steps for users
|