diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index cdcdae177646..cc409752d832 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -51,6 +51,10 @@ "source": "Secrets management", "target": "密钥管理" }, + { + "source": "SecretRef credential surface", + "target": "SecretRef 凭据覆盖面" + }, { "source": "Secrets runtime model", "target": "密钥运行时模型" @@ -243,6 +247,10 @@ "source": "Gateway protocol", "target": "Gateway 协议" }, + { + "source": "RPC adapters", + "target": "RPC 适配器" + }, { "source": "Gateway RPC methods", "target": "Gateway RPC 方法" @@ -483,6 +491,10 @@ "source": "Getting started", "target": "入门指南" }, + { + "source": "Personal assistant setup", + "target": "个人助理设置" + }, { "source": "Quick start", "target": "快速开始" @@ -635,6 +647,10 @@ "source": "Model providers", "target": "模型提供商" }, + { + "source": "Models FAQ", + "target": "模型常见问题" + }, { "source": "Quick rules", "target": "快速规则" @@ -707,6 +723,18 @@ "source": "VPS hosting", "target": "VPS 托管" }, + { + "source": "Ansible", + "target": "Ansible" + }, + { + "source": "Kubernetes", + "target": "Kubernetes" + }, + { + "source": "Cloudflare Containers", + "target": "Cloudflare Containers" + }, { "source": "Fly.io", "target": "Fly.io" @@ -723,6 +751,10 @@ "source": "Linux server", "target": "Linux 服务器" }, + { + "source": "macOS VMs", + "target": "macOS 虚拟机" + }, { "source": "Platforms", "target": "平台" @@ -771,6 +803,10 @@ "source": "Credits", "target": "致谢" }, + { + "source": "OpenClaw lore", + "target": "OpenClaw 传说" + }, { "source": "Features", "target": "功能" @@ -1147,6 +1183,10 @@ "source": "Release policy", "target": "发布策略" }, + { + "source": "Full release validation", + "target": "完整发布验证" + }, { "source": "Release notes", "target": "发布说明" @@ -1599,6 +1639,10 @@ "source": "Migrating", "target": "迁移" }, + { + "source": "Backups", + "target": "备份" + }, { "source": "Migrating from Hermes", "target": "从 Hermes 迁移" @@ -1611,6 +1655,14 @@ "source": "Agent workspace", "target": "Agent 工作区" }, + { + "source": "Default AGENTS.md", + "target": "默认 AGENTS.md" + }, + { + "source": "Bootstrapping", + "target": "引导初始化" + }, { "source": "Migration", "target": "迁移" @@ -1647,6 +1699,14 @@ "source": "Testing", "target": "测试" }, + { + "source": "Tests", + "target": "测试" + }, + { + "source": "Scripts", + "target": "脚本" + }, { "source": "Update and plugin tests", "target": "更新和插件测试" @@ -1923,6 +1983,10 @@ "source": "Control UI", "target": "Control UI" }, + { + "source": "Hosted embeds", + "target": "托管嵌入" + }, { "source": "Control UI URLs", "target": "Control UI 地址" @@ -2599,6 +2663,10 @@ "source": "Session management", "target": "会话管理" }, + { + "source": "Transcript hygiene", + "target": "转录净化" + }, { "source": "Session tools", "target": "会话工具" diff --git a/docs/auth-credential-semantics.md b/docs/auth-credential-semantics.md index 8ef22fde497b..0be97a613406 100644 --- a/docs/auth-credential-semantics.md +++ b/docs/auth-credential-semantics.md @@ -207,3 +207,4 @@ Human-friendly detail and the stable reason code follow on subsequent lines in t - [Secrets management](/gateway/secrets) - [Auth storage](/concepts/oauth) +- [SecretRef credential surface](/reference/secretref-credential-surface) - which credential fields accept a SecretRef instead of a raw secret value diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index 93de00f90398..790ae20af8bd 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -122,4 +122,10 @@ Every section heading from the previous single-page version keeps its anchor her Full iMessage field reference. + + The line-delimited JSON-RPC stdio protocol OpenClaw speaks to `imsg rpc`. + + + Run OpenClaw in a sandboxed macOS VM, local or hosted, when you want iMessage isolated from your main Mac. + diff --git a/docs/channels/signal.md b/docs/channels/signal.md index 849e4e21c6f3..67bcc6086c41 100644 --- a/docs/channels/signal.md +++ b/docs/channels/signal.md @@ -512,4 +512,5 @@ Related global options: - [Pairing](/channels/pairing) - DM authentication and pairing flow - [Groups](/channels/groups) - group chat behavior and mention gating - [Channel Routing](/channels/channel-routing) - session routing for messages +- [RPC adapters](/reference/rpc) - the signal-cli JSON-RPC-over-HTTP daemon pattern behind this channel - [Security](/gateway/security) - access model and hardening diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md index 1885d2b67ed0..c51dd1c53728 100644 --- a/docs/concepts/agent-workspace.md +++ b/docs/concepts/agent-workspace.md @@ -238,6 +238,9 @@ Suggested `.gitignore` starter: ## Related +- [Backups](/install/backups) - archives, per-database snapshots, scheduling, and offsite copies of state and workspace +- [Bootstrapping](/start/bootstrapping) - the first-run ritual that seeds a new workspace and its identity files +- [Default AGENTS.md](/reference/AGENTS.default) - the default agent instructions and skills roster placed in the workspace - [Heartbeat](/gateway/heartbeat) - heartbeat monitors and cron scratch - [Sandboxing](/gateway/sandboxing) - workspace access in sandboxed environments - [Session](/concepts/session) - session storage paths diff --git a/docs/concepts/context-engine.md b/docs/concepts/context-engine.md index edd9ece8931d..8ba961ea23f4 100644 --- a/docs/concepts/context-engine.md +++ b/docs/concepts/context-engine.md @@ -463,3 +463,4 @@ The slot is exclusive at run time - only one registered context engine is resolv - [Plugin Architecture](/plugins/architecture) - registering context engine plugins - [Plugin manifest](/plugins/manifest) - plugin manifest fields - [Plugins](/tools/plugin) - plugin overview +- [Session management deep dive](/reference/session-management-compaction) - the session store, transcript events, and auto-compaction internals diff --git a/docs/concepts/session-pruning.md b/docs/concepts/session-pruning.md index 919d0557ba6b..a897efcf5e9c 100644 --- a/docs/concepts/session-pruning.md +++ b/docs/concepts/session-pruning.md @@ -155,3 +155,4 @@ They complement each other -- pruning keeps tool output lean between compaction - [Session management](/concepts/session) - [Session tools](/concepts/session-tool) - [Context engine](/concepts/context-engine) +- [Transcript hygiene](/reference/transcript-hygiene) - in-memory, provider-specific transcript sanitization applied before a run diff --git a/docs/concepts/session.md b/docs/concepts/session.md index 1b4f8fb27174..527011493b9c 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -346,5 +346,6 @@ Preview any maintenance run with `openclaw sessions cleanup --dry-run`. - [Session pruning](/concepts/session-pruning) - [Session tools](/concepts/session-tool) +- [Transcript hygiene](/reference/transcript-hygiene) - in-memory, provider-specific transcript sanitization applied before a run - [Command queue](/concepts/queue) - [Multi-agent sandbox and tools](/tools/multi-agent-sandbox-tools) - per-agent sandbox and tool restrictions, including session visibility diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 1ec92a9d57e8..02ab9726d33f 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -175,5 +175,6 @@ _Related: [Configuration Examples](/gateway/configuration-examples) · [Configur - [Gateway runbook](/gateway) - [`openclaw config`](/cli/config) — read and write these settings from the CLI - [`openclaw configure`](/cli/configure) — guided editor for these settings +- [Docker](/install/docker) — container deployment, its environment variables, and the mounted config and state paths - [Security audit checks](/gateway/security/audit-checks) — what the audit flags in this configuration - [Trusted proxy auth](/gateway/trusted-proxy-auth) — configuring the Gateway behind a reverse proxy diff --git a/docs/gateway/sandboxing/podman-backend.md b/docs/gateway/sandboxing/podman-backend.md index c76c4a7c1e76..fc635884bd8f 100644 --- a/docs/gateway/sandboxing/podman-backend.md +++ b/docs/gateway/sandboxing/podman-backend.md @@ -6,6 +6,8 @@ read_when: "You are using Podman instead of Docker for sandboxed tool execution. Selecting the native Podman CLI as a built-in backend, the Docker settings it reuses, and its rootless user-mapping rules. +This page covers Podman as the sandbox backend for agent tool execution. Running the Gateway itself in a rootless Podman container is a separate setup: see [Podman](/install/podman). + ## Podman backend Use `sandbox.backend: "podman"` to select the native `podman` CLI directly. This is a built-in backend, not a plugin. It does not probe or select Docker, even when the `docker` executable is installed. diff --git a/docs/gateway/security/dependency-locking.md b/docs/gateway/security/dependency-locking.md index e155644231d8..12841301090b 100644 --- a/docs/gateway/security/dependency-locking.md +++ b/docs/gateway/security/dependency-locking.md @@ -68,3 +68,7 @@ tar -tf /tmp/openclaw-plugin-pack/openclaw-discord-.tgz | grep -E '^pac ``` The `node_modules` entries prove that the plugin carries its bundled runtime payload. The final check proves that neither npm lockfile format ships in the tarball. + +## Related + +- [Release performance sweep](/reference/release-performance-sweep) - the May 2026 package-size, dependency, and shrinkwrap audit this policy came out of diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md index 96922ea2c415..ef96670c52d8 100644 --- a/docs/help/faq-first-run.md +++ b/docs/help/faq-first-run.md @@ -85,6 +85,7 @@ still resolves. Each entry points at the page that now holds the content. ## Related - [FAQ](/help/faq) - the main FAQ (models, sessions, gateway, security, more) +- [Models FAQ](/help/faq-models) - model defaults, selection, aliases, switching, failover, and auth profiles - [Install overview](/install) - [Getting started](/start/getting-started) - [Troubleshooting](/help/troubleshooting) diff --git a/docs/help/index.md b/docs/help/index.md index 787fb1402af5..3d30ff8bda60 100644 --- a/docs/help/index.md +++ b/docs/help/index.md @@ -31,6 +31,7 @@ Fastest path to unstuck, by symptom: - [Testing](/help/testing) - test suites and Docker runners - [Update and plugin tests](/help/testing-updates-plugins) - package update, migration, and plugin install validation - [Live tests](/help/testing-live) - network-touching provider and CLI smokes +- [Scripts](/help/scripts) - helper scripts under `scripts/` and when to prefer the CLI ## Community and meta diff --git a/docs/help/testing-live.md b/docs/help/testing-live.md index 84083047257d..67c95ffad4b0 100644 --- a/docs/help/testing-live.md +++ b/docs/help/testing-live.md @@ -90,3 +90,4 @@ entry points at the page that now holds the content. ## Related - [Testing](/help/testing) - unit, integration, QA, and Docker suites +- [Tests](/reference/test) - index of the testing reference, one page per reader job diff --git a/docs/help/testing-updates-plugins.md b/docs/help/testing-updates-plugins.md index 5057313345e3..22f0c99d766e 100644 --- a/docs/help/testing-updates-plugins.md +++ b/docs/help/testing-updates-plugins.md @@ -459,3 +459,9 @@ Start with the artifact identity: Prefer rerunning the failed exact lane with the same package artifact over rerunning the whole release umbrella. + +## Related + +- [Tests](/reference/test) - index of the testing reference, one page per reader job +- [Testing](/help/testing) - the full testing kit: suites, live lanes, and Docker runners +- [Release policy](/reference/RELEASING) - the release process this checklist gates diff --git a/docs/install/backups.md b/docs/install/backups.md index 1ddf0073f275..079a9afdf25a 100644 --- a/docs/install/backups.md +++ b/docs/install/backups.md @@ -382,6 +382,7 @@ first with `openclaw database preflight`; see - [Agent workspace](/concepts/agent-workspace#git-backup-recommended-private) for keeping workspace files in a private git repository - [Backup CLI reference](/cli/backup) +- [Cloudflare Containers](/install/cloudflare) — continuous Litestream replication to R2 for an ephemeral container deployment - [Database schemas](/reference/database-schemas) - [Migrating between machines](/install/migrating) - [Updating](/install/updating) diff --git a/docs/install/development-channels.md b/docs/install/development-channels.md index c6719e5074e1..702b0c45ace9 100644 --- a/docs/install/development-channels.md +++ b/docs/install/development-channels.md @@ -199,3 +199,4 @@ Beta and dev builds may **not** include a macOS app release. That is fine: - [Updating](/install/updating) - [Installer internals](/install/installer) +- [Release policy](/reference/RELEASING) - how releases are cut and published into these channels diff --git a/docs/install/docker.md b/docs/install/docker.md index c392f64adaee..fcd998943438 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -350,5 +350,8 @@ docker compose exec openclaw-gateway sh -lc 'node dist/index.js gateway health - - [Install Overview](/install) — all installation methods - [Podman](/install/podman) — Podman alternative to Docker +- [Kubernetes](/install/kubernetes) — a minimal Kustomize starting point for running the Gateway on a cluster +- [Ansible](/install/ansible) — automated server deployment with Tailscale VPN and firewall isolation +- [Cloudflare Containers](/install/cloudflare) — experimental Worker plus container deployment with Litestream backups to R2 - [Updating](/install/updating) — keeping OpenClaw up to date - [Configuration](/gateway/configuration) — gateway configuration after install diff --git a/docs/install/migrating.md b/docs/install/migrating.md index 9cf875dcdf49..a0befd00a60c 100644 --- a/docs/install/migrating.md +++ b/docs/install/migrating.md @@ -148,5 +148,6 @@ In-place plugin upgrades preserve the same plugin id and config keys but may mov - [`openclaw migrate`](/cli/migrate): CLI reference for cross-system imports. - [Install overview](/install): all installation methods. - [Doctor](/gateway/doctor): post-migration health check. +- [Updating](/install/updating): updating an existing install in place, plus rollback strategy. - [Uninstall](/install/uninstall): removing OpenClaw cleanly. - [`openclaw backup`](/cli/backup) — create the archive this migration restores diff --git a/docs/nodes/index.md b/docs/nodes/index.md index b47870c46c35..f8d80c59aa61 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -18,6 +18,9 @@ adds native widget-panel, camera, screen, notification, and computer-control com to the same node-host command surface used by `openclaw node run`. Do not start a second CLI node on that Mac; the app runs the matching CLI node-host runtime as an internal worker and remains the sole Gateway connection and node identity. +The app's **Instances** UI shows each device under a friendly hardware name; see +[Device model database](/reference/device-models) for how Apple model +identifiers are vendored and mapped. Nodes are **peripherals**, not gateways: they don't run the gateway service, and channel messages (Telegram, WhatsApp, etc.) land on the gateway, not on nodes. diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index 2f7b1abffb10..47c010d8007a 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -263,5 +263,6 @@ own docs. - [Platforms](/platforms) - [Getting started](/start/getting-started) +- [Onboarding](/start/onboarding) - the macOS app's first-run flow: where the Gateway runs, runtime install, and connecting a provider - [Gateway](/gateway) - [Exec approvals](/tools/exec-approvals) diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md index ba7d8c08ae88..fd70b754997e 100644 --- a/docs/reference/RELEASING.md +++ b/docs/reference/RELEASING.md @@ -1204,3 +1204,5 @@ Maintainers use the private release docs in [`openclaw/maintainers/release/READM ## Related - [Release channels](/install/development-channels) +- [Full release validation](/reference/full-release-validation) - the release product-validation umbrella and its child workflows +- [Update and plugin tests](/help/testing-updates-plugins) - proving the installable package updates real user state before a release diff --git a/docs/reference/credits.md b/docs/reference/credits.md index e0776f8b28ce..205a0afbe68a 100644 --- a/docs/reference/credits.md +++ b/docs/reference/credits.md @@ -27,5 +27,5 @@ MIT, copyright OpenClaw Foundation. Third-party notices for incorporated or adap ## Related -- [Token use and costs](/reference/token-use) -- [Release policy](/reference/RELEASING) +- [OpenClaw lore](/start/lore) - the backstory behind the name, the shell, and the space lobster +- [Pull request review flow](/reference/pull-request-review-flow) - how a contribution moves through Barnacle and ClawSweeper review diff --git a/docs/reference/rich-output-protocol.md b/docs/reference/rich-output-protocol.md index 7be84e9b04d3..c79bc6d9f47c 100644 --- a/docs/reference/rich-output-protocol.md +++ b/docs/reference/rich-output-protocol.md @@ -101,5 +101,5 @@ The normalized/stored assistant content block is a structured `canvas` item: ## Related -- [RPC adapters](/reference/rpc) +- [Hosted embeds](/web/control-ui/chat#hosted-embeds) - how the Control UI renders `[embed ...]` and its iframe sandbox policy - [Typebox](/concepts/typebox) diff --git a/docs/reference/templates/BOOTSTRAP.md b/docs/reference/templates/BOOTSTRAP.md index 355a7c9118cb..42bb6be40b3b 100644 --- a/docs/reference/templates/BOOTSTRAP.md +++ b/docs/reference/templates/BOOTSTRAP.md @@ -121,3 +121,4 @@ when a `memory/` folder exists. ## Related - [Agent workspace](/concepts/agent-workspace) +- [Bootstrapping](/start/bootstrapping) - the first-run ritual this template drives, and when the file is removed diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 6ec8b293e28d..fdb2203e6d51 100644 --- a/docs/start/getting-started.md +++ b/docs/start/getting-started.md @@ -199,5 +199,6 @@ Full reference: [Environment variables](/help/environment). - [Install overview](/install) - [Channels overview](/channels) - [Setup](/start/setup) +- [Personal assistant setup](/start/openclaw) - end-to-end guide to a dedicated number that behaves like an always-on assistant - [Triage](/cli/triage) - [Troubleshooting](/help/troubleshooting) diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 7ec088a99f40..bbe58aefd73a 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -68,7 +68,7 @@ Use these hubs to discover more of the documentation, including deep dives and r ## Providers + ingress - [Chat channels hub](/channels) -- [Model providers hub](/providers/models) +- [Model providers hub](/providers) - [Discord](/channels/discord) - [iMessage](/channels/imessage) - [Mattermost](/channels/mattermost) diff --git a/docs/vps.md b/docs/vps.md index 2f1aa59fee51..8af566909b9d 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -136,3 +136,6 @@ diagnostics, see [Linux memory pressure and OOM kills](/platforms/linux#memory-p - [DigitalOcean](/install/digitalocean) - [Fly.io](/install/fly) - [Hetzner](/install/hetzner) +- [Ansible](/install/ansible) — automated deployment to remote Debian/Ubuntu servers with Tailscale VPN and firewall isolation +- [Kubernetes](/install/kubernetes) — a minimal Kustomize starting point when you run the Gateway on a cluster instead of a single VPS +- [macOS VMs](/install/macos-vm) — a sandboxed macOS VM when you need macOS itself (iMessage) rather than a Linux host diff --git a/docs/web/control-ui/settings.md b/docs/web/control-ui/settings.md index 4495b1908483..1b665426e996 100644 --- a/docs/web/control-ui/settings.md +++ b/docs/web/control-ui/settings.md @@ -97,6 +97,8 @@ The **Typography** block lets you choose an **Interface** face and a separate ** Appearance also has a Text size setting. It applies to chat text, composer text, tool cards, and chat sidebars, and keeps text inputs at least 16px so mobile Safari does not auto-zoom on focus. +Appearance also carries the **Lobster visits** and **Lobster sounds** toggles and the Lobsterdex. Both toggles are browser-local. See [The Lobster](/web/lobster) for what the sidebar visitor does and how to turn it off for good. + When your connection is bound to an authenticated Gateway profile, theme, theme mode, and accent color are saved to that profile instead of the gateway config. They follow you across devices without changing anyone else's appearance, override gateway-wide `ui.prefs` values, and update your connected clients live. Connections without an authenticated profile continue syncing these preferences through the gateway config exactly as before. Language and chat display preferences remain gateway-config preferences for every connection. Each browser keeps a local mirror for instant boot, and text size remains browser-local. An explicitly read-only connection applies preference changes only in that browser. Changes made while offline remain queued until a later connection can write their applicable preferences; on a read-only reconnect, they continue to behave as browser-local preferences. See [Configuration reference](/gateway/configuration-reference#ui). ## Manage plugins diff --git a/docs/web/lobster.md b/docs/web/lobster.md index 954291c3e4e2..571ea273c665 100644 --- a/docs/web/lobster.md +++ b/docs/web/lobster.md @@ -80,3 +80,9 @@ Collected observations from people who spend too much time watching their sideba ## Privacy Everything on this page happens locally in your browser: the randomness, the schedule, the Lobsterdex. No lobster data leaves your machine. OpenClaw does not know which lobsters you have met, and frankly it is jealous. + +## Related + +- [Control UI](/web/control-ui) - the dashboard the lobster wanders into +- [Settings](/web/control-ui/settings#appearance-themes) - the Control UI Appearance panel that holds the visits and sounds toggles +- [OpenClaw lore](/start/lore) - why there is a lobster at all