fengming 0.3.9 → 0.3.11

package/docs/install/render.mdx

@@ -1,167 +0,0 @@
----
-summary: "Deploy OpenClaw on Render with Infrastructure-as-Code"
-read_when:
-  - Deploying OpenClaw to Render
-  - You want a declarative cloud deploy with Render Blueprints
-title: "Render"
----
-
-# Render
-
-Deploy OpenClaw on Render using Infrastructure as Code. The included `render.yaml` Blueprint defines your entire stack declaratively, service, disk, environment variables, so you can deploy with a single click and version your infrastructure alongside your code.
-
-## Prerequisites
-
-- A [Render account](https://render.com) (free tier available)
-- An API key from your preferred [model provider](/providers)
-
-## Deploy with a Render Blueprint
-
-[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
-
-Clicking this link will:
-
-1. Create a new Render service from the `render.yaml` Blueprint at the root of this repo.
-2. Build the Docker image and deploy
-
-Once deployed, your service URL follows the pattern `https://<service-name>.onrender.com`.
-
-## Understanding the Blueprint
-
-Render Blueprints are YAML files that define your infrastructure. The `render.yaml` in this
-repository configures everything needed to run OpenClaw:
-
-```yaml
-services:
-  - type: web
-    name: openclaw
-    runtime: docker
-    plan: starter
-    healthCheckPath: /health
-    envVars:
-      - key: OPENCLAW_GATEWAY_PORT
-        value: "8080"
-      - key: OPENCLAW_STATE_DIR
-        value: /data/.openclaw
-      - key: OPENCLAW_WORKSPACE_DIR
-        value: /data/workspace
-      - key: OPENCLAW_GATEWAY_TOKEN
-        generateValue: true # auto-generates a secure token
-    disk:
-      name: openclaw-data
-      mountPath: /data
-      sizeGB: 1
-```
-
-Key Blueprint features used:
-
-| Feature               | Purpose                                                    |
-| --------------------- | ---------------------------------------------------------- |
-| `runtime: docker`     | Builds from the repo's Dockerfile                          |
-| `healthCheckPath`     | Render monitors `/health` and restarts unhealthy instances |
-| `generateValue: true` | Auto-generates a cryptographically secure value            |
-| `disk`                | Persistent storage that survives redeploys                 |
-
-## Choosing a plan
-
-| Plan      | Spin-down         | Disk          | Best for                      |
-| --------- | ----------------- | ------------- | ----------------------------- |
-| Free      | After 15 min idle | Not available | Testing, demos                |
-| Starter   | Never             | 1GB+          | Personal use, small teams     |
-| Standard+ | Never             | 1GB+          | Production, multiple channels |
-
-The Blueprint defaults to `starter`. To use free tier, change `plan: free` in
-your fork's `render.yaml` (but note: no persistent disk means OpenClaw state
-resets on each deploy).
-
-## After deployment
-
-### Access the Control UI
-
-The web dashboard is available at `https://<your-service>.onrender.com/`.
-
-Connect using the configured shared secret. This deploy template auto-generates
-`OPENCLAW_GATEWAY_TOKEN` (find it in **Dashboard → your service →
-Environment**); if you replace it with password auth, use that password
-instead.
-
-## Render Dashboard features
-
-### Logs
-
-View real-time logs in **Dashboard → your service → Logs**. Filter by:
-
-- Build logs (Docker image creation)
-- Deploy logs (service startup)
-- Runtime logs (application output)
-
-### Shell access
-
-For debugging, open a shell session via **Dashboard → your service → Shell**. The persistent disk is mounted at `/data`.
-
-### Environment variables
-
-Modify variables in **Dashboard → your service → Environment**. Changes trigger an automatic redeploy.
-
-### Auto-deploy
-
-If you use the original OpenClaw repository, Render will not auto-deploy your OpenClaw. To update it, run a manual Blueprint sync from the dashboard.
-
-## Custom domain
-
-1. Go to **Dashboard → your service → Settings → Custom Domains**
-2. Add your domain
-3. Configure DNS as instructed (CNAME to `*.onrender.com`)
-4. Render provisions a TLS certificate automatically
-
-## Scaling
-
-Render supports horizontal and vertical scaling:
-
-- **Vertical**: Change the plan to get more CPU/RAM
-- **Horizontal**: Increase instance count (Standard plan and above)
-
-For OpenClaw, vertical scaling is usually sufficient. Horizontal scaling requires sticky sessions or external state management.
-
-## Backups and migration
-
-Export your state, config, auth profiles, and workspace at any time using the
-shell access in the Render Dashboard:
-
-```bash
-openclaw backup create
-```
-
-This creates a portable backup archive with OpenClaw state plus any configured
-workspace. See [Backup](/cli/backup) for details.
-
-## Troubleshooting
-
-### Service will not start
-
-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` is set so the gateway binds to the port Render expects
-
-### Slow cold starts (free tier)
-
-Free tier services spin down after 15 minutes of inactivity. The first request after spin-down takes a few seconds while the container starts. Upgrade to Starter plan for always-on.
-
-### Data loss after redeploy
-
-This happens on free tier (no persistent disk). Upgrade to a paid plan, or
-regularly export a full backup via `openclaw backup create` in the Render shell.
-
-### Health check failures
-
-Render expects a 200 response from `/health` within 30 seconds. If builds succeed but deploys fail, the service may be taking too long to start. Check:
-
-- Build logs for errors
-- Whether the container runs locally with `docker build && docker run`
-
-## Next steps
-
-- Set up messaging channels: [Channels](/channels)
-- Configure the Gateway: [Gateway configuration](/gateway/configuration)
-- Keep OpenClaw up to date: [Updating](/install/updating)

package/docs/install/uninstall.md

@@ -1,131 +0,0 @@
----
-summary: "Uninstall FengMing completely (CLI, service, state, workspace)"
-read_when:
-  - You want to remove FengMing from a machine
-  - The gateway service is still running after uninstall
-title: "Uninstall"
----
-
-Two paths:
-
-- **Easy path** if `fengming` is still installed.
-- **Manual service removal** if the CLI is gone but the service is still running.
-
-## Easy path (CLI still installed)
-
-Recommended: use the built-in uninstaller:
-
-```bash
-fengming uninstall
-```
-
-Non-interactive (automation / npx):
-
-```bash
-fengming uninstall --all --yes --non-interactive
-npx -y fengming uninstall --all --yes --non-interactive
-```
-
-Manual steps (same result):
-
-1. Stop the gateway service:
-
-```bash
-fengming gateway stop
-```
-
-2. Uninstall the gateway service (launchd/systemd/schtasks):
-
-```bash
-fengming gateway uninstall
-```
-
-3. Delete state + config:
-
-```bash
-rm -rf "${FENGMING_STATE_DIR:-$HOME/.fengming}"
-```
-
-If you set `FENGMING_CONFIG_PATH` to a custom location outside the state dir, delete that file too.
-
-4. Delete your workspace (optional, removes agent files):
-
-```bash
-rm -rf ~/.fengming/workspace
-```
-
-5. Remove the CLI install (pick the one you used):
-
-```bash
-npm rm -g fengming
-pnpm remove -g fengming
-bun remove -g fengming
-```
-
-6. If you installed the macOS app:
-
-```bash
-rm -rf /Applications/FengMing.app
-```
-
-Notes:
-
-- If you used profiles (`--profile` / `FENGMING_PROFILE`), repeat step 3 for each state dir (defaults are `~/.fengming-<profile>`).
-- In remote mode, the state dir lives on the **gateway host**, so run steps 1-4 there too.
-
-## Manual service removal (CLI not installed)
-
-Use this if the gateway service keeps running but `fengming` is missing.
-
-### macOS (launchd)
-
-Default label is `ai.fengming.gateway` (or `ai.fengming.<profile>`; legacy `com.fengming.*` may still exist):
-
-```bash
-launchctl bootout gui/$UID/ai.fengming.gateway
-rm -f ~/Library/LaunchAgents/ai.fengming.gateway.plist
-```
-
-If you used a profile, replace the label and plist name with `ai.fengming.<profile>`. Remove any legacy `com.fengming.*` plists if present.
-
-### Linux (systemd user unit)
-
-Default unit name is `fengming-gateway.service` (or `fengming-gateway-<profile>.service`):
-
-```bash
-systemctl --user disable --now fengming-gateway.service
-rm -f ~/.config/systemd/user/fengming-gateway.service
-systemctl --user daemon-reload
-```
-
-### Windows (Scheduled Task)
-
-Default task name is `FengMing Gateway` (or `FengMing Gateway (<profile>)`).
-The task script lives under your state dir.
-
-```powershell
-schtasks /Delete /F /TN "FengMing Gateway"
-Remove-Item -Force "$env:USERPROFILE\.fengming\gateway.cmd"
-```
-
-If you used a profile, delete the matching task name and `~\.fengming-<profile>\gateway.cmd`.
-
-## Normal install vs source checkout
-
-### Normal install (install.sh / npm / pnpm / bun)
-
-If you used `https://fengming.ai/install.sh` or `install.ps1`, the CLI was installed with `npm install -g fengming@latest`.
-Remove it with `npm rm -g fengming` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
-
-### Source checkout (git clone)
-
-If you run from a repo checkout (`git clone` + `fengming ...` / `bun run fengming ...`):
-
-1. Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
-2. Delete the repo directory.
-3. Remove state + workspace as shown above.
-
-## Related
-
-- [Install overview](/install)
-- [Migration guide](/install/migrating)

package/docs/install/updating.md

@@ -1,284 +0,0 @@
----
-summary: "Updating FengMing safely (global install or source), plus rollback strategy"
-read_when:
-  - Updating FengMing
-  - Something breaks after an update
-title: "Updating"
----
-
-Keep FengMing up to date.
-
-## Recommended: `fengming update`
-
-The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `fengming doctor`, and restarts the gateway.
-
-```bash
-fengming update
-```
-
-To switch channels or target a specific version:
-
-```bash
-fengming update --channel beta
-fengming update --channel dev
-fengming update --dry-run   # preview without applying
-```
-
-`fengming update` does not accept `--verbose`. For update diagnostics, use
-`--dry-run` to preview the planned actions, `--json` for structured results, or
-`fengming update status --json` to inspect channel and availability state. The
-installer has its own `--verbose` flag, but that flag is not part of
-`fengming update`.
-
-`--channel beta` prefers beta, but the runtime falls back to stable/latest when
-the beta tag is missing or older than the latest stable release. Use `--tag beta`
-if you want the raw npm beta dist-tag for a one-off package update.
-
-Use `--channel dev` for a persistent moving GitHub `main` checkout. For package
-updates, `--tag main` maps to `github:fengming/fengming#main` for one run, and
-GitHub/git source specs are packed into a temporary tarball before the staged
-npm install.
-
-For managed plugins, beta-channel fallback is a warning: the core update can
-still succeed while a plugin uses its recorded default/latest release because no
-plugin beta is available.
-
-See [Development channels](/install/development-channels) for channel semantics.
-
-## Switch between npm and git installs
-
-Use channels when you want to change the install type. The updater keeps your
-state, config, credentials, and workspace in `~/.fengming`; it only changes
-which FengMing code install the CLI and gateway use.
-
-```bash
-# npm package install -> editable git checkout
-fengming update --channel dev
-
-# git checkout -> npm package install
-fengming update --channel stable
-```
-
-Run with `--dry-run` first to preview the exact install-mode switch:
-
-```bash
-fengming update --channel dev --dry-run
-fengming update --channel stable --dry-run
-```
-
-The `dev` channel ensures a git checkout, builds it, and installs the global CLI
-from that checkout. The `stable` and `beta` channels use package installs. If the
-gateway is already installed, `fengming update` refreshes the service metadata
-and restarts it unless you pass `--no-restart`.
-
-For package installs with a managed Gateway service, `fengming update` targets
-the package root used by that service. If the shell `fengming` command comes
-from a different install, the updater prints both roots and the managed service
-Node path. The package update uses the package manager that owns the service
-root and checks the managed service Node against the target release engine
-before replacing the package.
-
-## Alternative: re-run the installer
-
-```bash
-curl -fsSL https://fengming.ai/install.sh | bash
-```
-
-Add `--no-onboard` to skip onboarding. To force a specific install type through
-the installer, pass `--install-method git --no-onboard` or
-`--install-method npm --no-onboard`.
-
-If `fengming update` fails after the npm package install phase, re-run the
-installer. The installer does not call the old updater; it runs the global
-package install directly and can recover a partially updated npm install.
-
-```bash
-curl -fsSL https://fengming.ai/install.sh | bash -s -- --install-method npm
-```
-
-To pin the recovery to a specific version or dist-tag, add `--version`:
-
-```bash
-curl -fsSL https://fengming.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
-```
-
-## Alternative: manual npm, pnpm, or bun
-
-```bash
-npm i -g fengming@latest
-```
-
-Prefer `fengming update` for supervised installs because it can coordinate the
-package swap with the running Gateway service. If you update manually on a
-supervised install, stop the managed Gateway before the package manager starts.
-Package managers replace files in place, and a running Gateway can otherwise try
-to load core or plugin files while the package tree is temporarily half-swapped.
-Restart the Gateway after the package manager finishes so the service picks up
-the new install.
-
-For a root-owned Linux system-global install, if `fengming update` fails with
-`EACCES` and you recover with system npm, keep the Gateway stopped through the
-manual package replacement. Use the same `fengming` profile flags or environment
-you normally use for that Gateway. Replace `/usr/bin/npm` with the system npm
-that owns the root-owned global prefix on your host:
-
-```bash
-fengming gateway stop
-sudo /usr/bin/npm i -g fengming@latest
-fengming gateway install --force
-fengming gateway restart
-```
-
-Then verify the service:
-
-```bash
-fengming --version
-curl -fsS http://127.0.0.1:18789/readyz
-fengming plugins list --json
-fengming gateway status --deep --json
-fengming doctor --lint --json
-```
-
-When `fengming update` manages a global npm install, it installs the target into
-a temporary npm prefix first, verifies the packaged `dist` inventory, then swaps
-the clean package tree into the real global prefix. That avoids npm overlaying a
-new package onto stale files from the old package. If the install command fails,
-FengMing retries once with `--omit=optional`. That retry helps hosts where native
-optional dependencies cannot compile, while keeping the original failure visible
-if the fallback also fails.
-
-FengMing-managed npm update and plugin-update commands also clear npm
-`min-release-age` quarantine for the child npm process. npm may report that
-policy as a derived `before` cutoff; both are useful for general supply-chain
-quarantine policies, but an explicit FengMing update means "install the selected
-FengMing release now."
-
-```bash
-pnpm add -g fengming@latest
-```
-
-```bash
-bun add -g fengming@latest
-```
-
-### Advanced npm install topics
-
-<AccordionGroup>
-  <Accordion title="Read-only package tree">
-    FengMing treats packaged global installs as read-only at runtime, even when the global package directory is writable by the current user. Plugin package installs live in FengMing-owned npm/git roots under the user config directory, and Gateway startup does not mutate the FengMing package tree.
-
-    Some Linux npm setups install global packages under root-owned directories such as `/usr/lib/node_modules/fengming`. FengMing supports that layout because plugin install/update commands write outside that global package directory.
-
-  </Accordion>
-  <Accordion title="Hardened systemd units">
-    Give FengMing write access to its config/state roots so explicit plugin installs, plugin updates, and doctor cleanup can persist their changes:
-
-    ```ini
-    ReadWritePaths=/var/lib/fengming /home/fengming/.fengming /tmp
-    ```
-
-  </Accordion>
-  <Accordion title="Disk-space preflight">
-    Before package updates and explicit plugin installs, FengMing tries a best-effort disk-space check for the target volume. Low space produces a warning with the checked path, but does not block the update because filesystem quotas, snapshots, and network volumes can change after the check. The actual package-manager install and post-install verification remain authoritative.
-  </Accordion>
-</AccordionGroup>
-
-## Auto-updater
-
-The auto-updater is off by default. Enable it in `~/.fengming/fengming.json`:
-
-```json5
-{
-  update: {
-    channel: "stable",
-    auto: {
-      enabled: true,
-      stableDelayHours: 6,
-      stableJitterHours: 12,
-      betaCheckIntervalHours: 1,
-    },
-  },
-}
-```
-
-| Channel  | Behavior                                                                                                      |
-| -------- | ------------------------------------------------------------------------------------------------------------- |
-| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
-| `beta`   | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately.                              |
-| `dev`    | No automatic apply. Use `fengming update` manually.                                                           |
-
-The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).
-For downgrade or incident recovery, set `FENGMING_NO_AUTO_UPDATE=1` in the gateway environment to block automatic applies even when `update.auto.enabled` is configured. Startup update hints can still run unless `update.checkOnStart` is also disabled.
-
-Package-manager updates requested through the live Gateway control-plane handler
-do not replace the package tree inside the running Gateway process. On managed
-service installs, the Gateway starts a detached handoff, exits, and lets the
-normal `fengming update --yes --json` CLI path stop the service, replace the
-package, refresh service metadata, restart, verify the Gateway version and
-reachability, and recover an installed-but-unloaded macOS LaunchAgent when
-possible. If the Gateway cannot make that handoff safely, `update.run` reports a
-safe shell command instead of running the package manager in-process.
-
-## After updating
-
-<Steps>
-
-### Run doctor
-
-```bash
-fengming doctor
-```
-
-Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)
-
-### Restart the gateway
-
-```bash
-fengming gateway restart
-```
-
-### Verify
-
-```bash
-fengming health
-```
-
-</Steps>
-
-## Rollback
-
-### Pin a version (npm)
-
-```bash
-npm i -g fengming@<version>
-fengming doctor
-fengming gateway restart
-```
-
-<Tip>
-`npm view fengming version` shows the current published version.
-</Tip>
-
-### Pin a commit (source)
-
-```bash
-git fetch origin
-git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
-pnpm install && pnpm build
-fengming gateway restart
-```
-
-To return to latest: `git checkout main && git pull`.
-
-## If you are stuck
-
-- Run `fengming doctor` again and read the output carefully.
-- For `fengming update --channel dev` on source checkouts, the updater auto-bootstraps `pnpm` when needed. If you see a pnpm/corepack bootstrap error, install `pnpm` manually (or re-enable `corepack`) and rerun the update.
-- Check: [Troubleshooting](/gateway/troubleshooting)
-- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
-
-## Related
-
-- [Install overview](/install): all installation methods.
-- [Doctor](/gateway/doctor): health checks after updates.
-- [Migrating](/install/migrating): major version migration guides.

package/docs/install/upstash.md

@@ -1,96 +0,0 @@
----
-summary: "Host FengMing on Upstash Box with keep-alive and SSH tunnel access"
-read_when:
-  - Deploying FengMing to Upstash Box
-  - You want a managed Linux environment for FengMing with SSH-tunneled dashboard access
-title: "Upstash Box"
----
-
-Run a persistent FengMing 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 FengMing Box walkthrough at
-[FengMing Setup](https://upstash.com/docs/box/guides/fengming-setup).
-
-## Connect with an SSH tunnel
-
-Forward the FengMing 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 FengMing
-
-Inside the Box:
-
-```bash
-sudo npm install -g fengming
-```
-
-## Run onboarding
-
-```bash
-fengming 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
-fengming config set gateway.bind lan
-nohup fengming 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 fengming 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 FengMing](/install/updating)