diff --git a/CHANGELOG.md b/CHANGELOG.md index 8530830219a5..2bcd3a8187ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Docs: consolidate GLM under Z.AI, add the Upstash Box install guide and Gateway exposure runbook, clarify MEDIA directives, Copilot and Voyage setup, config path quoting, real behavior proof, and memory-file write guidance. Thanks @BobDu, @alitariksahin, @Jefsky, @musaabhasan, @OmerZeyveli, @leno23, @WuKongAI-CMU, @luoyanglang, and @majin1102. - Docs: clarify media provider credentials, Codex/OpenClaw code-mode boundaries, Slack and Telegram ack reactions, Feishu dynamic agents, secrets plaintext boundaries, memory guidance, and Chinese glossary terms. Thanks @nielskaspers, @cosmopolitan033, @drclaw-iq, @alexgduarte, @zccyman, @chengoak, and @cassthebandit. - Packaging: exclude documentation images and assets from the npm tarball, reducing published package size without affecting runtime docs search or CLI behavior. Thanks @SebTardif. - Agents/subagents: limit default sub-agent bootstrap context to `AGENTS.md` and `TOOLS.md`, keeping persona, identity, user, memory, heartbeat, and setup files out of delegated workers by default. (#85283) Thanks @100yenadmin. diff --git a/README.md b/README.md index a3ce88e5205e..ff3c910adc63 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,8 @@ Models config + CLI: [Models](https://docs.openclaw.ai/concepts/models). Auth pr OpenClaw connects to real messaging surfaces. Treat inbound DMs as **untrusted input**. -Full security guide: [Security](https://docs.openclaw.ai/gateway/security) +Full security guide: [Security](https://docs.openclaw.ai/gateway/security). +Before remote exposure, use the [Gateway exposure runbook](https://docs.openclaw.ai/gateway/security/exposure-runbook). Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack: @@ -159,7 +160,7 @@ Run `openclaw doctor` to surface risky/misconfigured DM policies. - Default: tools run on the host for the `main` session, so the agent has full access when it is just you. - Group/channel safety: set `agents.defaults.sandbox.mode: "non-main"` to run non-`main` sessions inside sandboxes. Docker is the default sandbox backend; SSH and OpenShell backends are also available. - Typical sandbox default: allow `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`; deny `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`. -- Before exposing anything remotely, read [Security](https://docs.openclaw.ai/gateway/security), [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing), and [Configuration](https://docs.openclaw.ai/gateway/configuration). +- Before exposing anything remotely, read [Security](https://docs.openclaw.ai/gateway/security), [Gateway exposure runbook](https://docs.openclaw.ai/gateway/security/exposure-runbook), [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing), and [Configuration](https://docs.openclaw.ai/gateway/configuration). ## Operator quick refs @@ -173,7 +174,7 @@ Run `openclaw doctor` to surface risky/misconfigured DM policies. - New here: [Getting started](https://docs.openclaw.ai/start/getting-started), [Onboarding](https://docs.openclaw.ai/start/wizard), [Updating](https://docs.openclaw.ai/install/updating) - Channel setup: [Channels index](https://docs.openclaw.ai/channels), [WhatsApp](https://docs.openclaw.ai/channels/whatsapp), [Telegram](https://docs.openclaw.ai/channels/telegram), [Discord](https://docs.openclaw.ai/channels/discord), [Slack](https://docs.openclaw.ai/channels/slack) - Apps + nodes: [macOS](https://docs.openclaw.ai/platforms/macos), [iOS](https://docs.openclaw.ai/platforms/ios), [Android](https://docs.openclaw.ai/platforms/android), [Nodes](https://docs.openclaw.ai/nodes) -- Config + security: [Configuration](https://docs.openclaw.ai/gateway/configuration), [Security](https://docs.openclaw.ai/gateway/security), [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing) +- Config + security: [Configuration](https://docs.openclaw.ai/gateway/configuration), [Security](https://docs.openclaw.ai/gateway/security), [Exposure runbook](https://docs.openclaw.ai/gateway/security/exposure-runbook), [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing) - Remote + web: [Gateway](https://docs.openclaw.ai/gateway), [Remote access](https://docs.openclaw.ai/gateway/remote), [Tailscale](https://docs.openclaw.ai/gateway/tailscale), [Web surfaces](https://docs.openclaw.ai/web) - Tools + automation: [Tools](https://docs.openclaw.ai/tools), [Skills](https://docs.openclaw.ai/tools/skills), [Cron jobs](https://docs.openclaw.ai/automation/cron-jobs), [Webhooks](https://docs.openclaw.ai/automation/webhook), [Gmail Pub/Sub](https://docs.openclaw.ai/automation/gmail-pubsub) - Internals: [Architecture](https://docs.openclaw.ai/concepts/architecture), [Agent](https://docs.openclaw.ai/concepts/agent), [Session model](https://docs.openclaw.ai/concepts/session), [Gateway protocol](https://docs.openclaw.ai/reference/rpc) diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 99fbffb7a504..e05e18a9f3cf 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -1022,5 +1022,13 @@ { "source": "Per-user agent isolation", "target": "每用户 Agent 隔离" + }, + { + "source": "Gateway exposure runbook", + "target": "Gateway 暴露运行手册" + }, + { + "source": "Z.AI (GLM)", + "target": "Z.AI (GLM)" } ] diff --git a/docs/.i18n/zh-Hans-navigation.json b/docs/.i18n/zh-Hans-navigation.json index 4380ee2ca239..641d4b0054cd 100644 --- a/docs/.i18n/zh-Hans-navigation.json +++ b/docs/.i18n/zh-Hans-navigation.json @@ -260,7 +260,6 @@ "zh-CN/providers/claude-max-api-proxy", "zh-CN/providers/deepgram", "zh-CN/providers/github-copilot", - "zh-CN/providers/glm", "zh-CN/providers/moonshot", "zh-CN/providers/minimax", "zh-CN/providers/opencode", diff --git a/docs/ci.md b/docs/ci.md index dba615957336..652eab021669 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -45,6 +45,34 @@ GitHub may mark superseded jobs as `cancelled` when a newer push lands on the sa The `ci-timings-summary` job uploads a compact `ci-timings-summary` artifact for each non-draft CI run. It records wall time, queue time, slowest jobs, and failed jobs for the current run, so CI health checks do not need to scrape the full Actions payload repeatedly. +## Real behavior proof + +External contributor PRs run a `Real behavior proof` gate from +`.github/workflows/real-behavior-proof.yml`. The workflow checks out the trusted +base commit and evaluates the PR body only; it does not execute code from the +contributor branch. + +The gate applies to PR authors who are not repository owners, members, +collaborators, or bots. It passes when the PR body contains a +`Real behavior proof` section with filled values for: + +- `Behavior or issue addressed` +- `Real environment tested` +- `Exact steps or command run after this patch` +- `Evidence after fix` +- `Observed result after fix` +- `What was not tested` + +The evidence must show the changed behavior after the patch in a real OpenClaw +setup. Screenshots, recordings, terminal captures, console output, copied live +output, redacted runtime logs, and linked artifacts all count. Unit tests, mocks, +snapshots, lint, typechecks, and CI results are useful supporting verification, +but they do not satisfy this gate by themselves. + +When the check fails, update the PR body instead of pushing another code commit. +Maintainers can apply `proof: override` only when the proof gate should not +apply to that PR. + ## Scope and routing Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`. Manual dispatch skips changed-scope detection and makes the preflight manifest act as if every scoped area changed. diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 7a806de3f4ff..7903f23e86b9 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -177,7 +177,7 @@ Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so Ope ### Other subscription-style hosted options - + Z.AI Coding Plan or general API endpoints. diff --git a/docs/concepts/oauth.md b/docs/concepts/oauth.md index 9a219eca85e9..0d8b1b684ecf 100644 --- a/docs/concepts/oauth.md +++ b/docs/concepts/oauth.md @@ -95,7 +95,7 @@ plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with- If you want other subscription-style options in OpenClaw, see [OpenAI Codex](/providers/openai), [Qwen Cloud Coding Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax), -and [Z.AI / GLM Coding Plan](/providers/glm). +and [Z.AI / GLM Coding Plan](/providers/zai). OpenClaw also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and `claude -p` when available. diff --git a/docs/docs.json b/docs/docs.json index d95325df00f4..fdd601e3f452 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -226,12 +226,16 @@ }, { "source": "/glm", - "destination": "/providers/glm" + "destination": "/providers/zai" }, { "source": "/zai", "destination": "/providers/zai" }, + { + "source": "/providers/glm", + "destination": "/providers/zai" + }, { "source": "/message", "destination": "/cli/message" @@ -1040,7 +1044,8 @@ "install/oracle", "install/railway", "install/raspberry-pi", - "install/render" + "install/render", + "install/upstash" ] }, { @@ -1381,7 +1386,6 @@ "providers/fal", "providers/fireworks", "providers/github-copilot", - "providers/glm", "providers/google", "providers/gradium", "providers/groq", @@ -1529,6 +1533,7 @@ "group": "Security and sandboxing", "pages": [ "gateway/security/index", + "gateway/security/exposure-runbook", "gateway/security/secure-file-operations", "gateway/security/audit-checks", "gateway/operator-scopes", diff --git a/docs/gateway/security/exposure-runbook.md b/docs/gateway/security/exposure-runbook.md new file mode 100644 index 000000000000..188b948ead16 --- /dev/null +++ b/docs/gateway/security/exposure-runbook.md @@ -0,0 +1,212 @@ +--- +summary: "Pre-flight and rollback checklist before exposing an OpenClaw Gateway beyond loopback" +title: "Gateway exposure runbook" +sidebarTitle: "Exposure runbook" +read_when: + - Exposing the Gateway over LAN, tailnet, Tailscale Serve, Funnel, or a reverse proxy + - Reviewing a deployment before allowing real messaging users + - Rolling back a risky remote access or DM configuration +--- + + +Expose the Gateway only after you can explain who can reach it, how they are +authenticated, which agents they can trigger, and which tools those agents can +use. When in doubt, return to loopback-only access and re-run the audit. + + +This runbook turns the broader [Security](/gateway/security) guidance into an +operator checklist for remote access and messaging exposure. + +## Choose the exposure pattern + +Prefer the narrowest pattern that satisfies the workflow. + +| Pattern | Recommended when | Required controls | +| -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| Loopback + SSH tunnel | Personal use, admin access, debugging | Keep `gateway.bind: "loopback"` and tunnel `127.0.0.1:18789` | +| Loopback + Tailscale Serve | Personal tailnet access to Control UI/WebSocket | Keep Gateway loopback-only; rely on Tailscale identity headers only for supported surfaces | +| Tailnet/LAN bind | Dedicated private network with known devices | Gateway auth, firewall allowlist, no public port-forward | +| Trusted reverse proxy | Organization SSO/OIDC in front of Gateway | `trusted-proxy` auth, strict `trustedProxies`, header overwrite/strip rules, explicit allowed users | +| Public internet | Rare, high-risk deployments | Identity-aware proxy, TLS, rate limits, strict allowlists, sandboxed non-main sessions | + +Avoid direct public port-forwarding to the Gateway. If you need public access, +put an identity-aware proxy in front of it and make the proxy the only network +path to the Gateway. + +## Pre-flight inventory + +Record these before changing bind, proxy, Tailscale, or channel policy: + +- Gateway host, OS user, and state directory. +- Gateway URL and bind mode. +- Auth mode, token/password source, or trusted proxy identity source. +- All enabled channels and whether they accept DMs, groups, or webhooks. +- Agents reachable from non-local senders. +- Tool profile, sandbox mode, and elevated tool policy for each reachable agent. +- External credentials available to those agents. +- Backup location for `~/.openclaw/openclaw.json` and credentials. + +If more than one person can message the bot, treat this as shared delegated tool +authority, not as per-user host isolation. + +## Baseline checks + +Run these before opening access: + +```bash +openclaw doctor +openclaw security audit +openclaw security audit --deep +openclaw health +``` + +Resolve critical findings first. Warnings may be acceptable only when they are +intentional and documented for the deployment. + +For remote CLI validation, pass credentials explicitly: + +```bash +openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN" +``` + +Do not assume local config credentials apply to an explicit remote URL. + +## Minimum safe baseline + +Use this shape as the starting point for exposed deployments: + +```json5 +{ + gateway: { + bind: "loopback", + auth: { + mode: "token", + token: "replace-with-a-long-random-token", + }, + }, + session: { + dmScope: "per-channel-peer", + }, + agents: { + defaults: { + sandbox: { mode: "non-main" }, + }, + }, + tools: { + profile: "messaging", + exec: { security: "deny", ask: "always" }, + elevated: { enabled: false }, + }, +} +``` + +Then widen one control at a time. For example, add a specific channel allowlist +before enabling write-capable tools, or enable a reverse proxy before accepting +remote Control UI traffic. + +The strict `exec.security: "deny"` baseline blocks all exec calls, including +benign diagnostics. If diagnostics or low-risk commands are required, relax this +only after choosing the specific senders, agents, commands, and approval mode +that match your threat model. + +## DM and group exposure + +Messaging channels are untrusted input surfaces. Before allowing DMs or groups: + +- Prefer `dmPolicy: "pairing"` or strict `allowFrom` lists. +- Avoid `dmPolicy: "open"` unless every sender is trusted. +- Do not combine `"*"` allowlists with broad tool access. +- Require mentions in groups unless the room is tightly controlled. +- Use `session.dmScope: "per-channel-peer"` when multiple people can DM the bot. +- Route shared channels to agents with minimal tools and no personal credentials. + +Pairing approves the sender to trigger the bot. It does not make that sender a +separate host security boundary. + +## Reverse proxy checks + +For identity-aware proxies: + +- The proxy must authenticate users before forwarding to the Gateway. +- Direct access to the Gateway port must be blocked by firewall or network policy. +- `gateway.trustedProxies` must contain only the proxy source IPs. +- The proxy must strip or overwrite client-supplied identity and forwarding headers. +- `gateway.auth.trustedProxy.allowUsers` should list expected users when the proxy serves more than one audience. +- Same-host loopback proxy mode should use `allowLoopback` only when local processes are trusted and the proxy owns the identity headers. + +Run `openclaw security audit --deep` after proxy changes. Trusted-proxy findings +are intentionally high-signal because the proxy becomes the authentication +boundary. + +## Tool and sandbox review + +Before exposing an agent to remote senders: + +- Confirm which sessions run on host versus sandbox. +- Deny or require approval for host exec. +- Keep elevated tools disabled unless a specific, trusted sender needs them. +- Avoid browser, canvas, node, cron, gateway, and session-spawn tools for open or semi-open messaging surfaces. +- Keep bind mounts narrow and avoid credential, home, Docker socket, and system paths. +- Use separate gateways, OS users, or hosts for materially different trust boundaries. + +If remote users are not fully trusted, isolation must come from separate +deployments, not only from prompts or session labels. + +## Post-change validation + +After each exposure change: + +1. Re-run `openclaw security audit --deep`. +2. Test a successful authorized connection. +3. Test that an unauthorized sender or browser session is denied. +4. Confirm logs redact secrets. +5. Confirm DM/group routing reaches only the intended agent. +6. Confirm high-impact tools ask for approval or are denied. +7. Document the accepted residual warnings. + +Do not proceed to the next exposure change until the current one is understood. + +## Rollback plan + +If the Gateway may be overexposed: + +```json5 +{ + gateway: { + bind: "loopback", + }, + channels: { + whatsapp: { dmPolicy: "disabled" }, + telegram: { dmPolicy: "disabled" }, + discord: { dmPolicy: "disabled" }, + slack: { dmPolicy: "disabled" }, + }, + tools: { + exec: { security: "deny", ask: "always" }, + elevated: { enabled: false }, + }, +} +``` + +Then: + +1. Stop public forwarding, Tailscale Funnel, or reverse proxy routes. +2. Rotate Gateway tokens/passwords and affected integration credentials. +3. Remove `"*"` and unexpected senders from allowlists. +4. Review recent audit logs, run history, tool calls, and config changes. +5. Re-run `openclaw security audit --deep`. +6. Re-enable access with the narrowest pattern that satisfies the workflow. + +## Review checklist + +- Gateway remains loopback-only unless there is a documented reason. +- Non-loopback access has auth, firewalling, and no public direct route. +- Trusted-proxy deployments have strict proxy IPs and header controls. +- DMs use pairing or allowlists, not open access by default. +- Groups require mentions or explicit allowlists. +- Shared channels do not reach personal credentials. +- Non-main sessions run in sandbox mode. +- Host exec and elevated tools are denied or approval-gated. +- Logs redact secrets. +- Critical audit findings are resolved. +- Rollback steps are tested and documented. diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 33bd4058af8a..2d58f31fdac6 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -25,6 +25,10 @@ OpenClaw security guidance assumes a **personal assistant** deployment: one trus This page explains hardening **within that model**. It does not claim hostile multi-tenant isolation on one shared gateway. +Before changing remote access, DM policy, reverse proxy, or public exposure, +use the [Gateway exposure runbook](/gateway/security/exposure-runbook) as a +pre-flight and rollback checklist. + ## Quick check: `openclaw security audit` See also: [Formal Verification (Security Models)](/security/formal-verification) diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md index 8340cd1715e6..6687603a085b 100644 --- a/docs/help/faq-first-run.md +++ b/docs/help/faq-first-run.md @@ -534,7 +534,7 @@ and troubleshooting see the main [FAQ](/help/faq). Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai), [Qwen Cloud](/providers/qwen), - [MiniMax](/providers/minimax), [GLM Models](/providers/glm), + [MiniMax](/providers/minimax), [Z.AI (GLM)](/providers/zai), [Local models](/gateway/local-models), [Models](/concepts/models). @@ -561,7 +561,7 @@ and troubleshooting see the main [FAQ](/help/faq). safer, more predictable choice. If you want other subscription-style hosted options in OpenClaw, see [OpenAI](/providers/openai), [Qwen / Model Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [GLM - Models](/providers/glm). + Models](/providers/zai). diff --git a/docs/install/upstash.md b/docs/install/upstash.md new file mode 100644 index 000000000000..6fe8211f6e3c --- /dev/null +++ b/docs/install/upstash.md @@ -0,0 +1,96 @@ +--- +summary: "Host OpenClaw on Upstash Box with keep-alive and SSH tunnel access" +read_when: + - Deploying OpenClaw to Upstash Box + - You want a managed Linux environment for OpenClaw with SSH-tunneled dashboard access +title: "Upstash Box" +--- + +Run a persistent OpenClaw Gateway on Upstash Box, a managed Linux environment +with keep-alive lifecycle support. + +Use an SSH tunnel for dashboard access. Do not expose the Gateway port directly +to the public internet. + +## Prerequisites + +- Upstash account +- Keep-alive Upstash Box +- SSH client on your local machine + +## Create a Box + +Create a keep-alive Box in the Upstash Console. Note the Box ID, such as +`right-flamingo-14486`, and your Box API key. + +Upstash maintains its current OpenClaw Box walkthrough at +[OpenClaw Setup](https://upstash.com/docs/box/guides/openclaw-setup). + +## Connect with an SSH tunnel + +Forward the OpenClaw dashboard port to your local machine. Use your Box API key +as the SSH password when prompted: + +```bash +ssh -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -L 18789:127.0.0.1:18789 @us-east-1.box.upstash.com +``` + +The keepalive options reduce idle tunnel drops during onboarding. + +## Install OpenClaw + +Inside the Box: + +```bash +sudo npm install -g openclaw +``` + +## Run onboarding + +```bash +openclaw onboard --install-daemon +``` + +Follow the prompts. Copy the dashboard URL and token when onboarding finishes. + +## Start the Gateway + +Configure the Gateway for the Box network and start it in the background: + +```bash +openclaw config set gateway.bind lan +nohup openclaw gateway > gateway.log 2>&1 & +``` + +With the SSH tunnel active, open the dashboard URL locally: + +```text +http://127.0.0.1:18789/#token= +``` + +## Auto-restart + +Set this command as the Box init script so the Gateway restarts when the Box +starts: + +```bash +nohup openclaw gateway > gateway.log 2>&1 & +``` + +## Troubleshooting + +If SSH freezes during onboarding, reconnect with a clean SSH config and +keepalives: + +```bash +ssh -F /dev/null -o ControlMaster=no -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -L 18789:127.0.0.1:18789 @us-east-1.box.upstash.com +``` + +This bypasses stale local `~/.ssh/config` settings and keeps the tunnel active +through idle network periods. + +## Related + +- [Remote access](/gateway/remote) +- [Gateway security](/gateway/security) +- [Updating OpenClaw](/install/updating) diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index 085d0bb9d3b2..cbd4633d362e 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -121,7 +121,7 @@ Anthropic's current public docs: `anthropic/*` and put the execution backend in provider/model runtime policy. - If you want the clearest billing path, use an Anthropic API key instead. OpenClaw also supports subscription-style options from [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/glm). + If you want the clearest billing path, use an Anthropic API key instead. OpenClaw also supports subscription-style options from [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/zai). diff --git a/docs/providers/glm.md b/docs/providers/glm.md deleted file mode 100644 index 76ebc5f6ace0..000000000000 --- a/docs/providers/glm.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -summary: "GLM model family overview and how to use it in OpenClaw" -read_when: - - You want GLM models in OpenClaw - - You need the model naming convention and setup -title: "GLM (Zhipu)" ---- - -GLM is a model family (not a company) available through the [Z.AI](https://z.ai) platform. In OpenClaw, GLM models are accessed through the bundled `zai` provider with refs like `zai/glm-5.1`. - -| Property | Value | -| ------------------- | --------------------------------------------------------------------------- | -| Provider id | `zai` | -| Plugin | bundled, `enabledByDefault: true` | -| Auth env vars | `ZAI_API_KEY` or `Z_AI_API_KEY` | -| Onboarding choices | `zai-api-key`, `zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn` | -| API | OpenAI-compatible | -| Default base URL | `https://api.z.ai/api/paas/v4` | -| Suggested default | `zai/glm-5.1` | -| Default image model | `zai/glm-4.6v` | - -## Getting started - - - - Pick the onboarding choice that matches your Z.AI plan and region. The generic `zai-api-key` choice auto-detects the matching endpoint from the key shape; use the explicit regional choices when you want to force a specific Coding Plan or general API surface. - - | Auth choice | Best for | - | ------------------- | --------------------------------------------------- | - | `zai-api-key` | Generic API key with endpoint auto-detection | - | `zai-coding-global` | Coding Plan users (global) | - | `zai-coding-cn` | Coding Plan users (China region) | - | `zai-global` | General API (global) | - | `zai-cn` | General API (China region) | - - - -```bash Auto-detect -openclaw onboard --auth-choice zai-api-key -``` - -```bash Coding Plan (global) -openclaw onboard --auth-choice zai-coding-global -``` - -```bash Coding Plan (China) -openclaw onboard --auth-choice zai-coding-cn -``` - -```bash General API (global) -openclaw onboard --auth-choice zai-global -``` - -```bash General API (China) -openclaw onboard --auth-choice zai-cn -``` - - - - - - ```bash - openclaw config set agents.defaults.model.primary "zai/glm-5.1" - ``` - - - ```bash - openclaw models list --provider zai - ``` - - - -## Config example - -```json5 -{ - env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, -} -``` - - - `zai-api-key` lets OpenClaw detect the matching Z.AI endpoint from the key shape and apply the correct base URL automatically. Use the explicit regional choices when you want to pin a specific Coding Plan or general API surface. - - -## Built-in catalog - -The bundled `zai` provider seeds 13 GLM model refs. All entries support reasoning unless marked otherwise; `glm-5v-turbo` and `glm-4.6v` accept image input as well as text. - -| Model ref | Notes | -| -------------------- | -------------------------------------------------- | -| `zai/glm-5.1` | Default model. Reasoning, text only, 202k context. | -| `zai/glm-5` | Reasoning, text only, 202k context. | -| `zai/glm-5-turbo` | Reasoning, text only, 202k context. | -| `zai/glm-5v-turbo` | Reasoning, text + image, 202k context. | -| `zai/glm-4.7` | Reasoning, text only, 204k context. | -| `zai/glm-4.7-flash` | Reasoning, text only, 200k context. | -| `zai/glm-4.7-flashx` | Reasoning, text only. | -| `zai/glm-4.6` | Reasoning, text only. | -| `zai/glm-4.6v` | Reasoning, text + image. Default image model. | -| `zai/glm-4.5` | Reasoning, text only. | -| `zai/glm-4.5-air` | Reasoning, text only. | -| `zai/glm-4.5-flash` | Reasoning, text only. | -| `zai/glm-4.5v` | Reasoning, text + image. | - - - GLM versions and availability can change. Run `openclaw models list --provider zai` to see the catalog rows known to your installed version, and check Z.AI's docs for newly added or deprecated models. - - -## Advanced configuration - - - - When you use the `zai-api-key` auth choice, OpenClaw inspects the key shape to determine the correct Z.AI base URL. Explicit regional choices (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) override auto-detection and pin the endpoint directly. - - - - GLM models are served by the `zai` runtime provider. For full provider configuration, regional endpoints, and additional capabilities, see the [Z.AI provider page](/providers/zai). - - - -## Related - - - - Full Z.AI provider configuration and regional endpoints. - - - Choosing providers, model refs, and failover behavior. - - - `/think` levels for the reasoning-capable GLM family. - - - Auth profiles, switching models, and resolving "no profile" errors. - - diff --git a/docs/providers/index.md b/docs/providers/index.md index e37bd8c4db94..a800de392657 100644 --- a/docs/providers/index.md +++ b/docs/providers/index.md @@ -41,7 +41,6 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi - [fal](/providers/fal) - [Fireworks](/providers/fireworks) - [GitHub Copilot](/providers/github-copilot) -- [GLM models](/providers/glm) - [Google (Gemini)](/providers/google) - [Gradium](/providers/gradium) - [Groq (LPU inference)](/providers/groq) @@ -76,7 +75,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi - [Vydra](/providers/vydra) - [xAI](/providers/xai) - [Xiaomi](/providers/xiaomi) -- [Z.AI](/providers/zai) +- [Z.AI (GLM)](/providers/zai) ## Shared overview pages diff --git a/docs/providers/models.md b/docs/providers/models.md index a96cd76d47a8..2b0eeff9099e 100644 --- a/docs/providers/models.md +++ b/docs/providers/models.md @@ -32,7 +32,6 @@ model as `provider/model`. - [DeepInfra](/providers/deepinfra) - [fal](/providers/fal) - [Fireworks](/providers/fireworks) -- [GLM models](/providers/glm) - [MiniMax](/providers/minimax) - [Mistral](/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) @@ -47,7 +46,7 @@ model as `provider/model`. - [Vercel AI Gateway](/providers/vercel-ai-gateway) - [Venice (Venice AI)](/providers/venice) - [xAI](/providers/xai) -- [Z.AI](/providers/zai) +- [Z.AI (GLM)](/providers/zai) ## Additional provider variants diff --git a/docs/providers/zai.md b/docs/providers/zai.md index 165195434d47..772de6af8310 100644 --- a/docs/providers/zai.md +++ b/docs/providers/zai.md @@ -6,19 +6,26 @@ read_when: title: "Z.AI" --- -Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and uses API keys -for authentication. Create your API key in the Z.AI console. OpenClaw uses the `zai` provider -with a Z.AI API key. +Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and +uses API keys for authentication. Create your API key in the Z.AI console. +OpenClaw uses the `zai` provider with a Z.AI API key. -- Provider: `zai` -- Auth: `ZAI_API_KEY` -- API: Z.AI Chat Completions (Bearer auth) +| Property | Value | +| -------- | -------------------------------------------- | +| Provider | `zai` | +| Auth | `ZAI_API_KEY` (legacy alias: `Z_AI_API_KEY`) | +| API | Z.AI Chat Completions (Bearer auth) | + +## GLM models + +GLM is a model family, not a separate provider. In OpenClaw, GLM models use +refs such as `zai/glm-5.1`: provider `zai`, model id `glm-5.1`. ## Getting started - **Best for:** most users. OpenClaw detects the matching Z.AI endpoint from the key and applies the correct base URL automatically. + **Best for:** most users. OpenClaw probes supported Z.AI endpoints with your API key and applies the correct base URL automatically. @@ -26,14 +33,6 @@ with a Z.AI API key. openclaw onboard --auth-choice zai-api-key ``` - - ```json5 - { - env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, - } - ``` - ```bash openclaw models list --all --provider zai @@ -62,14 +61,6 @@ with a Z.AI API key. openclaw onboard --auth-choice zai-cn ``` - - ```json5 - { - env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, - } - ``` - ```bash openclaw models list --all --provider zai @@ -80,6 +71,29 @@ with a Z.AI API key. +## Config example + + +`zai-api-key` lets OpenClaw detect the matching Z.AI endpoint from the key and +apply the correct base URL automatically. Use the explicit regional choices when +you want to force a specific Coding Plan or general API surface. + + +```json5 +{ + env: { ZAI_API_KEY: "sk-..." }, + models: { + providers: { + zai: { + // Example value. Onboarding writes the matching baseUrl for your endpoint. + baseUrl: "https://api.z.ai/api/paas/v4", + }, + }, + }, + agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, +} +``` + ## Built-in catalog OpenClaw ships the bundled `zai` provider catalog in the plugin manifest, so read-only @@ -108,9 +122,15 @@ The manifest-backed catalog currently includes: | `zai/glm-4.5v` | | -GLM models are available as `zai/` (example: `zai/glm-5`). The default bundled model ref is `zai/glm-5.1`. +GLM models are available as `zai/` (example: `zai/glm-5`). + +The default bundled model ref is `zai/glm-5.1`. GLM versions and availability +can change; run `openclaw models list --all --provider zai` to see the catalog +known to your installed version. + + ## Advanced configuration @@ -185,8 +205,9 @@ GLM models are available as `zai/` (example: `zai/glm-5`). The default bu - Z.AI uses Bearer auth with your API key. - - The `zai-api-key` onboarding choice auto-detects the matching Z.AI endpoint from the key prefix. + - The `zai-api-key` onboarding choice auto-detects the matching Z.AI endpoint by probing supported endpoints with your key. - Use the explicit regional choices (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) when you want to force a specific API surface. + - The legacy env var `Z_AI_API_KEY` is still accepted; OpenClaw copies it to `ZAI_API_KEY` at startup if `ZAI_API_KEY` is unset. @@ -194,10 +215,10 @@ GLM models are available as `zai/` (example: `zai/glm-5`). The default bu ## Related - - Model family overview for GLM. - Choosing providers, model refs, and failover behavior. + + Full OpenClaw config schema, including provider and model settings. + diff --git a/docs/reference/AGENTS.default.md b/docs/reference/AGENTS.default.md index 7dfe9e8cd833..7f99ae420e78 100644 --- a/docs/reference/AGENTS.default.md +++ b/docs/reference/AGENTS.default.md @@ -67,6 +67,7 @@ cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md - Long-term memory: `MEMORY.md` for durable facts, preferences, and decisions. - Lowercase `memory.md` is legacy repair input only; do not keep both root files on purpose. - On session start, read today + yesterday + `MEMORY.md` when present. +- Before writing memory files, read them first; write only concrete updates, never empty placeholders. - Capture: decisions, preferences, constraints, open loops. - Avoid secrets unless explicitly requested. diff --git a/docs/reference/templates/AGENTS.dev.md b/docs/reference/templates/AGENTS.dev.md index 17a7b75cc4d4..b7f33b717d1e 100644 --- a/docs/reference/templates/AGENTS.dev.md +++ b/docs/reference/templates/AGENTS.dev.md @@ -37,6 +37,7 @@ git commit -m "Add agent workspace" - Keep a short daily log at memory/YYYY-MM-DD.md (create memory/ if needed). - On session start, read today + yesterday if present. +- Before writing memory files, read them first; write only concrete updates, never empty placeholders. - Capture durable facts, preferences, and decisions; avoid secrets. ## Heartbeats (optional) diff --git a/docs/reference/templates/AGENTS.md b/docs/reference/templates/AGENTS.md index d2053ebb5ec3..6a6f958f262d 100644 --- a/docs/reference/templates/AGENTS.md +++ b/docs/reference/templates/AGENTS.md @@ -52,6 +52,7 @@ Capture what matters. Decisions, context, things to remember. Skip the secrets u - **Memory is limited** — if you want to remember something, WRITE IT TO A FILE - "Mental notes" don't survive session restarts. Files do. +- Before writing memory files, read them first; write only concrete updates, never empty placeholders. - When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file - When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant skill - When you make a mistake → document it so future-you doesn't repeat it diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md index 747c8ab9046a..ca10ac5f191a 100644 --- a/docs/start/openclaw.md +++ b/docs/start/openclaw.md @@ -196,7 +196,7 @@ Inbound attachments (images/audio/docs) can be surfaced to your command via temp - `{{MediaUrl}}` (pseudo-URL) - `{{Transcript}}` (if audio transcription is enabled) -Outbound attachments from the agent: include `MEDIA:` on its own line (no spaces). Example: +Outbound attachments from the agent: include `MEDIA:` on its own line (no spaces). The directive must start the line as plain text, outside code fences and without Markdown wrappers such as bold or inline code. Example: ``` Here's the screenshot. @@ -205,6 +205,14 @@ MEDIA:https://example.com/screenshot.png OpenClaw extracts these and sends them as media alongside the text. +These forms are not attachment directives and are sent as normal text: + +```md +**MEDIA:https://example.com/screenshot.png** +`MEDIA:https://example.com/screenshot.png` +Here is the screenshot: MEDIA:https://example.com/screenshot.png +``` + Local-path behavior follows the same file-read trust model as the agent: - If `tools.fs.workspaceOnly` is `true`, outbound `MEDIA:` local paths stay restricted to the OpenClaw temp root, the media cache, agent workspace paths, and sandbox-generated files. diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts index 7f9459b33c0f..610f71dbda9b 100644 --- a/src/agents/system-prompt.ts +++ b/src/agents/system-prompt.ts @@ -422,6 +422,7 @@ function buildAssistantOutputDirectivesSection(params: { return [ "## Assistant Output Directives", "- Attach media: `MEDIA:` on its own line.", + " The MEDIA directive must start the line as plain text, outside code fences and without Markdown wrappers. Do not write `**MEDIA:...**`, `` `MEDIA:...` ``, or inline prose like `Here is the file: MEDIA:...`.", "- Voice-note audio hint: `[[audio_as_voice]]` when audio is attached.", "- Native quote/reply: first token `[[reply_to_current]]`; use `[[reply_to:]]` only with an explicit id.", "- Supported directives are stripped before rendering; channel config still decides delivery.",