docs(rfc): define portable Claw agent settings

Author: giodl73-repo

rfcs/0016-claws.md

@@ -3,7 +3,7 @@ title: Claws
 authors:
   - Gio
 created: 2026-07-03
-last_updated: 2026-07-19
+last_updated: 2026-07-22
 status: draft
 issue:
 rfc_pr: https://github.com/openclaw/rfcs/pull/27
@@ -94,8 +94,10 @@ adopting or merging into an existing agent or managed workspace.
 - Embedding model, provider, thinking-level, authentication, or other
   operator-controlled runtime defaults.
 - Embedding channel account ids, group ids, credentials, or bindings.
-- Setting `agents.list[].skills`; workspace-installed skills remain naturally
-  discoverable and must not replace inherited allowlists.
+- Setting `agents.list[].skills`; package coordinates do not yet provide the
+  canonical skill identities needed to validate an agent allowlist safely.
+  Workspace-installed skills remain naturally discoverable and do not replace
+  inherited allowlists.
 - Defining a generic `connector` installation concept. Channel capabilities are
   supplied by normal channel plugins and configured or bound locally.
 - Defining a feed-backed MCP connector catalog or replacing the Control UI's
@@ -121,6 +123,7 @@ principles.
 | Package identity | Package name and version come from the enclosing package metadata and authenticated publish operation, following the ClawHub plugin precedent. |
 | Operator control | Models, providers, credentials, channel bindings, and local runtime defaults are not portable Claw settings. |
 | Agent configuration | Only explicitly supported portable job settings can be copied into the new `agents.list[]` entry. |
+| Tool policy | A Claw may select a built-in profile registered by the applying OpenClaw version and refine it with portable allow, deny, and workspace-only filesystem policy. Host policy remains authoritative. |
 | Skills | Skill packages install into the new agent's workspace and are discovered normally; the Claw does not set `agent.skills`. |
 | Plugins | Plugin packages use existing plugin installers, safety checks, enablement rules, and install records. |
 | Discovery and composition | Hosted feeds discover and govern plugin and skill packages; a Claw composes exact resolved package versions and direct MCP declarations rather than defining another catalog. |
@@ -231,8 +234,15 @@ The initial public shape is grouped by OpenClaw ownership boundary:
       "workspaceAccess": "rw"
     },
     "tools": {
-      "allow": ["read", "write", "edit", "web_fetch", "memory_search", "memory_get"],
-      "deny": ["exec", "browser", "nodes"]
+      "profile": "coding",
+      "alsoAllow": ["cron"],
+      "deny": ["exec", "browser", "nodes"],
+      "fs": { "workspaceOnly": true }
+    },
+    "memorySearch": {
+      "enabled": true,
+      "rememberAcrossConversations": true,
+      "sources": ["memory", "sessions"]
     },
     "heartbeat": {
       "every": "30m",
@@ -316,9 +326,11 @@ The schema version 1 field set, validation rules, JSON representation, and
 `CLAW.md` envelope are normative for the experimental implementation.
 Implementation slices may land separately behind the experimental gate, but a
 producer or consumer must not claim schema v1 conformance until it implements
-the complete grouped data model. Version 1 is strict: new portable fields,
-semantic changes, and ownership changes require a new schema version so
-existing consumers never interpret or silently discard an unknown declaration.
+the complete grouped data model. This addendum finalizes the experimental v1
+field set before graduation; omitted optional fields retain the prior behavior.
+After v1 graduates, new portable fields, semantic changes, and ownership changes
+require a new schema version so existing consumers never interpret or silently
+discard an unknown declaration.
 
 Unknown fields fail closed. Implementations must not silently drop a declared
 component and still call the agent complete.
@@ -333,7 +345,10 @@ can include:
 - agent identity presentation;
 - group-chat mention patterns;
 - sandbox boundaries;
-- tool allow and deny policy;
+- a built-in tool profile registered by the applying OpenClaw version;
+- tool `allow` or `alsoAllow`, `deny`, and `fs.workspaceOnly` policy;
+- memory-search enablement, explicit cross-conversation memory opt-in, and the
+  portable `memory` and `sessions` sources;
 - heartbeat behavior;
 - human-delay behavior.
 
@@ -344,11 +359,31 @@ The following remain operator controlled and are rejected in a Claw manifest:
 - channel account ids, group ids, and bindings;
 - default-agent selection and global `agents.defaults`;
 - `agent.skills` allowlists;
+- custom tool-profile definitions, provider-specific tool policy, elevated
+  access, executable defaults, and sender-specific policy;
+- memory providers, models, credentials, remote endpoints, local paths, and
+  storage or indexing tuning;
 - arbitrary config fragments or unknown future agent fields.
 
 The generated `agents.list[]` entry inherits operator defaults. Add appends one
 entry and does not rewrite existing list members or defaults.
 
+A profile name is valid only when the applying OpenClaw version resolves it
+through the canonical built-in profile registry. The Claw schema must not copy a
+fixed list of profile names. A Claw carries a profile selection, not a custom
+profile definition. Global and operator policy continue to constrain the
+resulting tool surface and cannot be widened by a Claw.
+
+`tools.allow` is an explicit allowlist. `tools.alsoAllow` extends a selected
+profile, so a single tools object must not contain both. Update preview resolves
+built-in profiles to their effective tool sets before classifying a profile
+change as an escalation or reduction. Enabling memory search, enabling
+`rememberAcrossConversations`, or adding a source is a capability escalation;
+disabling either behavior or removing a source is a reduction. A portable
+declaration of the `sessions` source requires
+`rememberAcrossConversations: true` so it cannot silently normalize to ordinary
+workspace memory.
+
 For example, adding the illustrative manifest above with local agent id
 `github-triage` appends an agent entry while preserving the operator's current
 defaults and agents:
@@ -382,8 +417,15 @@ defaults and agents:
           "workspaceAccess": "rw"
         },
         "tools": {
-          "allow": ["read", "write", "edit", "web_fetch", "memory_search", "memory_get"],
-          "deny": ["exec", "browser", "nodes"]
+          "profile": "coding",
+          "alsoAllow": ["cron"],
+          "deny": ["exec", "browser", "nodes"],
+          "fs": { "workspaceOnly": true }
+        },
+        "memorySearch": {
+          "enabled": true,
+          "rememberAcrossConversations": true,
+          "sources": ["memory", "sessions"]
         },
         "heartbeat": {
           "every": "30m",
@@ -658,6 +700,13 @@ servers, and cron jobs owned by the installed Claw. Local modifications become
 manual conflicts. Operator defaults, models, providers, credentials, bindings,
 and unrelated config remain untouched.
 
+Portable tool-profile changes are compared using the built-in profile registry's
+resolved capabilities rather than opaque profile labels. Tool additions,
+memory-search enablement, cross-conversation memory, and added memory sources
+require distinct capability consent. Restricting filesystem access, disabling
+memory search or cross-conversation memory, or removing sources is reported as a
+reduction. Update compares inherited memory defaults before classification.
+
 Consented update rebuilds the read-only plan immediately before mutation. Each
 owner uses its strongest available concurrency boundary: workspace content
 digests, expected MCP config values, stable cron declaration keys and scheduler
@@ -809,7 +858,7 @@ Implementation should widen the trust boundary in reviewable slices:
 
 ### Current OpenClaw implementation stack
 
-The experimental implementation is one RFC plus twelve ordered OpenClaw PRs. Each
+The experimental implementation is one RFC plus thirteen ordered OpenClaw PRs. Each
 implementation PR is based on the preceding head so reviewers can evaluate one
 ownership boundary at a time:
 
@@ -839,12 +888,17 @@ ownership boundary at a time:
     `CLAW.md` YAML-frontmatter input/export adaptation with grouped JSON read
     compatibility and no separate lifecycle behavior. It supersedes #106888,
     which was merged only into an obsolete stack head.
+13. [#112773](https://github.com/openclaw/openclaw/pull/112773) - registered
+    built-in tool profile selection, portable tool modifiers and filesystem
+    restriction, narrow memory-search behavior, export round trip, and
+    capability-aware updates.
 
 Public documentation follows the same staged boundary as the implementation.
 #101328 introduces the experimental guide, navigation, opt-in, schema, inspect,
 and add preview. Each later PR extends that guide only with the command or
 resource behavior implemented at that stage. #111391 adds only `CLAW.md`
-authoring and canonical export documentation. At every intermediate stack head,
+authoring and canonical export documentation. The final settings slice documents
+only the portable policy fields it implements. At every intermediate stack head,
 the guide must describe no later command or ownership behavior.
 
 These PRs replace the old workspace-apply prototype rather than

rfcs/0016/claw-md-v1-spec.md

@@ -160,15 +160,31 @@ The portable agent object is:
 | `sandbox.mode` | enum | No | `off`, `non-main`, or `all`. |
 | `sandbox.scope` | enum | No | `session`, `agent`, or `shared`. |
 | `sandbox.workspaceAccess` | enum | No | `none`, `ro`, or `rw`. |
-| `tools.allow` | string array | No | At least one non-empty string when present. |
+| `tools.profile` | string | No | Must resolve through the applying OpenClaw version's canonical built-in profile registry. Custom profile definitions are not portable. |
+| `tools.allow` | string array | No | At least one non-empty string when present; mutually exclusive with `tools.alsoAllow`. |
+| `tools.alsoAllow` | string array | No | At least one non-empty string when present; extends a selected profile and is mutually exclusive with `tools.allow`. |
 | `tools.deny` | string array | No | At least one non-empty string when present. |
+| `tools.fs.workspaceOnly` | boolean | No | Restricts filesystem tools to the new agent's workspace. |
+| `memorySearch.enabled` | boolean | No | Enables or disables memory search for the new agent. |
+| `memorySearch.rememberAcrossConversations` | boolean | No | Explicitly permits relevant context from the agent's other private conversations. |
+| `memorySearch.sources` | enum array | No | Non-empty array containing only `memory` and `sessions`; `sessions` requires `rememberAcrossConversations: true`. |
 | `heartbeat` | object | No | Exact portable heartbeat object below. |
 | `humanDelay` | object | No | Exact portable human-delay object below. |
 
 All objects are strict. Consumers may accept empty optional objects, but
 canonical producers must omit an optional object when none of its members are
 present.
 
+These fields map directly to existing per-agent OpenClaw configuration. The
+host's global tool and runtime policy remains authoritative. A Claw cannot carry
+custom profile definitions, provider-specific or sender-specific tool policy,
+elevated access, executable settings, memory providers or credentials, remote
+endpoints, local memory paths, or indexing/storage tuning.
+
+The package `ref` for a skill is not necessarily its canonical runtime skill
+identity. Version 1 therefore does not set `agent.skills`; declared workspace
+skills are discovered normally and inherited operator allowlists remain intact.
+
 `heartbeat` may contain only:
 
 | Field | Type | Constraints |
@@ -341,8 +357,15 @@ agent:
   name: GitHub Triage
   description: Reviews incoming issues and prepares a daily summary.
   tools:
-    allow: [read, write, web_fetch]
+    profile: coding
+    alsoAllow: [cron]
     deny: [exec]
+    fs:
+      workspaceOnly: true
+  memorySearch:
+    enabled: true
+    rememberAcrossConversations: true
+    sources: [memory, sessions]
   heartbeat:
     every: 30m
 workspace:
@@ -395,9 +418,12 @@ of the same schema version, not different capability levels.
 
 ## Compatibility and Evolution
 
-Schema evolution requires a new integer `schemaVersion`. Consumers must reject
-unsupported versions rather than partially apply them. New optional fields must
-not be added to version 1 because strict v1 consumers reject unknown fields.
+This addendum finalizes the experimental schema version 1 field set before
+graduation. Consumers must reject unsupported versions rather than partially
+apply them. After graduation, new optional fields require a new integer
+`schemaVersion` because strict v1 consumers reject unknown fields. Omission of
+the portable tool and memory-search fields preserves existing inherited
+behavior.
 
 There is no canonical byte serialization. Producers should emit stable field
 ordering and formatting for reviewable diffs, but semantic equality is based on
@@ -425,6 +451,9 @@ A conforming consumer must:
 - reject duplicate YAML keys and unknown schema fields;
 - validate all identifiers, exact versions, paths, environment references,
   cron expressions, timezones, and uniqueness constraints;
+- resolve profile names through the canonical built-in profile registry and
+  reject unknown or custom profile names;
+- reject `tools.allow` combined with `tools.alsoAllow`;
 - ignore the Markdown body for runtime behavior;
 - preserve original bytes for integrity calculations;
 - reject a `CLAW.md` file larger than 1 MiB before parsing, including when it
@@ -445,4 +474,5 @@ A conforming producer must:
   timezones;
 - place human explanation, not executable declarations, in the Markdown body;
 - exclude credentials and operator-owned runtime choices;
+- emit only portable per-agent tool and memory-search settings;
 - validate the result against this specification before publication or export.

rfcs/0016/claw-package-v1-spec.md

@@ -286,6 +286,22 @@ human-readable disclosure rather than being hidden in ordinary content
 reconciliation. The same classification applies during add and update; an
 owner must not invent a weaker capability-specific approval.
 
+Portable agent tool profiles are selections from the applying harness's
+canonical built-in registry, not package-defined policy objects. Planning must
+show the selected profile and modifiers. Update planning must resolve built-in
+profiles to tool capabilities before classifying a profile change; it must not
+treat profile labels as opaque. Enabling memory search, enabling
+cross-conversation memory, or adding the `memory` or `sessions` source is an
+escalation. Restricting filesystem tools to the agent workspace, disabling
+memory search or cross-conversation memory, or removing a source is a reduction.
+The `sessions` source requires an explicit cross-conversation memory opt-in.
+Update classification resolves inherited memory defaults before comparison.
+
+The applying host's global policy remains an upper bound. A package must not
+carry custom tool-profile definitions, local credentials or bindings, provider
+configuration, or local memory paths. Unsupported portable settings block the
+complete plan rather than being dropped.
+
 An application profile may satisfy capability and content consent with one
 confirmation only when the plan represents the capability set separately and
 the supplied integrity token binds both sets exactly. A profile may instead
@@ -500,6 +516,12 @@ workspace sources. Export includes only portable supported state and excludes
 secrets, resolved environment values, models, providers, bindings, sessions,
 logs, caches, and unrelated global configuration.
 
+For agent policy, export may preserve a registered built-in tool-profile
+selection, `allow` or `alsoAllow`, `deny`, `fs.workspaceOnly`, and memory-search
+`enabled`, `rememberAcrossConversations`, and `sources`. It must exclude custom
+profile definitions and all other tool or memory-search configuration. The
+exported manifest must pass the same strict validator before being returned.
+
 Export may preserve an original package name and version only by returning the
 byte-for-byte original artifact with the same digest. Any regenerated package,
 including one exported from an unchanged installation, must use a new
@@ -548,6 +570,7 @@ A conforming applying client must:
 - delegate resources to canonical owners and record provenance;
 - fail closed on collisions, unsupported components, and unsafe paths;
 - distinguish applied state from local operational readiness;
+- preserve host policy as the upper bound for portable agent settings;
 - preserve drifted or independently owned state during update and remove;
 - derive managed and referenced relationships from canonical owner state;
 - retain referenced resources by default and bind any operator-selected