mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-12 21:53:00 -06:00
docs: absorb maintainer docs sweep
Co-authored-by: Bob Du <i@bobdu.cc> Co-authored-by: alitariksahin <alitariksah@gmail.com> Co-authored-by: Jefsky <hwj3344@hotmail.com> Co-authored-by: Musaab Hasan <m9.3b@Hotmail.com> Co-authored-by: Intern Dev <dev@wukongai.io> Co-authored-by: majin.nathan <majin.nathan@bytedance.com>
This commit is contained in:
Peter Steinberger
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -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",
|
||||
|
||||
+28
@@ -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.
|
||||
|
||||
@@ -177,7 +177,7 @@ Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so Ope
|
||||
### Other subscription-style hosted options
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="GLM models" href="/providers/glm">
|
||||
<Card title="Z.AI (GLM)" href="/providers/zai">
|
||||
Z.AI Coding Plan or general API endpoints.
|
||||
</Card>
|
||||
<Card title="MiniMax" href="/providers/minimax">
|
||||
|
||||
@@ -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).
|
||||
</Warning>
|
||||
|
||||
OpenClaw also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and `claude -p` when available.
|
||||
|
||||
+8
-3
@@ -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",
|
||||
|
||||
@@ -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
|
||||
---
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
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.
|
||||
@@ -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)
|
||||
|
||||
@@ -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).
|
||||
|
||||
</Accordion>
|
||||
@@ -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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
@@ -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 <box-id>@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=<your-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 <box-id>@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)
|
||||
@@ -121,7 +121,7 @@ Anthropic's current public docs:
|
||||
`anthropic/*` and put the execution backend in provider/model runtime policy.
|
||||
|
||||
<Tip>
|
||||
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).
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
@@ -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
|
||||
|
||||
<Steps>
|
||||
<Step title="Choose an auth route and run onboarding">
|
||||
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) |
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Step>
|
||||
<Step title="Set GLM as the default model">
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary "zai/glm-5.1"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify models are available">
|
||||
```bash
|
||||
openclaw models list --provider zai
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Config example
|
||||
|
||||
```json5
|
||||
{
|
||||
env: { ZAI_API_KEY: "sk-..." },
|
||||
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
|
||||
}
|
||||
```
|
||||
|
||||
<Tip>
|
||||
`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.
|
||||
</Tip>
|
||||
|
||||
## 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. |
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Advanced configuration
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Endpoint auto-detection">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider details">
|
||||
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).
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Z.AI provider" href="/providers/zai" icon="server">
|
||||
Full Z.AI provider configuration and regional endpoints.
|
||||
</Card>
|
||||
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
|
||||
Choosing providers, model refs, and failover behavior.
|
||||
</Card>
|
||||
<Card title="Thinking modes" href="/tools/thinking" icon="brain">
|
||||
`/think` levels for the reasoning-capable GLM family.
|
||||
</Card>
|
||||
<Card title="Models FAQ" href="/help/faq-models" icon="circle-question">
|
||||
Auth profiles, switching models, and resolving "no profile" errors.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+49
-28
@@ -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
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Auto-detect endpoint">
|
||||
**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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Run onboarding">
|
||||
@@ -26,14 +33,6 @@ with a Z.AI API key.
|
||||
openclaw onboard --auth-choice zai-api-key
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set a default model">
|
||||
```json5
|
||||
{
|
||||
env: { ZAI_API_KEY: "sk-..." },
|
||||
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify the model is listed">
|
||||
```bash
|
||||
openclaw models list --all --provider zai
|
||||
@@ -62,14 +61,6 @@ with a Z.AI API key.
|
||||
openclaw onboard --auth-choice zai-cn
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set a default model">
|
||||
```json5
|
||||
{
|
||||
env: { ZAI_API_KEY: "sk-..." },
|
||||
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify the model is listed">
|
||||
```bash
|
||||
openclaw models list --all --provider zai
|
||||
@@ -80,6 +71,29 @@ with a Z.AI API key.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Config example
|
||||
|
||||
<Tip>
|
||||
`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.
|
||||
</Tip>
|
||||
|
||||
```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` | |
|
||||
|
||||
<Tip>
|
||||
GLM models are available as `zai/<model>` (example: `zai/glm-5`). The default bundled model ref is `zai/glm-5.1`.
|
||||
GLM models are available as `zai/<model>` (example: `zai/glm-5`).
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Advanced configuration
|
||||
|
||||
<AccordionGroup>
|
||||
@@ -185,8 +205,9 @@ GLM models are available as `zai/<model>` (example: `zai/glm-5`). The default bu
|
||||
|
||||
<Accordion title="Auth details">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@@ -194,10 +215,10 @@ GLM models are available as `zai/<model>` (example: `zai/glm-5`). The default bu
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="GLM model family" href="/providers/glm" icon="microchip">
|
||||
Model family overview for GLM.
|
||||
</Card>
|
||||
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
|
||||
Choosing providers, model refs, and failover behavior.
|
||||
</Card>
|
||||
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
|
||||
Full OpenClaw config schema, including provider and model settings.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:<path-or-url>` on its own line (no spaces). Example:
|
||||
Outbound attachments from the agent: include `MEDIA:<path-or-url>` 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.
|
||||
|
||||
@@ -422,6 +422,7 @@ function buildAssistantOutputDirectivesSection(params: {
|
||||
return [
|
||||
"## Assistant Output Directives",
|
||||
"- Attach media: `MEDIA:<path-or-url>` 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:<id>]]` only with an explicit id.",
|
||||
"- Supported directives are stripped before rendering; channel config still decides delivery.",
|
||||
|
||||
Reference in New Issue
Block a user