mirror of
https://github.com/openclaw/openclaw.git
synced 2026-10-26 10:13:27 +08:00
docs: simplify getting started and provider setup (#168693)
* docs: simplify getting started, installation, and provider setup docs * docs(install): preserve installer step anchors
This commit is contained in:
Dallin Romney authored and GitHub committed
1 parent
6199dfe4fd
commit
c101e1675e
64 files changed
+142
-132
No files matched your search
+3
-3
@@ -98,7 +98,7 @@ must declare their own development dependencies rather than rely on hoisting.
|
||||
- `pnpm test:extension --list` to see valid extension ids
|
||||
- If you changed shared plugin or channel surfaces, run `pnpm test:contracts`
|
||||
- For targeted shared-surface work, use `pnpm test:contracts:channels` or `pnpm test:contracts:plugins`
|
||||
- These commands also cover the shared seam/smoke files that the default unit lane skips
|
||||
- These commands also cover the shared integration/smoke files that the default unit lane skips
|
||||
- For broader runtime changes, select focused tests that cover the touched contracts; PR CI runs the wider lanes (`pnpm test:extensions`, `pnpm test:channels`, or `pnpm test`) before landing
|
||||
- If you touched bundled-plugin boundaries in shared code, run the matching inventories:
|
||||
- `node --import tsx scripts/check-src-extension-import-boundary.mts --json` for `src/**`
|
||||
@@ -109,7 +109,7 @@ must declare their own development dependencies rather than rely on hoisting.
|
||||
- Do not submit refactor-only PRs unless a maintainer explicitly requested that refactor for an active fix or deliverable.
|
||||
- Do not submit test or CI-config fixes for failures already red on `main` CI. If a failure is already visible in the [main branch CI runs](https://github.com/openclaw/openclaw/actions), it's a known issue the Maintainer team is tracking, and a PR that only addresses those failures will be closed automatically. If you spot a _new_ regression not yet shown in main CI, report it as an issue first.
|
||||
- Do not submit test-only PRs that just try to make known `main` CI failures pass. Test changes are acceptable when they are required to validate a new fix or cover new behavior in the same PR.
|
||||
- Ensure CI checks pass
|
||||
- Check that CI checks pass
|
||||
- Keep PRs focused (one thing per PR; do not mix unrelated concerns)
|
||||
- Describe what & why
|
||||
- **Include screenshots** — one showing the problem/before, one showing the fix/after (for UI or visual changes)
|
||||
@@ -282,4 +282,4 @@ For issues that don't fit a specific repo, or if you're unsure, email **security
|
||||
7. **Environment**
|
||||
8. **Remediation Advice**
|
||||
|
||||
Reports without reproduction steps, demonstrated impact, and remediation advice will be deprioritized. Given the volume of AI-generated scanner findings, we must ensure we're receiving vetted reports from researchers who understand the issues.
|
||||
Reports without reproduction steps, demonstrated impact, and remediation advice will be deprioritized. Given the volume of AI-generated scanner findings, we need reports that researchers have checked and understand.
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
OpenClaw is an open-source AI assistant that runs on your own computer and meets you in the channels you already use: Discord, iMessage, Slack, Teams, Telegram, WhatsApp, and 20+ more, plus native apps for macOS, iOS, Android, Windows, and Linux. One Gateway runs it as a personal assistant on a laptop or as a shared [team deployment](https://docs.openclaw.ai/start/teams); configuration is the only difference.
|
||||
|
||||
**Yours, with no catch.** State, memory, and credentials live on your hardware. Models and agent harnesses (Claude, Codex, local models) are plugins you can swap without changing anything else. Your prompts go to the model provider and chat platforms you configure, plus any diagnostics export you enable yourself; by default OpenClaw itself phones home for nothing but a daily version check, anonymous feature statistics are opt-in, and `update.checkOnStart: false` disables both ([what OpenClaw sends](https://docs.openclaw.ai/gateway/telemetry)). OpenClaw is stewarded by the [OpenClaw Foundation](https://openclaw.org), an independent 501(c)(3), and has no paid tier, hosted service, or token. The architecture case — trusted gateway, untrusted execution, deterministic policy — is in [Why OpenClaw](https://docs.openclaw.ai/start/why-openclaw).
|
||||
**Yours, with no catch.** State, memory, and credentials live on your hardware. Models and agent harnesses (Claude, Codex, local models) are plugins you can swap without changing anything else. Your prompts go to the model provider and chat platforms you configure, plus any diagnostics export you enable yourself; by default OpenClaw itself phones home for nothing but a daily version check, anonymous feature statistics are opt-in, and `update.checkOnStart: false` disables both ([what OpenClaw sends](https://docs.openclaw.ai/gateway/telemetry)). OpenClaw is stewarded by the [OpenClaw Foundation](https://openclaw.org), an independent 501(c)(3), and has no paid tier, hosted service, or token. The architecture case — trusted gateway, untrusted execution, policy enforced by code — is in [Why OpenClaw](https://docs.openclaw.ai/start/why-openclaw).
|
||||
|
||||
[Website](https://openclaw.ai) · [Docs](https://docs.openclaw.ai) · [Getting started](https://docs.openclaw.ai/start/getting-started) · [Why OpenClaw](https://docs.openclaw.ai/start/why-openclaw) · [FAQ](https://docs.openclaw.ai/help/faq) · [Vision](VISION.md) · [DeepWiki](https://deepwiki.com/openclaw/openclaw)
|
||||
|
||||
|
||||
+2
-2
@@ -63,7 +63,7 @@ If you are unsure, report privately. We would rather route a careful report than
|
||||
|
||||
- Search existing advisories before filing.
|
||||
- Include likely duplicate GHSA IDs in your report when applicable.
|
||||
- Maintainers may close lower-quality/later duplicates in favor of the earliest high-quality canonical report.
|
||||
- Maintainers may close lower-quality/later duplicates in favor of the earliest high-quality report.
|
||||
|
||||
## Security Posture and Report Rules
|
||||
|
||||
@@ -346,7 +346,7 @@ node --version # Should be v24.16+ or v26.1+
|
||||
|
||||
When running OpenClaw in Docker:
|
||||
|
||||
1. The official image runs as a non-root user (`node`) for reduced attack surface
|
||||
1. The official image runs as a non-root user (`node`) to limit what a compromised process can do
|
||||
2. Use `--read-only` flag when possible for additional filesystem protection
|
||||
3. Limit container capabilities with `--cap-drop=ALL`
|
||||
|
||||
|
||||
@@ -60,7 +60,7 @@ OpenClaw runtime code reads the current configuration schema only.
|
||||
We do not keep long-lived aliases or compatibility branches that silently accept old, renamed, or malformed config keys.
|
||||
|
||||
When a config change makes existing user config invalid, the same change needs a doctor migration.
|
||||
`openclaw doctor --fix` should detect the old shape, explain it, back it up when needed, and rewrite it to the canonical format.
|
||||
`openclaw doctor --fix` should detect the old shape, explain it, back it up when needed, and rewrite it to the current format.
|
||||
Core-owned config and auth state are repaired in core doctor code; plugin-owned config is repaired by that plugin's doctor contract.
|
||||
|
||||
## Security
|
||||
@@ -71,7 +71,7 @@ The goal is to stay powerful for real work while making risky paths explicit and
|
||||
A shared Gateway is for people who trust each other.
|
||||
Mutually untrusted users need separate Gateways, host or container isolation, and access controls.
|
||||
|
||||
Canonical security policy and reporting:
|
||||
Security policy and reporting:
|
||||
|
||||
- [`SECURITY.md`](SECURITY.md)
|
||||
|
||||
@@ -96,7 +96,7 @@ Plugins, skills, channels, and apps carry no such tax, and we want that surface
|
||||
When our contribution rules read as hostile to a feature, re-check the layer: usually they object to where it plugs in, not to the feature existing.
|
||||
|
||||
Recurring demand defines interfaces.
|
||||
Once several independent PRs or requests wire in the same kind of capability, the right response is a contract, not a queue of merges: land the seam in core or the SDK, port the bundled implementation onto it, and let the remaining candidates ship as plugins against it.
|
||||
Once several independent PRs or requests wire in the same kind of capability, the right response is a contract, not a queue of merges: add the shared interface in core or the SDK, update the bundled implementation to use it, and let the remaining candidates ship as plugins against it.
|
||||
|
||||
There are two broad plugin styles:
|
||||
|
||||
|
||||
+1
-1
@@ -102,7 +102,7 @@ OpenClaw is a **self-hosted gateway** that connects your favorite chat apps —
|
||||
- **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing
|
||||
- **Open source**: MIT licensed, community-driven
|
||||
|
||||
The full architecture case — a trusted gateway, untrusted execution, deterministic policy, and how one product spans personal and team use — is in [Why OpenClaw](/start/why-openclaw).
|
||||
The full architecture case — a trusted gateway, untrusted execution, policy enforced by code, and how one product spans personal and team use — is in [Why OpenClaw](/start/why-openclaw).
|
||||
|
||||
**What do you need?** Node 26 (recommended), or another supported release: Node 24.16+ or Node 26.1+. You also need an API key from your chosen provider and 5 minutes. For best quality and security, use the strongest latest-generation model available.
|
||||
|
||||
|
||||
@@ -107,7 +107,7 @@ Four-layer defense model:
|
||||
3. Docker isolation: `DOCKER-USER` iptables chain prevents external port exposure
|
||||
4. Systemd hardening: `NoNewPrivileges`, `PrivateTmp`, unprivileged user
|
||||
|
||||
Verify your external attack surface:
|
||||
Check which ports are publicly reachable:
|
||||
|
||||
```bash
|
||||
nmap -p- YOUR_SERVER_IP
|
||||
@@ -161,7 +161,7 @@ cd openclaw-ansible
|
||||
./run-playbook.sh
|
||||
```
|
||||
|
||||
This is idempotent and safe to run multiple times.
|
||||
You can run this multiple times without duplicating its effects.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -357,7 +357,7 @@ DSN. Restore verifies the matched set and creates a fresh owned PostgreSQL
|
||||
namespace before publishing its anchor. Retain the displaced namespace until
|
||||
recovery is confirmed.
|
||||
|
||||
For SQLite, Git-backed backups dump each selected database into deterministic `schema.sql`,
|
||||
For SQLite, Git-backed backups dump each selected database into consistently ordered `schema.sql`,
|
||||
`manifest.json`, and per-table JSONL files, then create one commit for the
|
||||
whole run. Unchanged database content produces no commit, so Git stores and
|
||||
pushes only content changes by construction. OpenClaw stages only the
|
||||
@@ -515,7 +515,7 @@ into live state or agent roots and has no force or in-place mode. Treat the
|
||||
restored directory as sensitive: it can contain credentials, auth profiles,
|
||||
sessions, and workspace data.
|
||||
|
||||
Before restoring, ensure the target filesystem has room for the archive's full
|
||||
Before restoring, check that the target filesystem has room for the archive's full
|
||||
uncompressed payload, plus extraction overhead, while the live tree remains in
|
||||
place. Renaming or moving the live tree to a sibling path on the same filesystem
|
||||
does not free its blocks; a full restore therefore needs space for a second tree.
|
||||
|
||||
@@ -39,12 +39,12 @@ openclaw update --channel dev
|
||||
config after core update success. A refused or failed core update keeps the
|
||||
previous channel. The selected channel drives both install paths:
|
||||
|
||||
| Channel | npm/package installs | git installs |
|
||||
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | dist-tag `latest` | switches to the npm package at `latest` |
|
||||
| `extended-stable` | resolves the public npm `extended-stable` selector, verifies the exact selected package, and installs that exact version. Fails closed with no fallback to `latest`, `beta`, or `dev`. | unsupported: OpenClaw leaves the checkout unchanged and asks you to use a package installation |
|
||||
| `beta` | dist-tag `beta`, falling back to `latest` when `beta` is missing or older | switches to the npm package at `beta`, falling back to `latest` when beta is missing or older |
|
||||
| `dev` | switches to a Git checkout, builds it, and reinstalls the global CLI | fetches, rebases the checkout on the upstream `main` branch, builds, and reinstalls the global CLI |
|
||||
| Channel | npm/package installs | git installs |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | dist-tag `latest` | switches to the npm package at `latest` |
|
||||
| `extended-stable` | resolves the public npm `extended-stable` selector, verifies the exact selected package, and installs that exact version. Stops on verification errors, with no fallback to `latest`, `beta`, or `dev`. | unsupported: OpenClaw leaves the checkout unchanged and asks you to use a package installation |
|
||||
| `beta` | dist-tag `beta`, falling back to `latest` when `beta` is missing or older | switches to the npm package at `beta`, falling back to `latest` when beta is missing or older |
|
||||
| `dev` | switches to a Git checkout, builds it, and reinstalls the global CLI | fetches, rebases the checkout on the upstream `main` branch, builds, and reinstalls the global CLI |
|
||||
|
||||
An explicit `--channel stable` or `--channel beta` switches a Git installation
|
||||
to a package installation. A bare `openclaw update` in a Git checkout with a
|
||||
|
||||
@@ -290,7 +290,7 @@ Readiness remains false while the default or system agent database is refused,
|
||||
and the readiness response includes the admission reason. A refused optional
|
||||
agent remains isolated while healthy agents can serve requests.
|
||||
|
||||
Missing or drifted canonical SQLite indexes are rebuilt by the schema migration
|
||||
Missing or drifted required SQLite indexes are rebuilt by the schema migration
|
||||
owner before session startup completes. Repair warnings identify the agent,
|
||||
database path, rebuilt indexes, and elapsed time. Current-schema shape refusal
|
||||
reports list all affected databases in stable path order. Missing required tables,
|
||||
|
||||
@@ -112,7 +112,7 @@ Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-inter
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
The browser origin check is fail-closed for public hostnames. The proxy
|
||||
The browser origin check rejects public hostnames that are not allowed. The proxy
|
||||
allowlist lets OpenClaw use nginx's overwritten `X-Forwarded-For` value
|
||||
instead of treating every request as if it originated from the loopback
|
||||
proxy. Keep this list limited to proxies you control.
|
||||
|
||||
+2
-2
@@ -257,7 +257,7 @@ The gateway is binding to `127.0.0.1` instead of `0.0.0.0`.
|
||||
|
||||
Fly cannot reach the gateway on the configured port, or `/startupz` is still reporting startup work.
|
||||
|
||||
**Fix:** ensure `internal_port` matches the gateway port (`--port 3000` or `OPENCLAW_GATEWAY_PORT=3000`), then inspect `fly logs` for the pending startup step.
|
||||
**Fix:** check that `internal_port` matches the gateway port (`--port 3000` or `OPENCLAW_GATEWAY_PORT=3000`), then inspect `fly logs` for the pending startup step.
|
||||
|
||||
### OOM / memory issues
|
||||
|
||||
@@ -323,7 +323,7 @@ fly ssh console --command "rm /data/openclaw.json"
|
||||
|
||||
If you lose auth profiles, channel/provider state, or sessions after a restart, the state dir is writing to the container filesystem instead of the volume.
|
||||
|
||||
**Fix:** ensure `OPENCLAW_STATE_DIR=/data` is set in `fly.toml` and redeploy.
|
||||
**Fix:** set `OPENCLAW_STATE_DIR=/data` in `fly.toml` and redeploy.
|
||||
|
||||
## Updating
|
||||
|
||||
|
||||
+1
-1
@@ -171,7 +171,7 @@ network.
|
||||
gcloud compute os-login describe-profile
|
||||
```
|
||||
|
||||
Ensure your account has Compute OS Login or Compute OS Admin Login permission.
|
||||
Check that your account has Compute OS Login or Compute OS Admin Login permission.
|
||||
|
||||
### Resize after an out-of-memory build
|
||||
|
||||
|
||||
@@ -138,11 +138,14 @@ checks also default to five minutes.
|
||||
<Step title="Detect OS">
|
||||
Supports macOS and Linux (including WSL).
|
||||
</Step>
|
||||
<Step title="Ensure a supported Node.js runtime">
|
||||
<Step title="Install a supported Node.js runtime">
|
||||
<a id="ensure-a-supported-nodejs-runtime" />
|
||||
<a id="ensure-a-supported-node-js-runtime" />
|
||||
Checks the Node version and linked SQLite library, then installs Node if needed (Node 26 through Homebrew `node` on macOS; Node 24 LTS through NodeSource setup scripts on Linux apt/dnf/yum). On RPM-based Linux, a supported distro Node that links unsafe SQLite remains installed while OpenClaw receives a user-space Node runtime. On macOS, Homebrew is installed only when the installer needs it for Node or Git. Node 24.16+ and Node 26.1+ are supported; Node 22, 23, and 25 are unsupported.
|
||||
On Alpine/musl Linux, the installer uses apk packages instead of NodeSource and verifies the actual linked SQLite version. Current stable Alpine package streams can provide a new-enough Node with vulnerable system SQLite; when that happens, use an official `node:26-alpine` container or a glibc-based host instead.
|
||||
</Step>
|
||||
<Step title="Ensure Git">
|
||||
<Step title="Install Git if missing">
|
||||
<a id="ensure-git" />
|
||||
Installs Git if missing using the detected package manager, including Homebrew on macOS and apk on Alpine.
|
||||
</Step>
|
||||
<Step title="Install OpenClaw">
|
||||
@@ -357,7 +360,8 @@ system Node packages.
|
||||
Linux ARMv7 stops before installation because official Node 24+ ARMv7 binaries are unavailable. Use a 64-bit OS on compatible hardware or another supported host.
|
||||
On Alpine/musl Linux, where Node does not publish compatible tarballs for the pinned runtime, installs `nodejs` and `npm` with `apk`, then verifies both Node and the actual linked SQLite library. Current stable Alpine package streams may still link vulnerable SQLite even with a new-enough Node; use an official `node:26-alpine` container or a glibc-based host when the safety check rejects the package.
|
||||
</Step>
|
||||
<Step title="Ensure Git">
|
||||
<Step title="Install Git if missing">
|
||||
<a id="ensure-git-1" />
|
||||
If Git is missing, attempts install via apt/dnf/yum/apk on Linux or Homebrew on macOS.
|
||||
On FreeBSD, install Git with `pkg install git` before retrying.
|
||||
</Step>
|
||||
@@ -494,10 +498,14 @@ its existing service-refresh behavior.
|
||||
### Flow (install.ps1)
|
||||
|
||||
<Steps>
|
||||
<Step title="Ensure PowerShell + Windows environment">
|
||||
<Step title="Check PowerShell and Windows">
|
||||
<a id="ensure-powershell-windows-environment" />
|
||||
<a id="ensure-powershell-%2B-windows-environment" />
|
||||
Requires PowerShell 5+.
|
||||
</Step>
|
||||
<Step title="Ensure a supported Node.js runtime">
|
||||
<Step title="Install a supported Node.js runtime">
|
||||
<a id="ensure-a-supported-nodejs-runtime-1" />
|
||||
<a id="ensure-a-supported-node-js-runtime-1" />
|
||||
If missing, attempts install via winget, then Chocolatey, then Scoop. If those methods are unavailable, fail, or leave an unsupported runtime, the script downloads the official Node.js 26 Windows zip into `%LOCALAPPDATA%\OpenClaw\deps\portable-node` and adds it to the current process and user PATH. Node 24.16+ and Node 26.1+ are supported; Node 22, 23, and 25 are unsupported.
|
||||
</Step>
|
||||
<Step title="Install OpenClaw">
|
||||
|
||||
@@ -236,12 +236,12 @@ For true always-on, consider a dedicated Mac mini or a small VPS. See [VPS hosti
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
| ------------------------ | ----------------------------------------------------------------------------------- |
|
||||
| Cannot SSH into VM | Check "Remote Login" is enabled in the VM's System Settings |
|
||||
| VM IP not showing | Wait for VM to fully boot, run `lume get openclaw` again |
|
||||
| Lume command not found | Add `~/.local/bin` to your PATH |
|
||||
| WhatsApp QR not scanning | Ensure you are logged into the VM (not host) when running `openclaw channels login` |
|
||||
| Problem | Solution |
|
||||
| ------------------------ | --------------------------------------------------------------------------------------- |
|
||||
| Cannot SSH into VM | Check "Remote Login" is enabled in the VM's System Settings |
|
||||
| VM IP not showing | Wait for VM to fully boot, run `lume get openclaw` again |
|
||||
| Lume command not found | Add `~/.local/bin` to your PATH |
|
||||
| WhatsApp QR not scanning | Check that you are logged into the VM (not host) when running `openclaw channels login` |
|
||||
|
||||
## Related docs
|
||||
|
||||
|
||||
@@ -137,7 +137,7 @@ Rerun with `--overwrite` only when replacing the existing target is intentional.
|
||||
|
||||
Conflicts are unusual on a fresh install. They typically show up when you re-run the import against a setup that already has user edits.
|
||||
|
||||
If a conflict surfaces mid-apply (for example, an unexpected race on a config file), that item is reported as a conflict while independent files, skills, credentials, archives, and config entries continue. Resolve the conflicted item and rerun the import; identical memory imports are idempotent.
|
||||
If a conflict surfaces mid-apply (for example, an unexpected race on a config file), that item is reported as a conflict while independent files, skills, credentials, archives, and config entries continue. Resolve the conflicted item and rerun the import; repeating an identical memory import does not create duplicates.
|
||||
|
||||
## Secrets
|
||||
|
||||
|
||||
@@ -122,7 +122,7 @@ awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permissions and ownership">
|
||||
If you copied as root or switched users, the gateway may fail to read credentials. Ensure the state directory and workspace are owned by the user running the gateway.
|
||||
If you copied as root or switched users, the gateway may fail to read credentials. Check that the state directory and workspace are owned by the user running the gateway.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Remote mode">
|
||||
|
||||
+1
-1
@@ -51,7 +51,7 @@ See the [nix-openclaw README](https://github.com/openclaw/nix-openclaw) for full
|
||||
|
||||
## Nix-mode runtime behavior
|
||||
|
||||
When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw), OpenClaw enters a deterministic mode for Nix-managed installs. Other Nix packages can set the same mode; nix-openclaw is the first-party reference.
|
||||
When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw), OpenClaw uses the Nix-managed install mode. Other Nix packages can set the same mode; nix-openclaw is the first-party reference.
|
||||
|
||||
For externally managed config without Nix, use
|
||||
[`OPENCLAW_CONFIG_READONLY=1`](/cli/config#externally-managed-config). It applies
|
||||
|
||||
@@ -96,7 +96,7 @@ Run a persistent OpenClaw Gateway on Oracle Cloud's **Always Free** ARM tier (up
|
||||
systemctl --user restart openclaw-gateway.service
|
||||
```
|
||||
|
||||
`gateway.trustedProxies=["127.0.0.1"]` here is only for the local Tailscale Serve proxy's forwarded-IP/local-client handling. It is **not** `gateway.auth.mode: "trusted-proxy"`. Diff viewer routes keep fail-closed behavior in this setup: raw `127.0.0.1` viewer requests without forwarded proxy headers return `Diff not found`. Use `mode=file` / `mode=both` for attachments, or intentionally enable remote viewers and set `plugins.entries.diffs.config.viewerBaseUrl` (or pass a proxy `baseUrl`) if you need shareable viewer links.
|
||||
`gateway.trustedProxies=["127.0.0.1"]` here is only for the local Tailscale Serve proxy's forwarded-IP/local-client handling. It is **not** `gateway.auth.mode: "trusted-proxy"`. Diff viewer routes still reject requests they cannot verify in this setup: raw `127.0.0.1` viewer requests without forwarded proxy headers return `Diff not found`. Use `mode=file` / `mode=both` for attachments, or intentionally enable remote viewers and set `plugins.entries.diffs.config.viewerBaseUrl` (or pass a proxy `baseUrl`) if you need shareable viewer links.
|
||||
|
||||
</Step>
|
||||
|
||||
|
||||
@@ -208,8 +208,8 @@ openclaw doctor --json
|
||||
|
||||
- **Token generation fails:** Setup and launch stop before saving a generated token or starting the container when the selected random source (`openssl`, Python, or `od`) fails. Repair that command and retry.
|
||||
- **Init executable missing (`lookup init binary` / `container-init binary not found on the host`):** Install `catatonit` on the Podman engine host or repair its configured `init_path`/`helper_binaries_dir` in `containers.conf`, then retry. Installing the helper inside the Gateway or sandbox image does not repair the engine host. Keep `--init` enabled; see [Host init prerequisite](/gateway/sandboxing/podman-backend#host-init-prerequisite).
|
||||
- **Permission denied (EACCES) on config or workspace:** The container runs with `--userns=keep-id` and `--user <your uid>:<your gid>` by default. Ensure the host config/workspace paths are owned by your current user.
|
||||
- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this if missing.
|
||||
- **Permission denied (EACCES) on config or workspace:** The container runs with `--userns=keep-id` and `--user <your uid>:<your gid>` by default. Check that the host config/workspace paths are owned by your current user.
|
||||
- **Gateway start blocked (missing `gateway.mode=local`):** Check that `~/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this if missing.
|
||||
- **Container restarts after an image update:** Run the one-off `openclaw doctor --fix` command in [Upgrading images](#upgrading-images), then start the gateway again.
|
||||
- **Container CLI commands hit the wrong target:** Use `openclaw --container <name> ...` explicitly, or export `OPENCLAW_CONTAINER=<name>` in your shell.
|
||||
- **`openclaw update` fails with `--container`:** Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
|
||||
|
||||
@@ -115,7 +115,7 @@ for the rollback warnings and activation sequence.
|
||||
Check the deploy logs in the Render Dashboard. Common issues:
|
||||
|
||||
- Missing `OPENCLAW_GATEWAY_TOKEN` — verify it is set in **Dashboard → Environment**
|
||||
- Port mismatch — ensure `OPENCLAW_GATEWAY_PORT=8080` so the gateway binds to the port Render expects
|
||||
- Port mismatch — set `OPENCLAW_GATEWAY_PORT=8080` so the gateway binds to the port Render expects
|
||||
|
||||
### Slow cold starts (free tier)
|
||||
|
||||
|
||||
@@ -178,7 +178,7 @@ prefix in the shell. An unrelated installation at that shell prefix does not
|
||||
block an update to the original installation. pnpm global installations retain
|
||||
their pnpm owner and do not use this npm destination check.
|
||||
|
||||
The actual destination must be empty, or its canonical package path must match
|
||||
The actual destination must be empty, or its resolved package path must match
|
||||
the running installation or selected managed service, with any existing launcher
|
||||
pointing inside that package. An inaccessible or unreadable destination stops the
|
||||
update before staging; an unknown destination is never treated as empty. Restore
|
||||
|
||||
@@ -70,7 +70,7 @@ If you already installed the latest version, Doctor stops before rewriting confi
|
||||
that still contains these retired keys and directs you through the same bridge.
|
||||
|
||||
The retired same-file memory index (`meta`, `files`, and `chunks`) is also refused
|
||||
before canonical tables are created. Preserve the original state and configuration,
|
||||
before current tables are created. Preserve the original state and configuration,
|
||||
then use **`2026.9.7`** to migrate a compatible copy of that index before retrying.
|
||||
Unrelated tables with these generic names remain untouched.
|
||||
|
||||
@@ -98,7 +98,7 @@ task, flow, plugin, and channel state you need. Resolve any failed or conflictin
|
||||
imports before continuing. Doctor imports channel state only for enabled channels
|
||||
and accounts. If needed, temporarily enable those channels while the Gateway is
|
||||
stopped, rerun the bridge Doctor, then restore their previous enabled settings.
|
||||
Ensure the affected plugins are installed before running their migrations.
|
||||
Install the affected plugins before running their migrations.
|
||||
Then install the current release and restart:
|
||||
|
||||
```bash
|
||||
@@ -272,7 +272,7 @@ updated package; the published updater and its handoff markers are unchanged.
|
||||
|
||||
The running Gateway retains its shutdown code before an in-place update can
|
||||
replace the package's bundled files. Transcript shutdown drains captures and
|
||||
persists deterministic notes without starting optional model inference. This
|
||||
persists rule-based notes without starting optional model inference. This
|
||||
protection applies to updates **from** a release containing the shutdown fix.
|
||||
Older running Gateways, including 2026.9.6, can still fail their first shutdown
|
||||
with `ERR_MODULE_NOT_FOUND` after package replacement; installing a fixed
|
||||
@@ -514,7 +514,7 @@ its `--timeout` option cannot increase this cap.
|
||||
Plugin rehearsal copies are temporary and rebuilt after interruption. Copying
|
||||
uses up to four concurrent file copies and avoids a disk flush for every file.
|
||||
If a copy fails, active copies finish before cleanup; link publication and
|
||||
verification run only after all file copies succeed. Canonical state and recovery backups
|
||||
verification run only after all file copies succeed. Stored state and recovery backups
|
||||
retain their existing durability guarantees. An older installed updater keeps
|
||||
its initial snapshot behavior until you launch an update from the newer version.
|
||||
|
||||
@@ -802,7 +802,7 @@ for compatibility.
|
||||
`--channel extended-stable` is package-only, and installation remains
|
||||
foreground-only. OpenClaw reads the public npm `extended-stable` selector,
|
||||
verifies the selected exact package, and installs that exact version. Missing
|
||||
or inconsistent registry data fails closed; it never falls back to `latest`.
|
||||
or inconsistent registry data stops the update; it never falls back to `latest`.
|
||||
If the selected version is older than the installed version, the normal
|
||||
downgrade confirmation still applies. The CLI persists the channel after a
|
||||
successful core update; a direct
|
||||
|
||||
@@ -132,7 +132,7 @@ unattended updates.
|
||||
|
||||
| Channel | Behavior |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | After a built-in delay with deterministic jitter for a spread rollout, announces an update campaign. |
|
||||
| `stable` | After a built-in delay with a repeatable offset to spread the rollout, announces an update campaign. |
|
||||
| `extended-stable` | Checks for a read-only update hint on startup and every 24 hours when `checkOnStart` is enabled. Never applies automatically. |
|
||||
| `beta` | Checks on a built-in interval and announces an update campaign as soon as a newer release is available. |
|
||||
| `dev` | With `auto.enabled`, git installs check hourly. When upstream commits are available, the Gateway announces an update campaign pinned to the exact announced commit. |
|
||||
|
||||
@@ -53,7 +53,7 @@ openclaw update --channel dev --dry-run
|
||||
openclaw update --channel stable --dry-run
|
||||
```
|
||||
|
||||
`dev` ensures a git checkout, builds it, and installs the global CLI from that
|
||||
`dev` creates or reuses a git checkout, builds it, and installs the global CLI from that
|
||||
checkout. The `stable`, `extended-stable`, and `beta` channels use package
|
||||
installs. Extended-stable is rejected on a git checkout without mutating or
|
||||
converting it. If the gateway is already installed, `openclaw update` refreshes
|
||||
@@ -460,7 +460,7 @@ intact.
|
||||
bun add -g --trust openclaw@latest
|
||||
```
|
||||
|
||||
`--trust` allows OpenClaw's lifecycle scripts. The canonical `openclaw update`
|
||||
`--trust` allows OpenClaw's lifecycle scripts. The standard `openclaw update`
|
||||
path applies the same OpenClaw-only Bun trust when it owns the install.
|
||||
For Bun-owned updates, package-manager checks and installs use the verified
|
||||
service Bun when updating a managed service root. Otherwise they use
|
||||
|
||||
@@ -14,7 +14,7 @@ Anthropic builds the **Claude** model family. OpenClaw supports two auth routes:
|
||||
## Choose a model route
|
||||
|
||||
The model picker shows each Claude model once per route. API and Claude CLI are
|
||||
not interchangeable billing choices: `anthropic/*` is the canonical model
|
||||
not interchangeable billing choices: `anthropic/*` is the standard model
|
||||
identity and can run through either runtime; `claude-cli/*` selects the native
|
||||
Claude runtime explicitly. When a configured `anthropic/*` model already runs
|
||||
through Claude CLI, the picker omits its matching `claude-cli/*` entry, unless the
|
||||
@@ -130,7 +130,8 @@ OpenClaw release:
|
||||
**Best for:** reusing an existing Claude CLI login without a separate API key.
|
||||
|
||||
<Steps>
|
||||
<Step title="Ensure Claude CLI is installed and logged in">
|
||||
<Step title="Install Claude CLI and log in">
|
||||
<a id="ensure-claude-cli-is-installed-and-logged-in" />
|
||||
OpenClaw communicates directly with the installed Claude Code executable.
|
||||
Verify that Claude Code is installed and up to date:
|
||||
|
||||
@@ -197,7 +198,7 @@ OpenClaw release:
|
||||
the `anthropic` provider require an explicit account selection for CLI
|
||||
forwarding. Existing sessions keep their account until you select another
|
||||
or remove its saved profile. Native-tool approvals remain under OpenClaw
|
||||
control. Schema-valid native calls pass through OpenClaw's canonical
|
||||
control. Schema-valid native calls pass through OpenClaw's shared
|
||||
tool policy before native approval. Isolated side-question completions
|
||||
and paired-node execution retain the supervised CLI path.
|
||||
|
||||
@@ -254,7 +255,7 @@ OpenClaw release:
|
||||
|
||||
### Config example
|
||||
|
||||
Prefer the canonical Anthropic model ref plus a CLI runtime override:
|
||||
Prefer the standard Anthropic model ref plus a CLI runtime override:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -305,7 +306,7 @@ OpenClaw release:
|
||||
|
||||
## Use Claude Opus 5.5
|
||||
|
||||
After setting up either auth route above, select the canonical model ref:
|
||||
After setting up either auth route above, select the standard model ref:
|
||||
|
||||
```bash
|
||||
openclaw models set anthropic/claude-opus-5-5
|
||||
@@ -315,7 +316,7 @@ The bare `opus` alias and explicit aliases `opus-5.5` / `opus-5-5` select this m
|
||||
Fresh API and Claude CLI setup defaults to Opus 5.5; existing version-pinned
|
||||
models and authored aliases remain unchanged.
|
||||
|
||||
For Claude CLI authentication, keep the canonical ref and select the CLI runtime:
|
||||
For Claude CLI authentication, keep the standard ref and select the CLI runtime:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -352,7 +353,7 @@ for model-switching and response-shape changes.
|
||||
|
||||
## Use Claude Sonnet 5.5
|
||||
|
||||
After setting up either auth route above, select the canonical model ref:
|
||||
After setting up either auth route above, select the standard model ref:
|
||||
|
||||
```bash
|
||||
openclaw models set anthropic/claude-sonnet-5-5
|
||||
@@ -363,7 +364,7 @@ this model. Fresh API and Claude CLI setup still defaults to Opus 5.5; select
|
||||
Sonnet 5.5 explicitly. Existing version-pinned models and authored aliases
|
||||
remain unchanged. Use `sonnet-5` to keep Sonnet 5.
|
||||
|
||||
For Claude CLI authentication, keep the canonical ref and select the CLI runtime:
|
||||
For Claude CLI authentication, keep the standard ref and select the CLI runtime:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -410,7 +411,7 @@ for model-switching and response-shape changes.
|
||||
|
||||
## Use Claude Fable 5.1
|
||||
|
||||
After setting up either auth route above, select the canonical model ref:
|
||||
After setting up either auth route above, select the standard model ref:
|
||||
|
||||
```bash
|
||||
openclaw models set anthropic/claude-fable-5-1
|
||||
|
||||
@@ -123,7 +123,7 @@ The onboarding preset sets `arcee/trinity-large-thinking` as the default model.
|
||||
|
||||
## OpenRouter catalog
|
||||
|
||||
OpenRouter onboarding exposes `arcee/trinity-large-preview` and `arcee/trinity-large-thinking`. OpenClaw keeps those provider-qualified model refs in config and sends OpenRouter's canonical `arcee-ai/*` runtime ids. Trinity Mini is no longer served by OpenRouter; use the direct Arcee API for that model.
|
||||
OpenRouter onboarding exposes `arcee/trinity-large-preview` and `arcee/trinity-large-thinking`. OpenClaw keeps those provider-qualified model refs in config and sends OpenRouter's `arcee-ai/*` runtime ids. Trinity Mini is no longer served by OpenRouter; use the direct Arcee API for that model.
|
||||
|
||||
## Supported features
|
||||
|
||||
@@ -143,7 +143,7 @@ OpenRouter onboarding exposes `arcee/trinity-large-preview` and `arcee/trinity-l
|
||||
|
||||
<Accordion title="OpenRouter routing">
|
||||
OpenRouter uses the same `arcee/trinity-large-thinking` OpenClaw model ref.
|
||||
OpenClaw routes it with the canonical `arcee-ai/trinity-large-thinking`
|
||||
OpenClaw routes it with the `arcee-ai/trinity-large-thinking`
|
||||
OpenRouter runtime id. See the
|
||||
[OpenRouter provider docs](/providers/openrouter) for OpenRouter-specific
|
||||
configuration details.
|
||||
|
||||
@@ -80,7 +80,7 @@ up provider credentials on the server.
|
||||
|
||||
## Discovery and pricing
|
||||
|
||||
When Cerebras auth is configured and the inference base URL is the canonical
|
||||
When Cerebras auth is configured and the inference base URL is the official
|
||||
`https://api.cerebras.ai/v1`, OpenClaw reads
|
||||
[`GET /public/v1/models`](https://inference-docs.cerebras.ai/api-reference/models/public-models).
|
||||
This request uses public headers only: inference API keys and discovery
|
||||
|
||||
@@ -72,7 +72,7 @@ you only need an issued ClawRouter key.
|
||||
## Managed non-interactive deployment
|
||||
|
||||
Keep the ClawRouter key in the workload's secret injection and store only a
|
||||
SecretRef in `openclaw.json`. The canonical managed fields are:
|
||||
SecretRef in `openclaw.json`. The managed fields are:
|
||||
|
||||
| Purpose | Config or environment field |
|
||||
| ------------- | ------------------------------------------------------------------------ |
|
||||
@@ -179,12 +179,12 @@ The plugin sends bounded `X-ClawRouter-Client`, `X-ClawRouter-Agent-Id`, and
|
||||
maps the model call's diagnostic `callId` (`<run-id>:model:<n>`) to
|
||||
`X-Request-ID`, so an OpenClaw model-call event can be joined to ClawRouter's
|
||||
metadata-only audit trail. Values within the 128-character request-id budget are
|
||||
identical. Longer values retain the `:model:<n>` suffix and a deterministic
|
||||
identical. Longer values retain the `:model:<n>` suffix and a stable
|
||||
hash so distinct calls remain bounded and joinable. Static deployment metadata
|
||||
such as `X-ClawRouter-Project-Id` can be set in the provider `headers` map.
|
||||
Agent and session attribution headers retain their separate 256-character
|
||||
limit. Automatic request ids containing characters outside ClawRouter's ASCII
|
||||
identifier set use the same deterministic bounded form.
|
||||
identifier set use the same size-limited hash format.
|
||||
Explicit configured headers, including any case variant of `X-Request-ID`, win
|
||||
over automatic values. The transport diagnostic records routing and response
|
||||
metadata; it does not log credentials, request ids, prompts, or completions.
|
||||
@@ -314,7 +314,7 @@ prevent model calls or the existing `/v1/usage` snapshot.
|
||||
- Automatic attribution and request-correlation values are trimmed and control-character rejected before dispatch. Attribution values are bounded to 256 characters; request ids are bounded to 128.
|
||||
- Model transport diagnostics contain metadata only and never include the ClawRouter key or model content.
|
||||
- Native Anthropic and Gemini model ids are rewritten to their upstream ids only at dispatch.
|
||||
- Unsupported or ungranted catalog rows fail closed and are not selectable.
|
||||
- Unsupported or ungranted catalog rows are not selectable.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@@ -113,7 +113,7 @@ openclaw onboard --non-interactive --accept-risk --skip-health \
|
||||
If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process.
|
||||
|
||||
<Warning>
|
||||
A key exported only in an interactive shell will not help a launchd/systemd daemon unless that environment is imported there as well. Set the key in `~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway process can read it.
|
||||
A key exported only in an interactive shell will not help a launchd/systemd daemon unless that environment is imported there as well. Set the key in `~/.openclaw/.env` or via `env.shellEnv` so the gateway process can read it.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
@@ -82,7 +82,7 @@ available to that process (for example, in `~/.openclaw/.env` or via
|
||||
|
||||
| Model ref | Name | Input | Context | Max output | Notes |
|
||||
| --------------------------------------- | --------------------------------------- | ----------- | --------- | ---------- | -------------------------------- |
|
||||
| `deepseek/deepseek-flash` | DeepSeek V4.1 Flash | text, image | 1,000,000 | 384,000 | Canonical Flash model |
|
||||
| `deepseek/deepseek-flash` | DeepSeek V4.1 Flash | text, image | 1,000,000 | 384,000 | Main Flash model |
|
||||
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | Fast V4 thinking-capable surface |
|
||||
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | Onboarding default |
|
||||
| `deepseek/deepseek-v4-flash-vision-exp` | DeepSeek V4 Flash Vision (Experimental) | text, image | 1,000,000 | 384,000 | Experimental image understanding |
|
||||
@@ -93,7 +93,7 @@ DeepSeek retired `deepseek-chat` and `deepseek-reasoner` on July 24, 2026 at
|
||||
to `deepseek/deepseek-v4-flash` or `deepseek/deepseek-v4-pro`.
|
||||
</Warning>
|
||||
|
||||
OpenClaw's local costs are estimates. Canonical Flash uses DeepSeek's peak
|
||||
OpenClaw's local costs are estimates. `deepseek/deepseek-flash` uses DeepSeek's peak
|
||||
rates: $0.30 per million input tokens, $1.20 per million output tokens, and
|
||||
$0.006 per million cached input tokens. Published off-peak rates are half those amounts.
|
||||
Legacy rows retain their earlier bundled metadata. DeepSeek still accepts
|
||||
@@ -105,12 +105,12 @@ authoritative for billing.
|
||||
|
||||
For image inputs, select `deepseek/deepseek-flash`. The legacy
|
||||
`deepseek/deepseek-v4-flash-vision-exp` selection also retains image support.
|
||||
Canonical Flash accepts
|
||||
`deepseek/deepseek-flash` accepts
|
||||
PNG, JPEG, GIF, and WebP images through the same API and API key. See
|
||||
[DeepSeek vision](https://api-docs.deepseek.com/guides/vision) for image limits.
|
||||
|
||||
<Tip>
|
||||
Canonical Flash and V4 models support DeepSeek's `thinking` control. OpenClaw also replays
|
||||
Flash and V4 models support DeepSeek's `thinking` control. OpenClaw also replays
|
||||
DeepSeek `reasoning_content` on follow-up turns so thinking sessions with tool
|
||||
calls can continue.
|
||||
Use `/think xhigh` or `/think max` with DeepSeek V4 models to request DeepSeek's
|
||||
@@ -139,7 +139,7 @@ When thinking is disabled (including the UI **None** selection), OpenClaw
|
||||
sends `thinking: { type: "disabled" }` and strips replayed `reasoning_content`
|
||||
from outgoing history, keeping the session on the non-thinking DeepSeek path.
|
||||
|
||||
Fresh onboarding selects `deepseek/deepseek-v4-pro`. To select canonical Flash:
|
||||
Fresh onboarding selects `deepseek/deepseek-v4-pro`. To select Flash:
|
||||
|
||||
```bash
|
||||
openclaw models set deepseek/deepseek-flash
|
||||
|
||||
@@ -13,7 +13,7 @@ generation.
|
||||
| Property | Value |
|
||||
| -------- | ------------------------------------------------------------------------------- |
|
||||
| Provider | `fal` |
|
||||
| Auth | `FAL_KEY` (canonical; `FAL_API_KEY` also works as a fallback) |
|
||||
| Auth | `FAL_KEY` (preferred; `FAL_API_KEY` also works as a fallback) |
|
||||
| API | fal model endpoints (`https://fal.run`; video jobs use `https://queue.fal.run`) |
|
||||
| Base URL | Override with `models.providers.fal.baseUrl` |
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ Then configure the provider:
|
||||
|
||||
`speakerVoiceId` is optional. Without it, Fish Audio uses its default voice.
|
||||
`FISH_AUDIO_API_KEY` is also accepted for compatibility with existing community
|
||||
plugins, but `FISH_API_KEY` is the canonical Fish SDK environment variable.
|
||||
plugins, but `FISH_API_KEY` is the standard Fish SDK environment variable.
|
||||
|
||||
### Hosted models
|
||||
|
||||
|
||||
@@ -241,7 +241,7 @@ enable or authenticate the provider. Use
|
||||
Fresh non-interactive setup validates the token before saving it. When setup
|
||||
must choose a default, it also checks the live Copilot model catalog. OpenClaw
|
||||
prefers the provider's current general-purpose model when that model is
|
||||
enabled for the account; otherwise it chooses a deterministic eligible fallback.
|
||||
enabled for the account; otherwise it chooses an eligible fallback using a fixed order.
|
||||
Setup fails without writing a new auth profile if the account has no
|
||||
picker-visible model that supports streaming and tool calls. An explicitly
|
||||
configured default model is never replaced.
|
||||
|
||||
@@ -145,7 +145,7 @@ the Gateway already runs inside a managed Google Cloud environment.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI runtime">
|
||||
**Advanced use only:** run a canonical `google/*` model through an installed
|
||||
**Advanced use only:** run a standard `google/*` model through an installed
|
||||
Gemini CLI while keeping authentication on the supported AI Studio API-key
|
||||
path.
|
||||
|
||||
@@ -175,7 +175,7 @@ the Gateway already runs inside a managed Google Cloud environment.
|
||||
common Windows/npm layouts.
|
||||
</Step>
|
||||
<Step title="Select the CLI runtime">
|
||||
Keep the canonical Google model ref and opt that model into the CLI
|
||||
Keep the standard Google model ref and opt that model into the CLI
|
||||
runtime:
|
||||
|
||||
```json5
|
||||
@@ -197,7 +197,7 @@ the Gateway already runs inside a managed Google Cloud environment.
|
||||
|
||||
- Runtime: `google-gemini-cli`
|
||||
- Auth: selected Google AI Studio API-key profile
|
||||
- Model refs: canonical `google/*`
|
||||
- Model refs: `google/*`
|
||||
|
||||
`google-gemini-cli` is the CLI backend the bundled Google plugin registers.
|
||||
See [CLI backends](/gateway/cli-backends) for its argv, JSONL dialect, and
|
||||
@@ -443,7 +443,7 @@ Kore: It is waiting at the maintainer gate.
|
||||
Gemini 3.1 and 2.5 preview TTS still use `generateContent`. Those models keep
|
||||
the older behavior: `audioProfile` is prepended to the transcript, and
|
||||
expressive tags use square brackets such as `[whispers]`. An unknown
|
||||
`gemini-3.8-*-tts` id fails closed instead of being sent to `generateContent`.
|
||||
`gemini-3.8-*-tts` id is rejected instead of being sent to `generateContent`.
|
||||
|
||||
For lowest-latency spoken conversations, use the Google realtime voice provider
|
||||
backed by the Gemini Live API instead of batch TTS.
|
||||
|
||||
@@ -107,7 +107,7 @@ Any model on the gateway is addressable as `kilocode/<upstream-id>` (for example
|
||||
<Accordion title="Troubleshooting">
|
||||
- If model discovery fails, OpenClaw reports an unavailable catalog refresh. It does not replace the failed request with static rows or turn an empty response into `kilocode/kilo-auto/balanced`.
|
||||
- Confirm your API key is valid and that your Kilo account has the desired models enabled.
|
||||
- When Gateway runs as a daemon, ensure `KILOCODE_API_KEY` is available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
|
||||
- When Gateway runs as a daemon, make `KILOCODE_API_KEY` available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -149,7 +149,7 @@ binary shape to the six-level scale before sending requests, including for older
|
||||
still has `off`/`on` reasoning maps.
|
||||
|
||||
For graded options, fresh discovery maps `max` (and Ultra's provider effort) to the highest
|
||||
advertised canonical effort, regardless of option order. For example, `off`, `low`, `medium`
|
||||
advertised standard effort level, regardless of option order. For example, `off`, `low`, `medium`
|
||||
maps `max` to `medium`. Existing saved graded `reasoningEffortMap` values remain explicit
|
||||
configuration; rerun LM Studio setup to regenerate them from current server metadata.
|
||||
|
||||
@@ -185,7 +185,7 @@ configuration; rerun LM Studio setup to regenerate them from current server meta
|
||||
With preload enabled, OpenClaw routes chat requests to a loaded instance with
|
||||
enough context for the selected model budget. A newly loaded instance is addressed by the
|
||||
identifier returned by LM Studio. Your configured model reference and conversation model identity
|
||||
keep the canonical model key.
|
||||
keep the configured model key.
|
||||
|
||||
Model loads use the configured provider `timeoutSeconds` (or the request timeout override),
|
||||
with a two-minute default matching embedding loads. Increase `models.providers.lmstudio.timeoutSeconds`
|
||||
@@ -196,7 +196,7 @@ Wait for loading to finish in LM Studio and retry, or lower the model's `context
|
||||
With preload enabled, embedding requests also check that their model is loaded and route to the
|
||||
instance prepared for the configured context length. This avoids truncating input through a smaller
|
||||
loaded instance and lets memory embeddings recover after model eviction even when LM Studio JIT
|
||||
loading is disabled. Embedding model and cache identity keep the canonical model key.
|
||||
loading is disabled. Embedding model and cache identity keep the configured model key.
|
||||
|
||||
### Disabling preload
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@ For the full provider catalog and advanced configuration, see
|
||||
|
||||
- `anthropic-vertex` - install `@openclaw/anthropic-vertex-provider` for implicit Anthropic on Google Vertex support. That support applies when Vertex credentials are available. There is no separate onboarding auth choice.
|
||||
- `copilot-proxy` - local VS Code Copilot Proxy bridge. Use `openclaw onboard --auth-choice copilot-proxy`.
|
||||
- `google-gemini-cli` - optional explicit runtime for canonical `google/*` models. It requires a local `gemini` install and a supported Google AI Studio API-key profile. New Gemini CLI or Antigravity OAuth setup is not offered.
|
||||
- `google-gemini-cli` - optional explicit runtime for standard `google/*` models. It requires a local `gemini` install and a supported Google AI Studio API-key profile. New Gemini CLI or Antigravity OAuth setup is not offered.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@@ -430,7 +430,7 @@ at $0.30 per million tokens. See
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tool call id sanitization">
|
||||
Moonshot Kimi serves native tool_call ids shaped like `functions.<name>:<index>`. OpenClaw preserves the first occurrence of each native Kimi id and rewrites later duplicates to deterministic OpenAI-style `call_*` ids. Matching tool results are remapped with the same id so replay remains unique without stripping Kimi's first native id. This behavior is wired into the bundled Moonshot provider and is not a user-configurable setting.
|
||||
Moonshot Kimi serves native tool_call ids shaped like `functions.<name>:<index>`. OpenClaw preserves the first occurrence of each native Kimi id and rewrites later duplicates to stable OpenAI-style `call_*` ids. Matching tool results are remapped with the same id so replay remains unique without stripping Kimi's first native id. This behavior is wired into the bundled Moonshot provider and is not a user-configurable setting.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Streaming usage compatibility">
|
||||
|
||||
@@ -24,7 +24,7 @@ cloud routing separate from the local `ollama` provider.
|
||||
Do not use the `/v1` OpenAI-compatible URL (`http://host:11434/v1`). It breaks tool calling and models can emit raw tool-call JSON as plain text. Use the native URL: `baseUrl: "http://host:11434"` (no `/v1`).
|
||||
</Warning>
|
||||
|
||||
The canonical config key is `baseUrl`. `baseURL` is also accepted for
|
||||
The current config key is `baseUrl`. `baseURL` is also accepted for
|
||||
OpenAI-SDK-style examples, but new config should use `baseUrl`.
|
||||
|
||||
This page is an index. Ollama is documented on nine pages, one per reader
|
||||
|
||||
@@ -21,7 +21,7 @@ sidebarTitle: "Setup"
|
||||
A custom provider with `api: "ollama"` follows the same rules. For example, an `ollama-remote` provider pointed at a private LAN host can use `apiKey: "ollama-local"`; sub-agents resolve that marker through the Ollama provider hook instead of treating it as a missing credential. `memory.search.provider` can also point at a custom provider id so embeddings use that Ollama endpoint.
|
||||
</Accordion>
|
||||
<Accordion title="Auth profiles">
|
||||
SQLite auth stores hold the credential for a provider id; put endpoint settings (`baseUrl`, `api`, models, headers, timeouts) in `models.providers.<id>`. Older flat `auth-profiles.json` files such as `{ "ollama-windows": { "apiKey": "ollama-local" } }` are not a runtime format; `openclaw doctor --fix` imports them into SQLite as a canonical `ollama-windows:default` API-key profile with a backup. A `baseUrl` value in that legacy file is noise and should move to provider config.
|
||||
SQLite auth stores hold the credential for a provider id; put endpoint settings (`baseUrl`, `api`, models, headers, timeouts) in `models.providers.<id>`. Older flat `auth-profiles.json` files such as `{ "ollama-windows": { "apiKey": "ollama-local" } }` are not a runtime format; `openclaw doctor --fix` imports them into SQLite as an `ollama-windows:default` API-key profile with a backup. A `baseUrl` value in that legacy file is noise and should move to provider config.
|
||||
</Accordion>
|
||||
<Accordion title="Memory embedding scope">
|
||||
Bearer auth for Ollama memory embeddings is scoped to the host it was declared for:
|
||||
|
||||
@@ -9,7 +9,7 @@ title: "OpenAI"
|
||||
---
|
||||
|
||||
OpenClaw uses one provider id, `openai`, for both direct API-key auth and
|
||||
ChatGPT/Codex subscription auth. `openai/*` is the canonical model route.
|
||||
ChatGPT/Codex subscription auth. `openai/*` is the standard model route.
|
||||
For embedded agent turns with runtime policy unset or `auto`, OpenAI's route
|
||||
facts decide whether OpenClaw may select the bundled Codex app-server runtime
|
||||
implicitly. The `openai/*` prefix alone does not select a runtime.
|
||||
@@ -68,7 +68,7 @@ working. Each entry points at the page that now holds the content.
|
||||
- <a id="verify-the-model-is-available" />[Verify the model is available](/providers/openai/setup#verify-the-model-is-available)
|
||||
- <a id="codex-subscription" />[Codex subscription](/providers/openai/setup#codex-subscription)
|
||||
- <a id="run-codex-oauth" />[Run Codex OAuth](/providers/openai/setup#run-codex-oauth)
|
||||
- <a id="use-the-canonical-openai-model-route" />[Use the canonical OpenAI model route](/providers/openai/setup#use-the-canonical-openai-model-route)
|
||||
- <a id="use-the-canonical-openai-model-route" />[Use the standard OpenAI model route](/providers/openai/setup#use-the-canonical-openai-model-route)
|
||||
- <a id="verify-codex-auth-is-available" />[Verify Codex auth is available](/providers/openai/setup#verify-codex-auth-is-available)
|
||||
|
||||
**[OpenAI models](/providers/openai/models)**
|
||||
|
||||
@@ -105,7 +105,7 @@ fallback even with explicit `agentRuntime.id: "codex"`; see
|
||||
|
||||
A setup or handshake failure before request dispatch falls back to SSE; it
|
||||
is not retried or reconnected first. After dispatch, failures with an
|
||||
unknown outcome remain replay-unsafe and fail closed. The explicit server
|
||||
unknown outcome stop without replaying the request. The explicit server
|
||||
rejections `previous_response_not_found`,
|
||||
`websocket_connection_limit_reached`, and the Zero Data Retention
|
||||
`unsupported_parameter` rejection of `previous_response_id` are safe
|
||||
|
||||
@@ -271,8 +271,8 @@ and [access guide](https://help.openai.com/en/articles/20001325-a-preview-of-gpt
|
||||
OpenAI's [GPT-5.6 Sol model page](https://developers.openai.com/api/docs/models/gpt-5.6-sol)
|
||||
documents the bare `openai/gpt-5.6` id as a supported alias for Sol. Fresh
|
||||
API-key and ChatGPT/Codex OAuth setup use `openai/gpt-6-astra`. Existing
|
||||
GPT-5.6 selections retain their canonical Sol identity. Run
|
||||
`openclaw doctor --fix` to rewrite persisted bare OpenAI refs to that canonical
|
||||
GPT-5.6 selections retain their full Sol identity. Run
|
||||
`openclaw doctor --fix` to rewrite persisted bare OpenAI refs to that full
|
||||
identity. The native Codex catalog can show the exact Sol, Terra, and Luna ids depending on
|
||||
workspace access. Check the current account with:
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ sidebarTitle: "Runtimes and Codex auth"
|
||||
|
||||
| Name you see | Layer | Meaning |
|
||||
| --------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `openai` | Provider prefix | Canonical OpenAI model route; route facts determine the implicit runtime. |
|
||||
| `openai` | Provider prefix | Standard OpenAI model route; route facts determine the implicit runtime. |
|
||||
| `codex` plugin | Plugin | Bundled plugin providing the native Codex app-server runtime and `/codex` chat controls. |
|
||||
| provider/model `agentRuntime.id: codex` | Agent runtime | Force the native Codex app-server harness for matching embedded turns. |
|
||||
| `/codex ...` | Chat command set | Bind/control Codex app-server threads from a conversation. |
|
||||
@@ -46,7 +46,7 @@ the official HTTPS model `baseUrl` when using that proxy.
|
||||
|
||||
An explicit `agentRuntime.id: "openclaw"` keeps a Codex-eligible route on
|
||||
OpenClaw. Explicit `agentRuntime.id: "codex"` requires a registered Codex harness;
|
||||
unsupported routes/auth fail closed, except that authored request overrides may
|
||||
unsupported routes/auth are rejected, except that authored request overrides may
|
||||
use Codex's declared exact-request OpenClaw fallback before execution. Inspect
|
||||
the completed result's actual harness when a recipe depends on native execution.
|
||||
Runtime compatibility does not establish credential type or billing: Platform API-key
|
||||
@@ -68,7 +68,7 @@ models, routes, and profiles.
|
||||
|
||||
`openclaw doctor --fix` migrates legacy `codex/*` and `openai-codex/*` model
|
||||
refs, legacy Codex auth profile ids, and legacy Codex auth-order entries to the
|
||||
canonical `openai` route. Migrated model refs receive model-scoped
|
||||
standard `openai` route. Migrated model refs receive model-scoped
|
||||
`agentRuntime.id: "codex"`; use `auth.order.openai` for new auth-order config.
|
||||
|
||||
<Note>
|
||||
|
||||
@@ -121,7 +121,8 @@ choose based on model access, hosted plugins, usage tracking, and permissions.
|
||||
openclaw models auth login --provider openai --device-code
|
||||
```
|
||||
</Step>
|
||||
<Step title="Use the canonical OpenAI model route">
|
||||
<Step title="Use the standard OpenAI model route">
|
||||
<a id="use-the-canonical-openai-model-route" />
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary openai/gpt-6-astra
|
||||
```
|
||||
@@ -355,7 +356,7 @@ choose based on model access, hosted plugins, usage tracking, and permissions.
|
||||
`openai/gpt-5.6-sol` configuration. Dense turns reached `295098`, `586562`,
|
||||
and `863664` prompt tokens. Turn three emitted and persisted a first-class
|
||||
server compaction item; the next request replayed that exact opaque item,
|
||||
pruned its prefix, and used `9602` prompt tokens. A deterministic long
|
||||
pruned its prefix, and used `9602` prompt tokens. A long
|
||||
response produced `5480` output tokens, durable markers survived compaction
|
||||
and Gateway restart, restart latency was `12081` ms, every call reported
|
||||
`serviceTier: priority`, and the full suite took `220.03` seconds. These
|
||||
|
||||
@@ -144,7 +144,7 @@ under `agents.defaults.mediaModels.image`:
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw sends canonical OpenRouter image requests to the dedicated image API
|
||||
OpenClaw sends standard OpenRouter image requests to the dedicated image API
|
||||
(`POST /api/v1/images`). Gemini image models additionally receive
|
||||
`aspect_ratio` and `resolution` hints, and image edits pass source images as
|
||||
`input_references`. Generated images come back as base64 (`b64_json`) with an
|
||||
|
||||
@@ -84,7 +84,7 @@ The video provider accepts these optional provider-specific keys:
|
||||
|
||||
| Option | Type | Effect |
|
||||
| ------------------------------------ | ------ | --------------------------------------------- |
|
||||
| `seed` | number | Deterministic seed, 0 to 2147483647 |
|
||||
| `seed` | number | Seed for repeatable output, 0 to 2147483647 |
|
||||
| `negativePrompt` / `negative_prompt` | string | Negative prompt |
|
||||
| `quality` | string | PixVerse quality such as `720p` |
|
||||
| `motionMode` / `motion_mode` | string | Image-to-video motion mode (default `normal`) |
|
||||
|
||||
@@ -31,7 +31,7 @@ on the next startup. See [Apply changes and inspect](/plugins/manage-plugins#app
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Baidu Cloud account">
|
||||
Sign up or log in at the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey) and ensure you have Qianfan API access enabled.
|
||||
Sign up or log in at the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey) and enable Qianfan API access.
|
||||
</Step>
|
||||
<Step title="Generate an API key">
|
||||
Create a new application or select an existing one, then generate an API key. Baidu Cloud keys use the `bce-v3/ALTAK-...` format.
|
||||
@@ -125,7 +125,7 @@ Model refs use the `qianfan/` prefix (for example `qianfan/deepseek-v4-pro`).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Troubleshooting">
|
||||
- Ensure your API key starts with `bce-v3/ALTAK-` and has Qianfan API access enabled in the Baidu Cloud console.
|
||||
- Check that your API key starts with `bce-v3/ALTAK-` and has Qianfan API access enabled in the Baidu Cloud console.
|
||||
- If models are not listed, confirm your account has the Qianfan service activated.
|
||||
- Only change the base URL if you use a custom endpoint or proxy.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ read_when:
|
||||
title: "Qwen"
|
||||
---
|
||||
|
||||
Qwen Cloud is an official external OpenClaw provider plugin with canonical id `qwen`. It targets Qwen Cloud / Alibaba DashScope Standard and Coding Plan endpoints, exposes Token Plan as `qwen-token-plan`, keeps `modelstudio` as a compatibility alias, and independently owns Alibaba's documented `bailian-token-plan` custom-provider id.
|
||||
Qwen Cloud is an official external OpenClaw provider plugin with primary id `qwen`. It targets Qwen Cloud / Alibaba DashScope Standard and Coding Plan endpoints, exposes Token Plan as `qwen-token-plan`, keeps `modelstudio` as a compatibility alias, and independently owns Alibaba's documented `bailian-token-plan` custom-provider id.
|
||||
|
||||
| Property | Value |
|
||||
| ---------------------- | ------------------------------------------ |
|
||||
@@ -89,7 +89,7 @@ configuration takes precedence; use the matching plan and regional key.
|
||||
|
||||
<Note>
|
||||
Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
|
||||
work as compatibility aliases, but new setup flows should prefer the canonical
|
||||
work as compatibility aliases, but new setup flows should prefer the current
|
||||
`qwen-*` auth-choice ids and `qwen/...` model refs. If you define an exact
|
||||
custom `models.providers.modelstudio` entry with another `api` value, that
|
||||
custom provider owns `modelstudio/...` refs instead of the Qwen compatibility
|
||||
@@ -138,7 +138,7 @@ configuration takes precedence; use the matching plan and regional key.
|
||||
|
||||
<Note>
|
||||
Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
|
||||
work as compatibility aliases, but new setup flows should prefer the canonical
|
||||
work as compatibility aliases, but new setup flows should prefer the current
|
||||
`qwen-*` auth-choice ids and `qwen/...` model refs. If you define an exact
|
||||
custom `models.providers.modelstudio` entry with another `api` value, that
|
||||
custom provider owns `modelstudio/...` refs instead of the Qwen compatibility
|
||||
@@ -180,7 +180,7 @@ configuration takes precedence; use the matching plan and regional key.
|
||||
provider. The plugin registers that id as a compatibility owner, but new
|
||||
configs should use `qwen-token-plan`. An exact custom
|
||||
`models.providers.bailian-token-plan` entry keeps ownership of its configured
|
||||
transport and catalog; it is never merged into the canonical OpenAI catalog.
|
||||
transport and catalog; it is never merged into the OpenAI catalog.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
@@ -214,7 +214,7 @@ are not converted automatically.
|
||||
| Token Plan (Team Edition) | China | `qwen-token-plan-cn` | `token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` |
|
||||
| Token Plan (Team Edition) | Global | `qwen-token-plan` | `token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` |
|
||||
|
||||
The provider auto-selects the endpoint based on your auth choice. Canonical
|
||||
The provider auto-selects the endpoint based on your auth choice. Current
|
||||
choices use the `qwen-*` family; `modelstudio-*` remains compatibility-only.
|
||||
Override with a custom `baseUrl` in config.
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ OpenClaw ships a bundled `runway` provider for hosted video generation, enabled
|
||||
| --------------- | ----------------------------------------------------------------- |
|
||||
| Provider id | `runway` |
|
||||
| Plugin | bundled, `enabledByDefault: true` |
|
||||
| Auth env vars | `RUNWAYML_API_SECRET` (canonical) or `RUNWAY_API_KEY` |
|
||||
| Auth env vars | `RUNWAYML_API_SECRET` (preferred) or `RUNWAY_API_KEY` |
|
||||
| Onboarding flag | `--auth-choice runway-api-key` |
|
||||
| Direct CLI flag | `--runway-api-key <key>` |
|
||||
| API | Runway task-based video generation (`GET /v1/tasks/{id}` polling) |
|
||||
@@ -82,7 +82,7 @@ Local image and video references are supported via data URIs.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Environment variable aliases">
|
||||
OpenClaw recognizes both `RUNWAYML_API_SECRET` (canonical) and `RUNWAY_API_KEY`.
|
||||
OpenClaw recognizes both `RUNWAYML_API_SECRET` (preferred) and `RUNWAY_API_KEY`.
|
||||
Either variable authenticates the Runway provider.
|
||||
</Accordion>
|
||||
|
||||
|
||||
@@ -141,7 +141,7 @@ review its different pricing and verify model access for the selected endpoint.
|
||||
If the Gateway runs as a managed service (launchd, systemd, Docker), `TOKENHUB_API_KEY` and `TOKENPLAN_API_KEY` must be visible to that process. Set them in `~/.openclaw/.env` or via `env.shellEnv` so launchd, systemd, or Docker exec environments can read them.
|
||||
|
||||
<Warning>
|
||||
Keys exported only in an interactive shell are not visible to managed gateway processes. Use the env file or config seam for persistent availability.
|
||||
Keys exported only in an interactive shell are not visible to managed gateway processes. Use the env file or config setting for persistent availability.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
@@ -138,7 +138,7 @@ catalog if the API is unreachable. The `/models` endpoint is public (no auth nee
|
||||
listing), but inference requires a valid API key.
|
||||
|
||||
Venice may continue accepting retired model IDs as provider-owned aliases. The
|
||||
OpenClaw catalog advertises only the canonical model IDs returned by `/models`.
|
||||
OpenClaw catalog advertises only the model IDs returned by `/models`.
|
||||
|
||||
## DeepSeek V4 replay behavior
|
||||
|
||||
|
||||
@@ -80,7 +80,7 @@ OpenClaw normalizes Claude shorthand model refs at runtime:
|
||||
| `vercel-ai-gateway/opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4-6` |
|
||||
|
||||
<Tip>
|
||||
Use either form in your configuration; OpenClaw resolves the canonical
|
||||
Use either form in your configuration; OpenClaw resolves the full
|
||||
`anthropic/...` ref automatically.
|
||||
</Tip>
|
||||
|
||||
@@ -94,7 +94,7 @@ Use either form in your configuration; OpenClaw resolves the canonical
|
||||
<Warning>
|
||||
A key exported only in an interactive shell will not be visible to a
|
||||
launchd/systemd daemon unless that environment is explicitly imported. Set
|
||||
the key in `~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway
|
||||
the key in `~/.openclaw/.env` or via `env.shellEnv` so the gateway
|
||||
process can read it.
|
||||
</Warning>
|
||||
|
||||
|
||||
@@ -283,7 +283,7 @@ An explicit tool model remains selected; the Grok 4.3 examples below are overrid
|
||||
tool calls, plus the model's input and output tokens. With each tool's
|
||||
`enabled` setting omitted, OpenClaw exposes it only for an active xAI model.
|
||||
A known non-xAI model provider requires an explicit per-tool `enabled: true`;
|
||||
a missing or unresolved provider fails closed. xAI auth is always required,
|
||||
a missing or unresolved provider blocks the request. xAI auth is always required,
|
||||
and `enabled: false` disables the tool for every provider.
|
||||
</Warning>
|
||||
|
||||
@@ -601,7 +601,7 @@ An explicit tool model remains selected; the Grok 4.3 examples below are overrid
|
||||
xAI to retain enough session state to resume the same conversation after a
|
||||
reconnect and then reconnects with the returned conversation id. Leave it
|
||||
disabled when provider-side replay/retention is not acceptable; interrupted
|
||||
sockets then fail closed instead of silently starting a fresh conversation.
|
||||
sockets then stop instead of silently starting a fresh conversation.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
@@ -278,7 +278,7 @@ USD pricing, so its catalog rows use zero USD cost and the config example omits
|
||||
<Accordion title="Troubleshooting">
|
||||
- If models do not appear, confirm the relevant key env var or auth profile is present and valid.
|
||||
- For Token Plan, confirm the chosen onboarding region matches the subscription page base URL and that the key starts with `tp-`.
|
||||
- When the Gateway runs as a daemon, ensure the key is available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
|
||||
- When the Gateway runs as a daemon, make the key available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
|
||||
|
||||
<Warning>
|
||||
Keys set only in your interactive shell are not visible to daemon-managed gateway processes. Use `~/.openclaw/.env` or `env.shellEnv` config for persistent availability.
|
||||
|
||||
+1
-1
@@ -77,7 +77,7 @@ Built Molty's world. Gave a lobster shell access. May regret this.
|
||||
|
||||
## The Moltiverse
|
||||
|
||||
The **Moltiverse** is the community and ecosystem around OpenClaw: a space
|
||||
The **Moltiverse** is the community around OpenClaw: a space
|
||||
where AI agents molt, grow, and evolve, and every instance is equally real,
|
||||
just loading different context.
|
||||
|
||||
|
||||
@@ -197,7 +197,7 @@ so another provider can opt in without adding provider-specific macOS code.
|
||||
|
||||
The manual key/token picker uses the same provider registry. In every route,
|
||||
the provider supplies its starter model and configuration. If the starter is an
|
||||
alias, OpenClaw tests and saves the provider's canonical model name while
|
||||
alias, OpenClaw tests and saves the provider's full model name while
|
||||
preserving existing model settings that the starter does not replace.
|
||||
A replacement credential stays inactive until you accept **Activate this saved
|
||||
sign-in?** after verification. Declining keeps your current connection and the
|
||||
|
||||
+1
-1
@@ -74,7 +74,7 @@ node openclaw.mjs gateway --port 18789 --verbose
|
||||
|
||||
1. Install + launch **OpenClaw.app** (menu bar).
|
||||
2. Complete the onboarding/permissions checklist (TCC prompts).
|
||||
3. Ensure Gateway is **Local** and running (the app manages it).
|
||||
3. Check that Gateway is **Local** and running (the app manages it).
|
||||
4. Link surfaces (example: WhatsApp):
|
||||
|
||||
```bash
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "The architecture case for OpenClaw: a trusted gateway, untrusted execution, deterministic policy, and versioned state, compared source-by-source with single-process harnesses"
|
||||
summary: "The architecture case for OpenClaw: a trusted gateway, untrusted execution, policy enforced by code, and versioned state, compared source-by-source with single-process harnesses"
|
||||
read_when:
|
||||
- You are evaluating agent harnesses for team or enterprise use
|
||||
- You need to explain to a security team how OpenClaw differs from single-process harnesses
|
||||
@@ -35,7 +35,7 @@ A good harness spans the whole range: the same product runs as a personal assist
|
||||
Seven testable properties:
|
||||
|
||||
1. **Separated trust boundary.** Execution moves into a sandbox, a node, or a throwaway cloud machine without standing Gateway credentials; scoped worker credentials have a separate lifecycle.
|
||||
2. **Policy is code.** Denial is structural, not a request the model is asked to honor; approval paths fail closed.
|
||||
2. **Policy is code.** Denial is structural, not a request the model is asked to honor; approval paths deny requests when validation fails.
|
||||
3. **Authenticated access, bounded roles.** Inbound access is default-deny and authenticated; people hold bounded roles; the vendor states which boundaries are security and which are convenience.
|
||||
4. **Secrets have owners.** Isolatable credential failures degrade their owners; ingress-auth and invalid-configuration failures stop startup.
|
||||
5. **Versioned state, guarded upgrades.** State is schema-versioned with owned migrations; upgrades are guarded and delivered through release channels.
|
||||
@@ -74,7 +74,7 @@ The public plugin SDK publishes about 150 entrypoints, held under shrink-only su
|
||||
|
||||
## Open standards
|
||||
|
||||
OpenClaw adopts the protocols the ecosystem is converging on. It is an [MCP client](/tools/mcp) (Streamable HTTP, SSE, and stdio transports, with OAuth) and an [MCP server](/cli/mcp), and plugins can [ship their own MCP servers and apps](/plugins/manifest/surfaces#mcp-server-reference). Other agents reach it through the Linux Foundation [A2A 1.0 protocol](/channels/a2a) — Agent Card discovery, authenticated JSON-RPC tasks, and outbound peer messaging — and editors connect over the [Agent Client Protocol](/cli/acp), which OpenClaw also uses to [host external harnesses](/tools/acp-agents). Agents render live [A2UI widgets](/web/dashboards) on session dashboards.
|
||||
OpenClaw adopts protocols used across AI tools. It is an [MCP client](/tools/mcp) (Streamable HTTP, SSE, and stdio transports, with OAuth) and an [MCP server](/cli/mcp), and plugins can [ship their own MCP servers and apps](/plugins/manifest/surfaces#mcp-server-reference). Other agents reach it through the Linux Foundation [A2A 1.0 protocol](/channels/a2a) — Agent Card discovery, authenticated JSON-RPC tasks, and outbound peer messaging — and editors connect over the [Agent Client Protocol](/cli/acp), which OpenClaw also uses to [host external harnesses](/tools/acp-agents). Agents render live [A2UI widgets](/web/dashboards) on session dashboards.
|
||||
|
||||
Skills follow the [AgentSkills spec](/tools/skills), plugin installs auto-detect [Agent Plugins, Codex, Claude, and Cursor bundle layouts](/plugins/bundles), and the Gateway can serve an [OpenAI-compatible API](/gateway/openai-http-api) (`/v1/chat/completions` with a documented function-tool subset, [`/v1/responses`](/gateway/openresponses-http-api), `/v1/models`, `/v1/embeddings`; disabled by default, `/v1/responses` separately enabled) so OpenAI clients can target the Gateway directly. Observability exports over [OpenTelemetry](/gateway/opentelemetry) and [Prometheus](/gateway/prometheus); gateways advertise via [Bonjour and DNS-SD](/gateway/bonjour); channels include native [Matrix](/channels/matrix), [IRC](/channels/irc), and [Nostr](/channels/nostr) protocol implementations; and releases ship with [npm provenance and verifiable artifact attestations](/reference/RELEASING).
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Hermes also has [opt-in session pruning](https://github.com/NousResearch/hermes-
|
||||
| Property | OpenClaw | Hermes Agent (`6defe7eb6c`) |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Trust boundary | Gateway-owned authority; configured sandbox, node, or cloud-worker execution; sandboxing off by default | Parent-owned tool dispatch; terminal, file, and generated-Python work can use remote backends |
|
||||
| Policy gate | Structural tool policy and deterministic denial; optional review and approval layers | Smart review of flagged commands behind hardline/configured denials on host-reaching backends; cron and one-shot defaults deny flagged commands, other headless paths may auto-approve |
|
||||
| Policy gate | Structural tool policy and denial enforced by code; optional review and approval layers | Smart review of flagged commands behind hardline/configured denials on host-reaching backends; cron and one-shot defaults deny flagged commands, other headless paths may auto-approve |
|
||||
| Vendor harnesses | Codex app-server, Copilot SDK, Claude Code CLI as native runtimes | Opt-in Codex loop with steering and a curated MCP tool bridge; text-only turn input, no native resume after restart; Copilot API and ACP adapters |
|
||||
| Code execution | JavaScript Code Mode with Node or QuickJS, typed tool documentation, and policy checked on host tool calls | Python in a local child or configured terminal backend, with bounded tool RPCs through the parent |
|
||||
| Roles and multi-user | Configured person-level role ceilings and default role; scopes and session attribution | Equal trust within an adapter's authorized set; slash-command controls and separate profiles, including profile multiplexing |
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
---
|
||||
summary: "Permission modes, tool policy, and exec approvals as deterministic code-enforced gates rather than prompt requests"
|
||||
summary: "Permission modes, tool policy, and exec approvals as code-enforced gates rather than prompt requests"
|
||||
title: "Policy as code"
|
||||
read_when:
|
||||
- You need to know which OpenClaw denials are structural rather than model-dependent
|
||||
- You are configuring permission modes, tool policy, or exec approvals
|
||||
- You need the approval binding and fail-closed rules
|
||||
- You need to understand how approvals are bound and when requests are denied
|
||||
---
|
||||
|
||||
Deterministic enforcement is not unique to OpenClaw — Claude Code, Codex, and Goose all gate approvals in code. Structural tool gating in a multi-channel assistant, rather than a terminal, is rarer: [permission modes](/gateway/permission-modes) shape which tools exist at all. For OpenClaw-managed tools, a `read-only` session omits `edit`, `write`, and `apply_patch`, and its exec tool resolves to a deny policy at the call boundary. Native harnesses can retain their own tool surface and apply native permission controls separately ([Codex runtime policy](/plugins/codex-harness-runtime)). `full` requires `operator.admin`, and scopes are derived from request parameters before dispatch ([operator scopes](/gateway/operator-scopes)), so a method with a privileged parameter still needs the privileged scope.
|
||||
Code-based enforcement is not unique to OpenClaw — Claude Code, Codex, and Goose all gate approvals in code. Structural tool gating in a multi-channel assistant, rather than a terminal, is rarer: [permission modes](/gateway/permission-modes) shape which tools exist at all. For OpenClaw-managed tools, a `read-only` session omits `edit`, `write`, and `apply_patch`, and its exec tool resolves to a deny policy at the call boundary. Native harnesses can retain their own tool surface and apply native permission controls separately ([Codex runtime policy](/plugins/codex-harness-runtime)). `full` requires `operator.admin`, and scopes are derived from request parameters before dispatch ([operator scopes](/gateway/operator-scopes)), so a method with a privileged parameter still needs the privileged scope.
|
||||
|
||||
Three controls govern separate decisions ([sandbox vs. tool policy vs. elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)). The sandbox decides where tools run. Tool policy decides which tools exist; deny always wins. Routine policy-filter diagnostics name the configured layer and matched deny entries at debug level; the [durable audit ledger](/gateway/audit) records blocked outcomes separately, without the matched rule. `tools.elevated` is an exec-only escape hatch that cannot override a deny.
|
||||
|
||||
[Exec approvals](/tools/exec-approvals) bind an approved run to its canonical command, cwd, environment hash, and content-hashed file operands, and deny on any drift after approval. Supported pipelines and command chains can use enforced execution plans. Shell forms or interpreter invocations for which OpenClaw cannot establish the required execution and file bindings are refused. When no approval UI is reachable, the answer is deny by default, and strict cases (inline eval, heredocs) cannot be softened by any fallback setting.
|
||||
[Exec approvals](/tools/exec-approvals) bind an approved run to its exact command, cwd, environment hash, and content-hashed file operands, and deny on any drift after approval. Supported pipelines and command chains can use enforced execution plans. Shell forms or interpreter invocations for which OpenClaw cannot establish the required execution and file bindings are refused. When no approval UI is reachable, the answer is deny by default, and strict cases (inline eval, heredocs) cannot be softened by any fallback setting.
|
||||
|
||||
```mermaid actions={true} placement="top-right"
|
||||
flowchart LR
|
||||
|
||||
@@ -31,7 +31,7 @@ flowchart LR
|
||||
|
||||
[`tools.exec.host`](/tools/exec) resolves to the gateway host, a [sandbox](/gateway/sandboxing), or a paired [node](/nodes). While a sandbox runtime is active, per-call escapes to the host are rejected. An explicit `host=sandbox` with no runtime configured fails instead of silently running on the host. The backends are Docker and Podman, SSH, and [OpenShell](/gateway/openshell). The default Docker and Podman profile has no network, a read-only root, all capabilities dropped, and a non-root user. OpenShell installs as a plugin and registers through the same backend contract as Docker. If you run OpenShell already, OpenClaw uses its sandboxes. It does not need to be wrapped in one.
|
||||
|
||||
Sandbox bind mounts are validated twice, once on the normalized path and again after resolving through the deepest existing ancestor, so symlink-based bypass attempts fail closed. The deny-list of credential and system paths cannot be disabled — the `dangerouslyAllowExternalBindSources` override relaxes only the allowed-roots check.
|
||||
Sandbox bind mounts are validated twice, once on the normalized path and again after resolving through the deepest existing ancestor, so symlink-based bypass attempts are rejected. The deny-list of credential and system paths cannot be disabled — the `dangerouslyAllowExternalBindSources` override relaxes only the allowed-roots check.
|
||||
|
||||
This separation also applies across machines. A paired [node](/nodes) that hosts sessions receives a sealed worker artifact. OpenClaw verifies that artifact's content hash at three points: download, manifest, and every reuse. The node installs no packages and runs no lifecycle scripts. It can also put each hosted session in its own container, enforced by node-local config the Gateway's launch request cannot express.
|
||||
|
||||
|
||||
@@ -9,6 +9,6 @@ read_when:
|
||||
|
||||
Runtime state is database-first: one global SQLite store, one per agent, with a written contract that runtime code never reads or writes JSON sidecars as active state. The contract is machine-checked in CI ([database schemas](/reference/database-schemas)). Schemas carry a two-place version contract; a build refuses to open a database newer than itself. [`openclaw update`](/cli/update) refuses targets whose declared schema support is older than your on-disk databases; legacy target packages without schema metadata cannot be preflighted. [`openclaw doctor --fix`](/cli/doctor) is the single owner of file-to-SQLite migrations and records a receipt for each one. SQLite snapshots in [backups](/cli/backup) use SQLite's online-backup API and are integrity- and hash-checked during creation and publication. Whole-archive verification does not bind ordinary file payloads to content hashes; restore never happens in place. [Restart recovery](/gateway/restart-recovery) resumes interrupted turns under a bounded attempt budget, and a crash-loop breaker keeps the control plane reachable while suppressing channel autostart.
|
||||
|
||||
Releases come through four channels (stable, extended-stable, beta, dev) on calendar versions with immutable npm publishes ([development channels](/install/development-channels), [release process](/reference/RELEASING)). Extended-stable is the conservative track and it fails closed: the updater re-fetches and verifies the exact selected package, and missing or inconsistent registry data is an error, never a fallback to `latest`. The [Full Release Validation](/reference/full-release-validation) workflow seals an immutable execution-plan artifact covering cross-OS installs and upgrades, package acceptance, live channel lanes, and performance gates. Publishing is serialized and provenance-verified (Sigstore attestations, npm provenance) under the OpenClaw Foundation identity.
|
||||
Releases come through four channels (stable, extended-stable, beta, dev) on calendar versions with immutable npm publishes ([development channels](/install/development-channels), [release process](/reference/RELEASING)). Extended-stable is the conservative track: the updater re-fetches and verifies the exact selected package, and missing or inconsistent registry data is an error, never a fallback to `latest`. The [Full Release Validation](/reference/full-release-validation) workflow seals an immutable execution-plan artifact covering cross-OS installs and upgrades, package acceptance, live channel lanes, and performance gates. Publishing is serialized and provenance-verified (Sigstore attestations, npm provenance) under the OpenClaw Foundation identity.
|
||||
|
||||
Per-surface readiness is published. The [maturity scorecard](/maturity/scorecard) grades 50 surfaces across [280 capability areas](/maturity/taxonomy) from deterministic QA evidence plus reviewed quality scores, with long-term-support status on every row. Extended-stable answers how long a surface is supported; the scorecard answers how proven it is.
|
||||
Per-surface readiness is published. The [maturity scorecard](/maturity/scorecard) grades 50 surfaces across [280 capability areas](/maturity/taxonomy) from repeatable QA checks plus reviewed quality scores, with long-term-support status on every row. Extended-stable answers how long a surface is supported; the scorecard answers how proven it is.
|
||||
+1
-1
@@ -127,7 +127,7 @@ TimeoutStartSec=90
|
||||
If you deliberately installed a system unit instead, edit it via
|
||||
`sudo systemctl edit openclaw-gateway.service`.
|
||||
|
||||
For the canonical managed unit body and its restart policy, see the [Gateway runbook](/gateway).
|
||||
For the standard managed unit definition and its restart policy, see the [Gateway runbook](/gateway).
|
||||
|
||||
For Linux OOM behavior, child process victim selection, and `exit 137`
|
||||
diagnostics, see [Linux memory pressure and OOM kills](/platforms/linux#memory-pressure-and-oom-kills).
|
||||
|
||||
Reference in new issue
Block a user