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
| Skill Management | Create, patch, delete, and grant skills |`skill_manage` tool |
14
14
15
15
Both `self_evolve` and `skill_evolve` are disabled by default. Enable them per-agent in **Agent Settings → Config tab**.
16
16
17
17
---
18
18
19
-
## Self-Evolution (SOUL.md)
19
+
## Self-Evolution (SOUL.md + CAPABILITIES.md)
20
20
21
21
### What it does
22
22
23
-
When `self_evolve` is enabled, an agent can update its own `SOUL.md` file during conversation to refine how it communicates. There is no dedicated tool for this — the agent uses the standard `write_file` tool. A context file interceptor ensures only `SOUL.md` is writable; `IDENTITY.md` and `AGENTS.md` remain locked regardless.
23
+
When `self_evolve` is enabled, an agent can update two of its own context files during conversation:
24
+
25
+
-**`SOUL.md`** — to refine communication style (tone, voice, vocabulary, response style)
26
+
-**`CAPABILITIES.md`** — to refine domain expertise, technical skills, and specialized knowledge
27
+
28
+
There is no dedicated tool for this — the agent uses the standard `write_file` tool. A context file interceptor ensures only `SOUL.md` and `CAPABILITIES.md` are writable; `IDENTITY.md` and `AGENTS.md` remain locked regardless.
24
29
25
30
Changes happen incrementally. The agent is guided to update only when it notices clear patterns in user feedback — not on every turn.
26
31
@@ -39,30 +44,20 @@ When `self_evolve=true`, GoClaw injects this guidance into the system prompt (~9
39
44
```
40
45
## Self-Evolution
41
46
42
-
You have self-evolution enabled. You may update your SOUL.md file to
43
-
refine your communication style over time.
44
-
45
-
What you CAN evolve in SOUL.md:
46
-
- Tone, voice, and manner of speaking
47
-
- Response style and formatting preferences
48
-
- Vocabulary and phrasing patterns
49
-
- Interaction patterns based on user feedback
50
-
51
-
What you MUST NOT change:
52
-
- Your name, identity, or contact information
53
-
- Your core purpose or role
54
-
- Any content in IDENTITY.md or AGENTS.md (these remain locked)
55
-
56
-
Make changes incrementally. Only update SOUL.md when you notice clear
57
-
patterns in user feedback or interaction style preferences.
47
+
You may update SOUL.md to refine communication style (tone, voice, vocabulary, response style).
48
+
You may update CAPABILITIES.md to refine domain expertise, technical skills, and specialized knowledge.
49
+
MUST NOT change: name, identity, contact info, core purpose, IDENTITY.md, or AGENTS.md.
50
+
Make changes incrementally based on clear user feedback patterns.
58
51
```
59
52
53
+
> Source: `buildSelfEvolveSection()` in `internal/agent/systemprompt.go`.
54
+
60
55
### Security
61
56
62
57
| Layer | What it enforces |
63
58
|---|---|
64
59
| System prompt guidance | CAN/MUST NOT rules limit scope |
65
-
| Context file interceptor | Validates that only SOUL.md is written |
60
+
| Context file interceptor | Validates that only SOUL.md or CAPABILITIES.md is written |
66
61
| File locking | IDENTITY.md and AGENTS.md are always read-only |
67
62
68
63
---
@@ -332,6 +327,89 @@ Maximum overhead per run with both features enabled: ~305 tokens for skill learn
332
327
333
328
---
334
329
330
+
## v3: Evolution Metrics and Suggestion Engine
331
+
332
+
v3 adds automated, metrics-driven evolution for predefined agents. This operates separately from the manual skill learning loop above.
333
+
334
+
### How It Works
335
+
336
+
```
337
+
Metrics collected during agent runs (7-day rolling window)
|`feedback`| User satisfaction signals | rating, sentiment, effectiveness_score |
356
+
357
+
Metrics aggregate over 7-day rolling windows. At least 100 data points are required before a suggestion can be auto-applied (configurable via `min_data_points` guardrail).
358
+
359
+
### Suggestion Types
360
+
361
+
| Type | Trigger | Recommendation |
362
+
|------|---------|----------------|
363
+
|`low_retrieval_usage`| Avg recall below threshold for 7 days | Lower `retrieval_threshold` by ≤ 0.1 |
364
+
|`tool_failure`| Single tool failure rate > 20% | Review tool config or add fallback |
365
+
|`repeated_tool`| Same tool called 5+ consecutive times | Extract workflow as a skill |
366
+
367
+
Only one pending suggestion of each type per agent exists at a time (duplicate prevention).
368
+
369
+
### Auto-Adapt Guardrails
370
+
371
+
Suggestions can be auto-applied when approved. Guardrails prevent runaway parameter changes:
372
+
373
+
| Guardrail | Default | Purpose |
374
+
|-----------|---------|---------|
375
+
|`max_delta_per_cycle`| 0.1 | Max parameter change per apply cycle |
376
+
|`min_data_points`| 100 | Minimum metrics required before applying |
377
+
|`rollback_on_drop_pct`| 20.0 | Auto-rollback if quality drops >20% after apply |
378
+
|`locked_params`|`[]`| Parameters that cannot be auto-changed |
379
+
380
+
Baseline parameter values are stored in the suggestion's `parameters._baseline` field for rollback.
381
+
382
+
### Evolution Cron
383
+
384
+
Analysis runs on a configurable schedule (default: daily at 02:00). Set via `evolution_cron_schedule` in agent config:
385
+
386
+
```json
387
+
{
388
+
"evolution_enabled": true,
389
+
"evolution_cron_schedule": "every day at 02:00",
390
+
"evolution_guardrails": {
391
+
"max_delta_per_cycle": 0.1,
392
+
"min_data_points": 100,
393
+
"rollback_on_drop_pct": 20.0,
394
+
"locked_params": []
395
+
}
396
+
}
397
+
```
398
+
399
+
Set `evolution_enabled: false` to disable all metrics collection for an agent.
Copy file name to clipboardExpand all lines: advanced/authentication.md
+17-1Lines changed: 17 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,22 @@ This flow is distinct from standard API key providers — it is only needed if y
10
10
11
11
---
12
12
13
+
## OAuth Provider Routing (v3)
14
+
15
+
GoClaw supports routing OAuth tokens to multiple provider types beyond OpenAI/Codex. In v3, the provider type `media` covers services like **Suno** (AI music) and **DashScope** (Alibaba media generation) that use OAuth or session tokens rather than plain API keys.
16
+
17
+
### Media Provider Types
18
+
19
+
| Provider type | Services | Auth method |
20
+
|---------------|----------|-------------|
21
+
|`openai-codex`| ChatGPT via Responses API | OAuth 2.0 PKCE |
22
+
|`suno`| Suno AI music generation | Session token |
23
+
|`dashscope`| Alibaba DashScope (when OAuth-based) | OAuth or API key |
24
+
25
+
Media provider types are registered in the `llm_providers` table with the appropriate `provider_type` value. The gateway resolves the correct token source and refresh logic based on `provider_type` at request time.
26
+
27
+
---
28
+
13
29
## How It Works
14
30
15
31
```mermaid
@@ -195,4 +211,4 @@ source .env.local
195
211
-[Providers Overview](/providers-overview) — all supported LLM providers and how to configure them
196
212
-[Hooks & Quality Gates](/hooks-quality-gates) — add validation to agent outputs
Copy file name to clipboardExpand all lines: advanced/caching.md
+21-1Lines changed: 21 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -70,6 +70,26 @@ Values are serialized as JSON. Pattern deletion uses SCAN with batch size of 100
70
70
71
71
---
72
72
73
+
## Permission Cache
74
+
75
+
GoClaw includes a dedicated `PermissionCache` for hot permission lookups that happen on every request. Unlike the context file caches, the permission cache is always in-memory — it does not use Redis.
76
+
77
+
| Cache | TTL | Key format | What it caches |
78
+
|---|---|---|---|
79
+
|`tenantRole`| 30s |`tenantID:userID`| User's role within a tenant |
80
+
|`agentAccess`| 30s |`agentID:userID`| Whether user can access an agent + their role |
81
+
|`teamAccess`| 30s |`teamID:userID`| Whether user can access a team |
82
+
83
+
**Invalidation via pubsub**: When a user's permissions change (e.g., role update, agent access revoked), GoClaw publishes a `CacheInvalidate` event on the internal bus. The permission cache processes these events:
84
+
85
+
-`CacheKindTenantUsers` — clears all tenant role entries (short TTL makes a full clear acceptable)
86
+
-`CacheKindAgentAccess` — removes all entries for that `agentID` prefix
87
+
-`CacheKindTeamAccess` — removes all entries for that `teamID` prefix
88
+
89
+
Permission changes take effect within 30 seconds at most, with immediate invalidation on write paths.
90
+
91
+
---
92
+
73
93
## Cache Behavior
74
94
75
95
Both backends implement the same interface:
@@ -91,4 +111,4 @@ Both backends implement the same interface:
Each channel instance exposes a runtime health snapshot. GoClaw tracks the current lifecycle state, failure classification, failure counters, and an operator remediation hint.
201
+
202
+
### Health states
203
+
204
+
| State | Meaning |
205
+
|---|---|
206
+
|`registered`| Instance created but not yet started |
207
+
|`starting`| Channel is initializing (connecting to upstream) |
208
+
|`healthy`| Channel is running and accepting messages |
209
+
|`degraded`| Channel is running but experiencing issues |
210
+
|`failed`| Channel failed to start or crashed |
211
+
|`stopped`| Channel was intentionally stopped |
212
+
213
+
### Failure classification
214
+
215
+
When a channel enters `failed` or `degraded` state, GoClaw classifies the error into one of four kinds:
216
+
217
+
| Kind | Examples | Retryable |
218
+
|---|---|---|
219
+
|`auth`| 401 Unauthorized, invalid token | No |
220
+
|`config`| Missing credentials, invalid proxy URL, agent not found | No |
221
+
|`network`| Timeout, connection refused, DNS failure, EOF | Yes |
222
+
|`unknown`| Unexpected errors | Yes |
223
+
224
+
### Remediation hints
225
+
226
+
Each failed channel includes a `remediation` object with a `code`, `headline`, and `hint` pointing to the relevant UI surface (`credentials`, `advanced`, `reauth`, or `details`). For example, a Zalo Personal auth failure suggests re-opening the sign-in flow rather than checking credentials.
227
+
228
+
Health data is available in the channel instance detail view in the Web UI and via the `GET /v1/channels/instances/{id}` endpoint.
229
+
230
+
---
231
+
198
232
## Group file writers
199
233
200
234
Each channel instance exposes writer-management endpoints that delegate to its bound agent. Writers control who can upload files through the group file feature.
0 commit comments