Skip to content

Commit f7d7148

Browse files
steipetesteipete
authored
docs: rewrite published docs grounded in current source (#100142)
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
1 parent e069cb2 commit f7d7148

531 files changed

Lines changed: 31841 additions & 41006 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/.generated/config-baseline.sha256‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
88a4b5241395f05e30f84b1f92be9517a64e35efe07a4012e760c160c320aecd config-baseline.json
2-
ef148d059b1b73b3d5ed568bd5cdbf8d4681a41a110341016d2d0318749df064 config-baseline.core.json
3-
3642204f860750da2ce0d43a338f982a206273084bf9afe645ebd759fed0a23a config-baseline.channel.json
4-
e228f29f17758763a098b0ccd10c6db7fc9df84840437ed3f88a88cf945b8078 config-baseline.plugin.json
1+
acdf418738f79d29f58cb6cfe5b7ab2d353cbcce2252861a4f527f85ea0c54af config-baseline.json
2+
4c98c716bc78e65c274ec374757357c1dcc9b5ec75c9e00ea4c20851531b7d1a config-baseline.core.json
3+
c68853362689981ac1cc1e55b9061286c2002104ff1c10bc44ee99a6080e169e config-baseline.channel.json
4+
859aa272b0dad53b7080c6fefcf775347ae79a1998ec39dd18b732c90d9df90c config-baseline.plugin.json

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
c5220c8ccb7c2c57fb62f689bba49fa34a062546bcac909f7d38bba61e99a585 plugin-sdk-api-baseline.json
2-
41ed9c28192c9f9c47de551b854a880225212c441f92e527681462b7fc3a9bab plugin-sdk-api-baseline.jsonl
1+
729181bf726ea51bebfa51c760eff8d5016933c21815e47197b5d05db8d549d5 plugin-sdk-api-baseline.json
2+
d8add92c9c5445e8bdd8a8361cdd5a42e1ab5baa45cd16ea640152d6f577f1bf plugin-sdk-api-baseline.jsonl

‎docs/.i18n/glossary.zh-CN.json‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1230,5 +1230,157 @@
12301230
{
12311231
"source": "Docs map",
12321232
"target": "文档地图"
1233+
},
1234+
{
1235+
"source": "Additional provider variants",
1236+
"target": "其他提供商变体"
1237+
},
1238+
{
1239+
"source": "Agent config reference",
1240+
"target": "Agent 配置参考"
1241+
},
1242+
{
1243+
"source": "Background process",
1244+
"target": "后台进程"
1245+
},
1246+
{
1247+
"source": "Channel outbound API",
1248+
"target": "渠道出站 API"
1249+
},
1250+
{
1251+
"source": "Channel routing",
1252+
"target": "渠道路由"
1253+
},
1254+
{
1255+
"source": "Channels Overview",
1256+
"target": "渠道概览"
1257+
},
1258+
{
1259+
"source": "Compaction",
1260+
"target": "压缩"
1261+
},
1262+
{
1263+
"source": "Debugging (--dev)",
1264+
"target": "调试（--dev）"
1265+
},
1266+
{
1267+
"source": "Devices",
1268+
"target": "设备"
1269+
},
1270+
{
1271+
"source": "Gateway CLI",
1272+
"target": "Gateway CLI"
1273+
},
1274+
{
1275+
"source": "Gateway configuration",
1276+
"target": "Gateway 配置"
1277+
},
1278+
{
1279+
"source": "Gmail Pub/Sub integration",
1280+
"target": "Gmail Pub/Sub 集成"
1281+
},
1282+
{
1283+
"source": "Group chats",
1284+
"target": "群聊"
1285+
},
1286+
{
1287+
"source": "Hooks",
1288+
"target": "Hooks"
1289+
},
1290+
{
1291+
"source": "Incident response",
1292+
"target": "事件响应"
1293+
},
1294+
{
1295+
"source": "Logging overview",
1296+
"target": "日志概览"
1297+
},
1298+
{
1299+
"source": "Menu bar",
1300+
"target": "菜单栏"
1301+
},
1302+
{
1303+
"source": "Message Presentation",
1304+
"target": "消息呈现"
1305+
},
1306+
{
1307+
"source": "Models CLI reference",
1308+
"target": "模型 CLI 参考"
1309+
},
1310+
{
1311+
"source": "Network proxy",
1312+
"target": "网络代理"
1313+
},
1314+
{
1315+
"source": "Nodes CLI",
1316+
"target": "节点 CLI"
1317+
},
1318+
{
1319+
"source": "Nodes overview",
1320+
"target": "节点概览"
1321+
},
1322+
{
1323+
"source": "NovitaAI",
1324+
"target": "NovitaAI"
1325+
},
1326+
{
1327+
"source": "Onboard",
1328+
"target": "引导设置"
1329+
},
1330+
{
1331+
"source": "Operator scopes",
1332+
"target": "操作员权限范围"
1333+
},
1334+
{
1335+
"source": "Scheduled tasks vs heartbeat",
1336+
"target": "定时任务与心跳对比"
1337+
},
1338+
{
1339+
"source": "Scheduled tasks: Troubleshooting",
1340+
"target": "定时任务：故障排查"
1341+
},
1342+
{
1343+
"source": "Session config",
1344+
"target": "会话配置"
1345+
},
1346+
{
1347+
"source": "Signal reactions",
1348+
"target": "Signal 表情回应"
1349+
},
1350+
{
1351+
"source": "Task Flow",
1352+
"target": "Task Flow"
1353+
},
1354+
{
1355+
"source": "Telegram reaction notifications",
1356+
"target": "Telegram 表情回应通知"
1357+
},
1358+
{
1359+
"source": "Threat model",
1360+
"target": "威胁模型"
1361+
},
1362+
{
1363+
"source": "Timezones",
1364+
"target": "时区"
1365+
},
1366+
{
1367+
"source": "Troubleshooting",
1368+
"target": "故障排查"
1369+
},
1370+
{
1371+
"source": "Webhooks",
1372+
"target": "Webhooks"
1373+
},
1374+
{
1375+
"source": "WhatsApp reaction level",
1376+
"target": "WhatsApp 表情回应级别"
1377+
},
1378+
{
1379+
"source": "Zalo (official Bot/webhook channel)",
1380+
"target": "Zalo（官方 Bot/webhook 渠道）"
1381+
},
1382+
{
1383+
"source": "Zalo personal channel config",
1384+
"target": "Zalo 个人渠道配置"
12331385
}
12341386
]

‎docs/AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ This directory owns docs authoring, Mintlify link rules, and docs i18n policy.
1515

1616
- For docs, UI copy, and picker lists, order services/providers alphabetically unless the section is explicitly describing runtime order or auto-detection order.
1717
- Keep bundled plugin naming consistent with the repo-wide plugin terminology rules in the root `AGENTS.md`.
18+
- Generated docs, never hand-edit: `docs/plugins/reference/**`, `docs/plugins/reference.md`, and `docs/plugins/plugin-inventory.md` come from `pnpm plugins:inventory:gen`; `docs/docs_map.md` from `pnpm docs:map:gen`; `docs/maturity/**` from `pnpm maturity:render`.
1819

1920
## Internal Docs
2021

‎docs/agent-runtime-architecture.md‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,32 @@
11
---
22
title: "Agent runtime architecture"
3-
summary: "How OpenClaw runs the built-in agent runtime, providers, sessions, tools, and extensions."
3+
summary: "How OpenClaw structures the built-in agent runtime: code layout, boundaries, resource manifests, and runtime selection."
44
---
55

6-
OpenClaw owns the built-in agent runtime directly. The runtime code lives under `src/agents/`, model/provider helpers live under `src/llm/`, and plugin-facing contracts are exposed through `openclaw/plugin-sdk/*` barrels.
6+
OpenClaw owns the built-in agent runtime. Runtime code lives under `src/agents/`, model/provider transport lives under `src/llm/`, and plugin-facing contracts are exposed through `openclaw/plugin-sdk/*` barrels.
77

88
## Runtime Layout
99

10-
- `src/agents/embedded-agent-runner/`: built-in agent attempt loop, provider stream adapters, compaction, model selection, and session wiring.
11-
- `src/agents/sessions/`: session persistence, extension loading, resource discovery, skills, prompts, themes, and TUI-backed tool renderers.
12-
- `packages/agent-core/`: reusable agent core, lower-level harness types, messages, compaction helpers, prompt templates, and tool/session contracts.
13-
- `src/agents/runtime/`: OpenClaw facade for `@openclaw/agent-core` plus local proxy utilities.
14-
- `src/agents/agent-tools*.ts`: OpenClaw-owned tool definitions, schemas, policy, before/after hook adapters, and host edit support.
15-
- `src/agents/agent-hooks/`: built-in runtime hooks such as compaction safeguards and context pruning.
16-
- `src/llm/`: model/provider registry, transport helpers, and provider-specific stream implementations.
10+
| Path | Owns |
11+
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12+
| `src/agents/embedded-agent-runner/` | Built-in attempt loop (`run.ts`, `run/`), model selection and provider normalization (`model*.ts`), per-provider request params (`extra-params.*`), compaction, transcript and session wiring. |
13+
| `src/agents/sessions/` | Session persistence (`session-manager.ts`), resource discovery (`package-manager.ts`, `resource-loader.ts`), in-session `extensions` loading, prompt templates, skills, themes, and TUI-backed tool renderers (`tools/`). |
14+
| `packages/agent-core/` | Reusable agent core (`@openclaw/agent-core`): agent loop, harness types, messages, compaction helpers, prompt templates, skills, and session storage contracts. |
15+
| `src/agents/runtime/` | OpenClaw facade that wires `@openclaw/agent-core` to the plugin SDK LLM runtime and re-exports it plus local proxy utilities. |
16+
| `src/agents/agent-tools*.ts` | OpenClaw-owned tool definitions, parameter schemas, tool policy, before/after tool-call adapters, and host/sandbox edit tools. |
17+
| `src/agents/agent-hooks/` | Built-in runtime hooks: compaction safeguard, compaction instructions, context pruning. |
18+
| `src/agents/harness/` | Harness registry, selection policy, and lifecycle for the built-in and plugin-registered harnesses. |
19+
| `src/llm/` | Model/provider registry, transport helpers, and provider-specific stream implementations (`src/llm/providers/`). |
1720

1821
## Boundaries
1922

20-
Core code calls the built-in runtime through OpenClaw modules and SDK barrels, not through old external agent packages. Plugins use documented `openclaw/plugin-sdk/*` entrypoints and do not import `src/**` internals.
23+
Core calls the built-in runtime through OpenClaw modules and SDK barrels; no external agent framework packages remain. Plugins use documented `openclaw/plugin-sdk/*` entrypoints and do not import `src/**` internals.
2124

22-
`@earendil-works/pi-tui` remains a third-party TUI dependency. It is used as a terminal component toolkit by the local TUI and session renderers; internalizing it would be a separate vendoring effort.
25+
`@earendil-works/pi-tui` remains a third-party dependency: a terminal component toolkit used by the local TUI and session tool renderers. Internalizing it would be a separate vendoring effort.
2326

2427
## Manifests
2528

26-
Resource packages declare OpenClaw resources in package metadata:
29+
Resource packages declare OpenClaw resources in `package.json` metadata. Entries are file paths or globs relative to the package root:
2730

2831
```json
2932
{
@@ -36,11 +39,15 @@ Resource packages declare OpenClaw resources in package metadata:
3639
}
3740
```
3841

39-
The package manager also discovers conventional `extensions/`, `skills/`, `prompts/`, and `themes/` directories.
42+
Resource types not listed in a manifest fall back to discovery of conventional `extensions/`, `skills/`, `prompts/`, and `themes/` directories.
4043

4144
## Runtime Selection
4245

43-
The default built-in runtime id is `openclaw`. Plugin harnesses can register additional runtime ids. `auto` selects a supporting plugin harness when one exists and otherwise uses the built-in OpenClaw runtime.
46+
- The built-in runtime id is `openclaw`. The legacy alias `pi` normalizes to `openclaw`; `codex-app-server` normalizes to `codex`.
47+
- Plugin harnesses register additional runtime ids (for example `codex`).
48+
- Runtime policy is model/provider-scoped `agentRuntime.id` config (model entry wins over provider entry). Unset or `default` resolves to `auto`.
49+
- `auto` selects a registered plugin harness that supports the provider/model, otherwise the built-in OpenClaw runtime.
50+
- The `openai` provider on the official API endpoint defaults to the `codex` harness; custom `baseUrl` values keep their configured behavior.
4451

4552
## Related
4653

‎docs/announcements/bluebubbles-imessage.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,17 @@ title: "BlueBubbles removal and the imsg iMessage path"
99

1010
# BlueBubbles removal and the imsg iMessage path
1111

12-
OpenClaw no longer ships the BlueBubbles channel. iMessage support now runs through the bundled `imessage` plugin, which starts [`imsg`](https://github.com/steipete/imsg) locally or through an SSH wrapper and talks JSON-RPC over stdin/stdout.
12+
OpenClaw no longer ships the BlueBubbles channel. iMessage support runs through the bundled `imessage` plugin: the Gateway spawns [`imsg`](https://github.com/steipete/imsg) as a child process, locally or through an SSH wrapper, and talks JSON-RPC over stdin/stdout. No server, no webhook, no port.
1313

1414
If your config still contains `channels.bluebubbles`, migrate it to `channels.imessage`. The legacy `/channels/bluebubbles` docs URL redirects to [Coming from BlueBubbles](/channels/imessage-from-bluebubbles), which has the full config translation table and cutover checklist.
1515

1616
## What changed
1717

18-
- There is no BlueBubbles HTTP server, webhook route, REST password, or BlueBubbles plugin runtime in the supported OpenClaw iMessage path.
18+
- The supported iMessage path has no BlueBubbles HTTP server, webhook route, REST password, or BlueBubbles plugin runtime.
1919
- OpenClaw reads and watches Messages through `imsg` on the Mac where Messages.app is signed in.
2020
- Basic send, receive, history, and media use the normal `imsg` surfaces and macOS permissions.
21-
- Advanced actions such as threaded replies, tapbacks, edit, unsend, effects, read receipts, typing indicators, and group management require `imsg launch` with the private API bridge available.
22-
- Linux and Windows gateways can still use iMessage by setting `channels.imessage.cliPath` to an SSH wrapper that runs `imsg` on the signed-in Mac.
21+
- Advanced actions (threaded replies, tapbacks, edit, unsend, effects, read receipts, typing indicators, group management) need the private API bridge: run `imsg launch`, which requires SIP disabled.
22+
- Linux and Windows gateways can still use iMessage by pointing `channels.imessage.cliPath` at an SSH wrapper that runs `imsg` on the signed-in Mac.
2323

2424
## What to do
2525

@@ -65,12 +65,12 @@ If your config still contains `channels.bluebubbles`, migrate it to `channels.im
6565

6666
## Migration notes
6767

68-
- `channels.bluebubbles.serverUrl` and `channels.bluebubbles.password` have no iMessage equivalent.
69-
- `channels.bluebubbles.allowFrom`, `groupAllowFrom`, `groups`, `includeAttachments`, attachment roots, media size limits, chunking, and action toggles have iMessage equivalents.
68+
- `channels.bluebubbles.serverUrl` and `channels.bluebubbles.password` have no iMessage equivalent; there is no server to reach or authenticate.
69+
- `allowFrom`, `groupAllowFrom`, `groups`, `includeAttachments`, `attachmentRoots`, `mediaMaxMb`, `textChunkLimit`, and `actions.*` keep their meaning under `channels.imessage`.
7070
- `channels.imessage.includeAttachments` is still off by default. Set it explicitly if you expect inbound photos, voice memos, videos, or files to reach the agent.
71-
- With `groupPolicy: "allowlist"`, copy the old `groups` block, including any `"*"` wildcard entry. Group sender allowlists and the group registry are separate gates.
72-
- ACP bindings that matched `channel: "bluebubbles"` must be changed to `channel: "imessage"`.
73-
- Old BlueBubbles session keys do not become iMessage session keys. Pairing approvals carry over by handle, but conversation history under BlueBubbles session keys does not.
71+
- With `groupPolicy: "allowlist"`, copy the old `groups` block, including any `"*"` wildcard entry. Group sender allowlists and the group registry are separate gates; a `groups` block with entries but no matching `chat_id` (or no `"*"`) drops the message at runtime, and an empty `groups` block logs a startup warning even though sender filtering still lets messages through.
72+
- ACP bindings with `match.channel: "bluebubbles"` must change to `"imessage"`.
73+
- Old BlueBubbles session keys do not become iMessage session keys. Pairing approvals key off sender handles, so copied `allowFrom` entries keep working, but conversation history under BlueBubbles session keys does not carry over.
7474

7575
## See also
7676

0 commit comments

Comments
 (0)