Skip to content

Commit c314391

Browse files
mcaxtrmcaxtr
committed
docs(plugins): document fallback opt-out flow
1 parent 088261b commit c314391

2 files changed

Lines changed: 85 additions & 0 deletions

File tree

‎docs/plugins/manifest.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -748,6 +748,53 @@ checks that run before channel runtime loads. Bundled channels can also publish
748748
the same defaults through `package.json#openclaw.channel.commands` alongside
749749
their other package-owned channel catalog metadata.
750750

751+
Channel packages can also publish `package.json#openclaw.channel.doctorCapabilities`
752+
for read-only doctor and transition checks. These fields are metadata, not user
753+
config. When a channel sets one fallback flag to `false`, `openclaw doctor --fix`
754+
infers the matching preservation copy from existing DM `allowFrom` entries to the
755+
canonical explicit allowlist.
756+
757+
Valid fallback metadata fields are:
758+
759+
| Field | Values |
760+
| ------------------------------------------ | --------- |
761+
| `groupAllowFromFallbackToAllowFrom` | `boolean` |
762+
| `groupOwnerAllowFromFallbackToAllowFrom` | `boolean` |
763+
| `commandGroupAllowFromFallbackToAllowFrom` | `boolean` |
764+
| `commandAllowFromFallbackToAllowFrom` | `boolean` |
765+
| `elevatedAllowFromFallbackToAllowFrom` | `boolean` |
766+
767+
### Disable fallback in a channel PR
768+
769+
Channel follow-up PRs should disable one fallback family only after the channel
770+
runtime consumes the matching explicit allowlist. The metadata and runtime flag
771+
must move together: setting only metadata makes doctor guidance wrong, and
772+
setting only runtime flags can remove access before `openclaw doctor --fix` can
773+
preserve it.
774+
775+
Use this table as the channel PR checklist:
776+
777+
| Fallback being removed | Runtime change in the channel | Doctor capability metadata | Doctor copy target |
778+
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | --------------------------------------- |
779+
| Normal group sender access falls back from group allowlists to DM `allowFrom` | Pass `policy.groupAllowFromFallbackToAllowFrom: false` to the shared ingress resolver and pass the explicit group sender allowlist the channel will use. | `groupAllowFromFallbackToAllowFrom: false` | `channels.<id>.groupAllowFrom` |
780+
| Group command senders fall back to DM or group sender allowlists | Pass `command.commandGroupAllowFromFallbackToAllowFrom: false` and pass `command.commandGroupAllowFrom` when the channel has a command-specific sender allowlist. | `commandGroupAllowFromFallbackToAllowFrom: false` | `channels.<id>.commandGroupAllowFrom` |
781+
| Group command owners fall back to DM `allowFrom` | Pass `command.groupOwnerAllowFromFallbackToAllowFrom: false` and pass `command.groupOwnerAllowFrom` when the channel has a command-owner allowlist. | `groupOwnerAllowFromFallbackToAllowFrom: false` | `channels.<id>.groupOwnerAllowFrom` |
782+
| Text command authorization falls back to channel `allowFrom` | Make command authorization use explicit `commands.allowFrom` entries for this provider and keep the prepared doctor capability available to the auto-reply command path. | `commandAllowFromFallbackToAllowFrom: false` | `commands.allowFrom.<channel-id>` |
783+
| Elevated authorization falls back to channel `allowFrom` | Stop using the channel elevated `allowFromFallback` hook, or let shared elevated auth skip it through the prepared doctor capability. | `elevatedAllowFromFallbackToAllowFrom: false` | `tools.elevated.allowFrom.<channel-id>` |
784+
785+
Before setting any fallback flag to `false`, verify that:
786+
787+
- the target config key is accepted by that channel schema
788+
- the channel runtime reads that key on the relevant ingress or command path
789+
- `openclaw doctor --fix` can preserve existing access without broadening
790+
account scope
791+
- synthetic open-DM wildcards are not being used as the source of the migration
792+
793+
Command-only migrations must target command-specific allowlists:
794+
`commandGroupAllowFrom`, `groupOwnerAllowFrom`, or provider maps under
795+
`commands.allowFrom` and `tools.elevated.allowFrom`. Do not use normal group
796+
sender targets to preserve command authorization fallback.
797+
751798
```json
752799
{
753800
"channelConfigs": {

‎docs/plugins/sdk-channel-ingress.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,44 @@ Do not precompute effective allowlists, command owners, or command groups. The
5858
resolver derives them from raw allowlists, store callbacks, route descriptors,
5959
access groups, policy, and conversation kind.
6060

61+
`allowFrom` is the direct-message allowlist. For group conversations, pass
62+
explicit non-DM targets when the channel has them:
63+
64+
- `groupAllowFrom` controls normal group sender authorization.
65+
- `command.commandGroupAllowFrom` controls group command senders.
66+
- `command.groupOwnerAllowFrom` controls group command owners.
67+
68+
`groupAllowFromFallbackToAllowFrom` controls only the shared normal group
69+
sender fallback. `command.commandGroupAllowFromFallbackToAllowFrom` is a
70+
separate command-group override; when omitted, it inherits the normal group
71+
fallback flag. `command.groupOwnerAllowFromFallbackToAllowFrom` controls the
72+
legacy group command-owner fallback and defaults to enabled for compatibility.
73+
74+
When a channel disables one of these fallbacks, update the runtime resolver
75+
input and the doctor capability metadata in the same channel PR. Runtime config
76+
loading does not perform this repair; `openclaw doctor --fix` is the only
77+
preservation-copy path.
78+
79+
Use these runtime flags before declaring the matching manifest metadata:
80+
81+
| Fallback family | Runtime input to set | Required explicit input |
82+
| ----------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
83+
| Normal group sender fallback | `policy.groupAllowFromFallbackToAllowFrom: false` | `groupAllowFrom` or a route sender allowlist that replaces the legacy fallback. |
84+
| Group command-sender fallback | `command.commandGroupAllowFromFallbackToAllowFrom: false` | `command.commandGroupAllowFrom`, unless command authorization is intentionally covered by explicit `groupAllowFrom`. |
85+
| Group command-owner fallback | `command.groupOwnerAllowFromFallbackToAllowFrom: false` | `command.groupOwnerAllowFrom`, or an intentional no-owner mode such as the legacy `"none"` sentinel. |
86+
87+
Provider-wide command fallback and elevated fallback are not ingress resolver
88+
inputs. Those paths read prepared channel capability metadata, so the channel PR
89+
must ensure the command or elevated authorization path already has an explicit
90+
target before declaring the fallback disabled.
91+
92+
After the runtime consumes the explicit target, set the corresponding
93+
`package.json#openclaw.channel.doctorCapabilities` fields described in
94+
[Plugin manifest](/plugins/manifest#disable-fallback-in-a-channel-pr). Doctor
95+
infers the copy target from the disabled fallback flag, so channel PRs should
96+
only set the fallback metadata after the target config key is accepted by that
97+
channel schema and read by that channel runtime.
98+
6199
## Result
62100

63101
Bundled plugins should consume modern projections directly:

0 commit comments

Comments
 (0)