You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: sync with goclaw d85bf171..fabe86b3 (151 commits) — EN+VI+ZH (#67)
Add Kimi Coding provider + Agent Permission Matrix pages; document agent-scoped git credentials, skill self-evolution, human-like channel delivery, passive channel memory, trace CLI/API, and 11 new DB tables. Regenerate API catalog (362 endpoints) and llms.txt across all locales.
Copy file name to clipboardExpand all lines: advanced/agent-evolution.md
+79-2Lines changed: 79 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -197,6 +197,8 @@ The `skill_manage` tool is available to agents when `skill_evolve=true`. It supp
197
197
|`content`| string | create | Full SKILL.md including YAML frontmatter |
198
198
|`find`| string | patch | Exact text to find in current SKILL.md |
199
199
|`replace`| string | patch | Replacement text |
200
+
|`files`| object | optional (create, patch) | Companion text files keyed by relative path (e.g. `references/guide.md`). Each file is capped at **2 MB**; paths are validated (no `..`, absolute/Windows paths, null bytes, `SKILL.md` overwrite, dotfiles, or system artifacts) |
201
+
|`visibility`| string | optional (patch) | Metadata-only visibility change (`private` or `public`) — updates who can discover the skill without creating a new version when no `content`/`files` change |
**Example — creating a skill with a companion reference file:**
230
+
231
+
```
232
+
skill_manage(
233
+
action="create",
234
+
content="---\nname: Deploy Checklist\ndescription: Steps to deploy the app safely.\n---\n\n## Steps\nSee {baseDir}/references/runbook.md",
235
+
files={"references/runbook.md": "# Runbook\n1. Run tests\n2. Build image\n3. Push to registry"}
236
+
)
237
+
```
238
+
227
239
### publish_skill tool
228
240
229
241
`publish_skill` is an alternative path that registers an entire local directory as a skill. It is always available as a built-in tool toggle (not gated by `skill_evolve`).
@@ -239,7 +251,7 @@ The directory must contain a `SKILL.md` with a `name` in frontmatter. The skill
239
251
||`skill_manage`|`publish_skill`|
240
252
|---|---|---|
241
253
| Input | Content string | Directory path |
242
-
| Files | SKILL.md only (companions copied on patch)| Entire directory (scripts, assets, etc.) |
254
+
| Files | SKILL.md plus direct text companion files (`files=...`); patch copies existing companions forward| Entire directory (scripts, assets, etc.) |
This is a **separate subsystem** from the agent-level "v3 Evolution Metrics" above. Where agent-level evolution tunes an *agent's* parameters, skill self-evolution tracks how each **existing skill** performs over time and proposes improvements to that skill. It is also distinct from the `skill_evolve` learning loop, which teaches an agent *when* to create or patch reusable skills.
428
+
429
+
### Runtime recording
430
+
431
+
Usage is recorded automatically as agents use skills — there is **no public usage endpoint**:
432
+
433
+
-`use_skill` tool calls record tenant-scoped usage with status `succeeded` or `failed`, plus duration, session key, run/trace ID, agent ID, and user scope.
434
+
- Slash-command activation (`/<slug>` or `/use <skill>`) records a `started` event when it resolves to a skill.
435
+
- Usage writes are **internal only**. v1 intentionally has no public `POST /v1/skills/{id}/usage` endpoint, so clients cannot forge success rates.
436
+
437
+
### Persistent tables
438
+
439
+
| Table | Purpose |
440
+
|---|---|
441
+
|`skill_evolution_settings`| Per-tenant, per-skill `enabled` flag and `mode`|
442
+
|`skill_usage_metrics`| Runtime usage events and status counts |
443
+
|`skill_improvement_suggestions`| Skill-scoped suggestions with evidence and draft patches |
444
+
|`skill_versions`| Immutable applied-version records linked to changed files and the originating suggestion |
445
+
446
+
### Modes and statuses
447
+
448
+
| Field | Values | Notes |
449
+
|---|---|---|
450
+
| Settings `mode`|`suggest_only` (default), `auto_analyze`| No automatic *patching* happens in v1 — `auto_analyze` only generates suggestions automatically |
451
+
| Usage `status`|`started`, `succeeded`, `failed`, `abandoned`| Recorded per skill invocation |
452
+
| Suggestion `status`|`pending`, `approved`, `rejected`, `applied`| Lifecycle of an improvement suggestion |
453
+
454
+
### Applying a suggestion
455
+
456
+
Suggestions are reviewed and applied by admins. Applying a suggestion to a **custom** skill:
457
+
458
+
1. Copies the current skill directory forward to the next version.
459
+
2. Validates the target path (same rules as `skill_manage` companion files).
460
+
3. Runs the SKILL.md content guard scanner when SKILL.md changes.
461
+
4. Updates the active skill and records a new `skill_versions` row.
462
+
5. Writes an activity log entry.
463
+
464
+
**System/bundled skill mutation is refused** — the apply path returns `403` for any skill with `is_system = true`, before touching the filesystem.
465
+
466
+
### Admin-gated surfaces
467
+
468
+
Viewer surfaces are sanitized. Failure evidence, draft patches, actor IDs, and activity details require **admin** visibility — non-admins see only aggregate, non-sensitive data.
|`GET`|`/v1/skills/{id}/evolution/suggestions`| List suggestions for the skill |
479
+
|`POST`|`/v1/skills/{id}/evolution/suggestions/{sid}/approve`| Approve a suggestion (tenant admin) |
480
+
|`POST`|`/v1/skills/{id}/evolution/suggestions/{sid}/reject`| Reject a suggestion (tenant admin) |
481
+
|`POST`|`/v1/skills/{id}/evolution/suggestions/{sid}/apply`| Apply an approved suggestion (tenant admin) |
482
+
483
+
The matching CLI commands are `goclaw skills evolve`, `goclaw skills metrics`, `goclaw skills suggestions`, and `goclaw skills activity`. The Dashboard surfaces all of this in the skill detail's **Evolution** tab.
| Patch fails with "not owner" | Agent trying to patch another agent's skill | Each agent can only modify skills it created |
421
495
| Patch fails with "system skill" | Attempting to modify a built-in system skill | System skills are always read-only |
422
496
| Skill content rejected | Content matched a security rule in guard.go | Remove the flagged pattern; see Layer 1 categories above |
497
+
| Companion file rejected by `skill_manage`| Path uses `..`, an absolute/Windows path, a dotfile, or a system artifact; or the file exceeds 2 MB | Use a clean relative path under the skill root and keep each text file under 2 MB |
498
+
| Cannot apply a skill suggestion | Target is a system/bundled skill, or the suggestion is not yet `approved`| System skills are read-only; approve the suggestion first, then apply |
499
+
| Skill metrics show no data | No `use_skill`/slash-command activations recorded yet, or self-evolution disabled | Usage is recorded internally as agents use the skill; enable self-evolution in the skill's Evolution tab |
Copy file name to clipboardExpand all lines: advanced/api-keys-rbac.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,8 @@
6
6
7
7
GoClaw uses a **5-layer permission system**. API keys and roles sit at layer 1 — gateway authentication. When a request arrives, GoClaw checks the `Authorization: Bearer <token>` header, resolves the token to a role, and enforces that role against the method being called.
8
8
9
+
> API keys and tenant RBAC are only the first layer. Agent-config permissions, group/channel scopes, and channel-context credentials are documented in the [Permission Matrix](/permission-matrix).
10
+
9
11
Three roles exist:
10
12
11
13
| Role | Level | Description |
@@ -254,9 +256,10 @@ When a key is created or revoked, a `cache.invalidate` event is broadcast on the
254
256
255
257
## What's Next
256
258
259
+
-[Permission Matrix](/permission-matrix) — agent-config permissions, group/channel scopes, and the full authorization-layer table
257
260
-[Authentication & OAuth](/authentication) — gateway token and OAuth flow
@@ -79,6 +82,48 @@ All API responses return an instance object with credentials masked:
79
82
80
83
---
81
84
85
+
## Instance `config` reference
86
+
87
+
The `config` object holds channel-specific settings. Beyond the per-channel keys documented on each channel page, two cross-channel concerns are worth calling out here.
Channel instances can override the workspace-level [human-like delivery](/channels-overview#human-like-delivery) behavior:
92
+
93
+
| Key | Type | Notes |
94
+
|---|---|---|
95
+
|`chat_behavior`| object | Override `gateway.chat_behavior` for this instance (omit = inherit). Set only the fields you want to change. |
96
+
|`block_reply`| bool |**Legacy.** Read as the inherited default for `intermediate_replies.enabled` when the newer field is unset. |
97
+
98
+
Resolution order is **Channel > Agent > Workspace**:
99
+
100
+
1.**Workspace** — `gateway.chat_behavior` (the base).
101
+
2.**Agent** — `agents.other_config.delivery_behavior` overrides the workspace base.
102
+
3.**Channel** — the instance's `config.chat_behavior` has the final say.
103
+
104
+
Each level only overrides the fields it sets, so you can tune one knob per channel and inherit the rest. Only channels that implement the `ChatBehaviorChannel` interface honor these overrides (Bitrix24, Discord, Feishu/Lark, Pancake, Slack, Telegram, WhatsApp, Zalo OA, Zalo Personal).
105
+
106
+
### Passive channel memory (`passive_memory`)
107
+
108
+
An instance can opt into [passive channel memory extraction](/memory-system#passive-channel-memory-extraction) by adding a `passive_memory` block to its `config`:
109
+
110
+
```json
111
+
{
112
+
"config": {
113
+
"passive_memory": {
114
+
"enabled": true,
115
+
"review_mode": true,
116
+
"interval_minutes": 360,
117
+
"min_messages": 5
118
+
}
119
+
}
120
+
}
121
+
```
122
+
123
+
Disabled by default, group-only in v1, and review-gated. See [Memory System › Passive Channel Memory Extraction](/memory-system#passive-channel-memory-extraction) for the full field table and behavior.
124
+
125
+
---
126
+
82
127
## REST API
83
128
84
129
All endpoints require `Authorization: Bearer <token>`.
|`403` on delete | Instance is a default/seeded instance | Default instances cannot be deleted; disable them with `enabled: false` instead |
272
-
|`400 invalid channel_type`| Typo or unsupported type | Use one of: `telegram`, `discord`, `slack`, `whatsapp`, `zalo_oa`, `zalo_personal`, `feishu`|
317
+
|`400 invalid channel_type`| Typo or unsupported type | Use one of: `telegram`, `discord`, `slack`, `whatsapp`, `zalo_oa`, `zalo_personal`, `feishu`, `bitrix24`, `pancake`, `facebook`|
273
318
| Messages not routing to agent | Instance is disabled or `agent_id` is wrong | Verify `enabled: true` and the correct `agent_id`|
274
319
| Credentials not persisted |`GOCLAW_ENCRYPTION_KEY` not set | Set the encryption key env var; credentials require it |
275
320
| Cache stale after update | In-memory cache not yet refreshed | GoClaw broadcasts a cache-invalidate event on every write; cache refreshes within seconds |
0 commit comments