mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 07:40:44 +00:00
docs(plugins): trim skill-workshop headings and collapse example variants; tighten codex-harness guardian explainer
This commit is contained in:
Vincent Koc
@@ -304,44 +304,9 @@ To opt in to Codex guardian-reviewed approvals, set `appServer.mode:
|
||||
}
|
||||
```
|
||||
|
||||
Guardian mode expands to:
|
||||
Guardian is a native Codex approval reviewer. When Codex asks to leave the sandbox, write outside the workspace, or add permissions like network access, Codex routes that approval request to a reviewer subagent instead of a human prompt. The reviewer applies Codex's risk framework and approves or denies the specific request. Use Guardian when you want more guardrails than YOLO mode but still need unattended agents to make progress.
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
codex: {
|
||||
enabled: true,
|
||||
config: {
|
||||
appServer: {
|
||||
mode: "guardian",
|
||||
approvalPolicy: "on-request",
|
||||
approvalsReviewer: "guardian_subagent",
|
||||
sandbox: "workspace-write",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Guardian is a native Codex approval reviewer. When Codex asks to leave the
|
||||
sandbox, write outside the workspace, or add permissions such as network access,
|
||||
Codex routes that approval request to a reviewer subagent instead of a human
|
||||
prompt. The reviewer gathers context and applies Codex's risk framework, then
|
||||
approves or denies the specific request. Guardian is useful when you want more
|
||||
guardrails than YOLO mode but still need unattended agents and heartbeats to
|
||||
make progress.
|
||||
|
||||
The Docker live harness includes a Guardian probe when
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`. It starts the Codex harness in
|
||||
Guardian mode, verifies that a benign escalated shell command is approved, and
|
||||
verifies that a fake-secret upload to an untrusted external destination is
|
||||
denied so the agent asks back for explicit approval.
|
||||
|
||||
The individual policy fields still win over `mode`, so advanced deployments can
|
||||
mix the preset with explicit choices.
|
||||
The `guardian` preset expands to `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"`, and `sandbox: "workspace-write"`. Individual policy fields still override `mode`, so advanced deployments can mix the preset with explicit choices.
|
||||
|
||||
For an already-running app-server, use WebSocket transport:
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Skill Workshop Plugin"
|
||||
title: "Skill Workshop plugin"
|
||||
summary: "Experimental capture of reusable procedures as workspace skills with review, approval, quarantine, and hot skill refresh"
|
||||
read_when:
|
||||
- You want agents to turn corrections or reusable procedures into workspace skills
|
||||
@@ -8,7 +8,7 @@ read_when:
|
||||
- You are deciding whether to enable automatic skill creation
|
||||
---
|
||||
|
||||
# Skill Workshop Plugin
|
||||
# Skill Workshop plugin
|
||||
|
||||
Skill Workshop is **experimental**. It is disabled by default, its capture
|
||||
heuristics and reviewer prompts may change between releases, and automatic
|
||||
@@ -46,7 +46,7 @@ It is not intended for:
|
||||
- secrets, credentials, or hidden prompt text
|
||||
- one-off instructions that will not repeat
|
||||
|
||||
## Default State
|
||||
## Default state
|
||||
|
||||
The bundled plugin is **experimental** and **disabled by default** unless it is
|
||||
explicitly enabled in `plugins.entries.skill-workshop`.
|
||||
@@ -165,18 +165,18 @@ Recommended profiles:
|
||||
}
|
||||
```
|
||||
|
||||
## Capture Paths
|
||||
## Capture paths
|
||||
|
||||
Skill Workshop has three capture paths.
|
||||
|
||||
### Tool Suggestions
|
||||
### Tool suggestions
|
||||
|
||||
The model can call `skill_workshop` directly when it sees a reusable procedure
|
||||
or when the user asks it to save/update a skill.
|
||||
|
||||
This is the most explicit path and works even with `autoCapture: false`.
|
||||
|
||||
### Heuristic Capture
|
||||
### Heuristic capture
|
||||
|
||||
When `autoCapture` is enabled and `reviewMode` is `heuristic` or `hybrid`, the
|
||||
plugin scans successful turns for explicit user correction phrases:
|
||||
@@ -201,7 +201,7 @@ uses topic hints to choose skill names for common workflows:
|
||||
Heuristic capture is intentionally narrow. It is for clear corrections and
|
||||
repeatable process notes, not for general transcript summarization.
|
||||
|
||||
### LLM Reviewer
|
||||
### LLM reviewer
|
||||
|
||||
When `autoCapture` is enabled and `reviewMode` is `llm` or `hybrid`, the plugin
|
||||
runs a compact embedded reviewer after thresholds are reached.
|
||||
@@ -219,13 +219,9 @@ The reviewer has no tools:
|
||||
- `toolsAllow: []`
|
||||
- `disableMessageTool: true`
|
||||
|
||||
It can return:
|
||||
The reviewer returns either `{ "action": "none" }` or one proposal. The `action` field is `create`, `append`, or `replace` — prefer `append`/`replace` when a relevant skill already exists; use `create` only when no existing skill fits.
|
||||
|
||||
```json
|
||||
{ "action": "none" }
|
||||
```
|
||||
|
||||
or one skill proposal:
|
||||
Example `create`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -238,37 +234,9 @@ or one skill proposal:
|
||||
}
|
||||
```
|
||||
|
||||
It can also append to an existing skill:
|
||||
`append` adds `section` + `body`. `replace` swaps `oldText` for `newText` in the named skill.
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "append",
|
||||
"skillName": "qa-scenario-workflow",
|
||||
"title": "QA Scenario Workflow",
|
||||
"reason": "Animated media QA needs reusable checks",
|
||||
"description": "QA scenario workflow.",
|
||||
"section": "Workflow",
|
||||
"body": "- For animated GIF tasks, verify frame count and attribution before passing."
|
||||
}
|
||||
```
|
||||
|
||||
Or replace exact text in an existing skill:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "replace",
|
||||
"skillName": "screenshot-asset-workflow",
|
||||
"title": "Screenshot Asset Workflow",
|
||||
"reason": "Old validation missed image optimization",
|
||||
"oldText": "- Replace the screenshot asset.",
|
||||
"newText": "- Replace the screenshot asset, preserve dimensions, optimize the PNG, and run the relevant validation gate."
|
||||
}
|
||||
```
|
||||
|
||||
Prefer `append` or `replace` when a relevant skill already exists. Use `create`
|
||||
only when no existing skill fits.
|
||||
|
||||
## Proposal Lifecycle
|
||||
## Proposal lifecycle
|
||||
|
||||
Every generated update becomes a proposal with:
|
||||
|
||||
@@ -304,7 +272,7 @@ Pending and quarantined proposals are deduplicated by skill name and change
|
||||
payload. The store keeps the newest pending/quarantined proposals up to
|
||||
`maxPending`.
|
||||
|
||||
## Tool Reference
|
||||
## Tool reference
|
||||
|
||||
The plugin registers one agent tool:
|
||||
|
||||
@@ -377,7 +345,7 @@ Fetch a proposal by id.
|
||||
|
||||
### `suggest`
|
||||
|
||||
Create a proposal. With `approvalPolicy: "pending"`, this queues by default.
|
||||
Create a proposal. With `approvalPolicy: "pending"` (default), this queues instead of writing.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -390,7 +358,8 @@ Create a proposal. With `approvalPolicy: "pending"`, this queues by default.
|
||||
}
|
||||
```
|
||||
|
||||
Force a safe write:
|
||||
<AccordionGroup>
|
||||
<Accordion title="Force a safe write (apply: true)">
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -402,7 +371,9 @@ Force a safe write:
|
||||
}
|
||||
```
|
||||
|
||||
Force pending even in `approvalPolicy: "auto"`:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Force pending under auto policy (apply: false)">
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -414,7 +385,9 @@ Force pending even in `approvalPolicy: "auto"`:
|
||||
}
|
||||
```
|
||||
|
||||
Append to a section:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Append to a named section">
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -426,7 +399,9 @@ Append to a section:
|
||||
}
|
||||
```
|
||||
|
||||
Replace exact text:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Replace exact text">
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -437,6 +412,9 @@ Replace exact text:
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### `apply`
|
||||
|
||||
Apply a pending proposal.
|
||||
@@ -490,7 +468,7 @@ Example:
|
||||
Support files are workspace-scoped, path-checked, byte-limited by
|
||||
`maxSkillBytes`, scanned, and written atomically.
|
||||
|
||||
## Skill Writes
|
||||
## Skill writes
|
||||
|
||||
Skill Workshop writes only under:
|
||||
|
||||
@@ -525,7 +503,7 @@ For `replace`:
|
||||
All writes are atomic and refresh the in-memory skills snapshot immediately, so
|
||||
the new or updated skill can become visible without a Gateway restart.
|
||||
|
||||
## Safety Model
|
||||
## Safety model
|
||||
|
||||
Skill Workshop has a safety scanner on generated `SKILL.md` content and support
|
||||
files.
|
||||
@@ -557,7 +535,7 @@ Quarantined proposals:
|
||||
To recover from a quarantined proposal, create a new safe proposal with the
|
||||
unsafe content removed. Do not edit the store JSON by hand.
|
||||
|
||||
## Prompt Guidance
|
||||
## Prompt guidance
|
||||
|
||||
When enabled, Skill Workshop injects a short prompt section that tells the agent
|
||||
to use `skill_workshop` for durable procedural memory.
|
||||
@@ -578,7 +556,7 @@ The write mode text changes with `approvalPolicy`:
|
||||
- pending mode: queue suggestions; apply only after explicit approval
|
||||
- auto mode: apply safe workspace-skill updates when clearly reusable
|
||||
|
||||
## Costs and Runtime Behavior
|
||||
## Costs and runtime behavior
|
||||
|
||||
Heuristic capture does not call a model.
|
||||
|
||||
@@ -599,7 +577,7 @@ The reviewer:
|
||||
If the reviewer fails, times out, or returns invalid JSON, the plugin logs a
|
||||
warning/debug message and skips that review pass.
|
||||
|
||||
## Operating Patterns
|
||||
## Operating patterns
|
||||
|
||||
Use Skill Workshop when the user says:
|
||||
|
||||
@@ -683,7 +661,7 @@ Relevant logs:
|
||||
- `skill-workshop: reviewer skipped: ...`
|
||||
- `skill-workshop: reviewer found no update`
|
||||
|
||||
## QA Scenarios
|
||||
## QA scenarios
|
||||
|
||||
Repo-backed QA scenarios:
|
||||
|
||||
@@ -711,7 +689,7 @@ pnpm openclaw qa suite \
|
||||
The reviewer scenario is intentionally separate because it enables
|
||||
`reviewMode: "llm"` and exercises the embedded reviewer pass.
|
||||
|
||||
## When Not To Enable Auto Apply
|
||||
## When not to enable auto apply
|
||||
|
||||
Avoid `approvalPolicy: "auto"` when:
|
||||
|
||||
@@ -724,7 +702,7 @@ Avoid `approvalPolicy: "auto"` when:
|
||||
Use pending mode first. Switch to auto mode only after reviewing the kind of
|
||||
skills the agent proposes in that workspace.
|
||||
|
||||
## Related Docs
|
||||
## Related docs
|
||||
|
||||
- [Skills](/tools/skills)
|
||||
- [Plugins](/tools/plugin)
|
||||
|
||||
Reference in New Issue
Block a user