fengming 0.3.10 → 0.3.11

package/docs/install/podman.md

@@ -1,216 +0,0 @@
----
-summary: "Run FengMing in a rootless Podman container"
-read_when:
-  - You want a containerized gateway with Podman instead of Docker
-title: "Podman"
----
-
-Run the FengMing Gateway in a rootless Podman container, managed by your current non-root user.
-
-The intended model is:
-
-- Podman runs the gateway container.
-- Your host `fengming` CLI is the control plane.
-- Persistent state lives on the host under `~/.fengming` by default.
-- Day-to-day management uses `fengming --container <name> ...` instead of `sudo -u fengming`, `podman exec`, or a separate service user.
-
-## Prerequisites
-
-- **Podman** in rootless mode
-- **FengMing CLI** installed on the host
-- **Optional:** `systemd --user` if you want Quadlet-managed auto-start
-- **Optional:** `sudo` only if you want `loginctl enable-linger "$(whoami)"` for boot persistence on a headless host
-
-## Quick start
-
-<Steps>
-  <Step title="One-time setup">
-    From the repo root, run `./scripts/podman/setup.sh`.
-  </Step>
-
-  <Step title="Start the Gateway container">
-    Start the container with `./scripts/run-fengming-podman.sh launch`.
-  </Step>
-
-  <Step title="Run onboarding inside the container">
-    Run `./scripts/run-fengming-podman.sh launch setup`, then open `http://127.0.0.1:18789/`.
-  </Step>
-
-  <Step title="Manage the running container from the host CLI">
-    Set `FENGMING_CONTAINER=fengming`, then use normal `fengming` commands from the host.
-  </Step>
-</Steps>
-
-Setup details:
-
-- `./scripts/podman/setup.sh` builds `fengming:local` in your rootless Podman store by default, or uses `FENGMING_IMAGE` / `FENGMING_PODMAN_IMAGE` if you set one.
-- It creates `~/.fengming/fengming.json` with `gateway.mode: "local"` if missing.
-- It creates `~/.fengming/.env` with `FENGMING_GATEWAY_TOKEN` if missing.
-- For manual launches, the helper reads only a small allowlist of Podman-related keys from `~/.fengming/.env` and passes explicit runtime env vars to the container; it does not hand the full env file to Podman.
-
-Quadlet-managed setup:
-
-```bash
-./scripts/podman/setup.sh --quadlet
-```
-
-Quadlet is a Linux-only option because it depends on systemd user services.
-
-You can also set `FENGMING_PODMAN_QUADLET=1`.
-
-Optional build/setup env vars:
-
-- `FENGMING_IMAGE` or `FENGMING_PODMAN_IMAGE` -- use an existing/pulled image instead of building `fengming:local`
-- `FENGMING_IMAGE_APT_PACKAGES` -- install extra apt packages during image build (also accepts legacy `FENGMING_DOCKER_APT_PACKAGES`)
-- `FENGMING_IMAGE_PIP_PACKAGES` -- install extra Python packages during image build; pin versions and use only package indexes you trust
-- `FENGMING_EXTENSIONS` -- pre-install plugin dependencies at build time
-- `FENGMING_INSTALL_BROWSER` -- pre-install Chromium and Xvfb for browser automation (set to `1` to enable)
-
-Container start:
-
-```bash
-./scripts/run-fengming-podman.sh launch
-```
-
-The script starts the container as your current uid/gid with `--userns=keep-id` and bind-mounts your FengMing state into the container.
-
-Onboarding:
-
-```bash
-./scripts/run-fengming-podman.sh launch setup
-```
-
-Then open `http://127.0.0.1:18789/` and use the token from `~/.fengming/.env`.
-
-Model auth in Podman:
-
-- Use FengMing-managed auth during setup: Anthropic API keys for Anthropic, or OpenAI Codex browser OAuth/device-code auth for Codex-backed OpenAI.
-- The Podman launcher does not mount host CLI credential homes such as `~/.claude` or `~/.codex` into the setup or gateway container.
-- Existing host CLI logins are same-host convenience paths. For container installs, keep provider auth in the mounted `~/.fengming` state that setup manages.
-
-Host CLI default:
-
-```bash
-export FENGMING_CONTAINER=fengming
-```
-
-Then commands such as these will run inside that container automatically:
-
-```bash
-fengming dashboard --no-open
-fengming gateway status --deep   # includes extra service scan
-fengming doctor
-fengming channels login
-```
-
-On macOS, Podman machine may make the browser appear non-local to the gateway.
-If the Control UI reports device-auth errors after launch, use the Tailscale guidance in
-[Podman and Tailscale](#podman--tailscale).
-
-<a id="podman--tailscale"></a>
-
-## Podman and Tailscale
-
-For HTTPS or remote browser access, follow the main Tailscale docs.
-
-Podman-specific note:
-
-- Keep the Podman publish host at `127.0.0.1`.
-- Prefer host-managed `tailscale serve` over `fengming gateway --tailscale serve`.
-- On macOS, if local browser device-auth context is unreliable, use Tailscale access instead of ad hoc local tunnel workarounds.
-
-See:
-
-- [Tailscale](/gateway/tailscale)
-- [Control UI](/web/control-ui)
-
-## Systemd (Quadlet, optional)
-
-If you ran `./scripts/podman/setup.sh --quadlet`, setup installs a Quadlet file at:
-
-```bash
-~/.config/containers/systemd/fengming.container
-```
-
-Useful commands:
-
-- **Start:** `systemctl --user start fengming.service`
-- **Stop:** `systemctl --user stop fengming.service`
-- **Status:** `systemctl --user status fengming.service`
-- **Logs:** `journalctl --user -u fengming.service -f`
-
-After editing the Quadlet file:
-
-```bash
-systemctl --user daemon-reload
-systemctl --user restart fengming.service
-```
-
-For boot persistence on SSH/headless hosts, enable lingering for your current user:
-
-```bash
-sudo loginctl enable-linger "$(whoami)"
-```
-
-## Config, env, and storage
-
-- **Config dir:** `~/.fengming`
-- **Workspace dir:** `~/.fengming/workspace`
-- **Token file:** `~/.fengming/.env`
-- **Launch helper:** `./scripts/run-fengming-podman.sh`
-
-The launch script and Quadlet bind-mount host state into the container:
-
-- `FENGMING_CONFIG_DIR` -> `/home/node/.fengming`
-- `FENGMING_WORKSPACE_DIR` -> `/home/node/.fengming/workspace`
-
-By default those are host directories, not anonymous container state, so
-`fengming.json`, per-agent `auth-profiles.json`, channel/provider state,
-sessions, and workspace survive container replacement.
-The Podman setup also seeds `gateway.controlUi.allowedOrigins` for `127.0.0.1` and `localhost` on the published gateway port so the local dashboard works with the container's non-loopback bind.
-
-Useful env vars for the manual launcher:
-
-- `FENGMING_PODMAN_CONTAINER` -- container name (`fengming` by default)
-- `FENGMING_PODMAN_IMAGE` / `FENGMING_IMAGE` -- image to run
-- `FENGMING_PODMAN_GATEWAY_HOST_PORT` -- host port mapped to container `18789`
-- `FENGMING_PODMAN_BRIDGE_HOST_PORT` -- host port mapped to container `18790`
-- `FENGMING_PODMAN_PUBLISH_HOST` -- host interface for published ports; default is `127.0.0.1`
-- `FENGMING_GATEWAY_BIND` -- gateway bind mode inside the container; default is `lan`
-- `FENGMING_PODMAN_USERNS` -- `keep-id` (default), `auto`, or `host`
-
-The manual launcher reads `~/.fengming/.env` before finalizing container/image defaults, so you can persist these there.
-
-If you use a non-default `FENGMING_CONFIG_DIR` or `FENGMING_WORKSPACE_DIR`, set the same variables for both `./scripts/podman/setup.sh` and later `./scripts/run-fengming-podman.sh launch` commands. The repo-local launcher does not persist custom path overrides across shells.
-
-Quadlet note:
-
-- The generated Quadlet service intentionally keeps a fixed, hardened default shape: `127.0.0.1` published ports, `--bind lan` inside the container, and `keep-id` user namespace.
-- It pins `FENGMING_NO_RESPAWN=1`, `Restart=on-failure`, and `TimeoutStartSec=300`.
-- It publishes both `127.0.0.1:18789:18789` (gateway) and `127.0.0.1:18790:18790` (bridge).
-- It reads `~/.fengming/.env` as a runtime `EnvironmentFile` for values such as `FENGMING_GATEWAY_TOKEN`, but it does not consume the manual launcher's Podman-specific override allowlist.
-- If you need custom publish ports, publish host, or other container-run flags, use the manual launcher or edit `~/.config/containers/systemd/fengming.container` directly, then reload and restart the service.
-
-## Useful commands
-
-- **Container logs:** `podman logs -f fengming`
-- **Stop container:** `podman stop fengming`
-- **Remove container:** `podman rm -f fengming`
-- **Open dashboard URL from host CLI:** `fengming dashboard --no-open`
-- **Health/status via host CLI:** `fengming gateway status --deep` (RPC probe + extra
-  service scan)
-
-## Troubleshooting
-
-- **Permission denied (EACCES) on config or workspace:** The container runs with `--userns=keep-id` and `--user <your uid>:<your gid>` by default. Ensure the host config/workspace paths are owned by your current user.
-- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~/.fengming/fengming.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this if missing.
-- **Container CLI commands hit the wrong target:** Use `fengming --container <name> ...` explicitly, or export `FENGMING_CONTAINER=<name>` in your shell.
-- **`fengming update` fails with `--container`:** Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
-- **Quadlet service does not start:** Run `systemctl --user daemon-reload`, then `systemctl --user start fengming.service`. On headless systems you may also need `sudo loginctl enable-linger "$(whoami)"`.
-- **SELinux blocks bind mounts:** Leave the default mount behavior alone; the launcher auto-adds `:Z` on Linux when SELinux is enforcing or permissive.
-
-## Related
-
-- [Docker](/install/docker)
-- [Gateway background process](/gateway/background-process)
-- [Gateway troubleshooting](/gateway/troubleshooting)

package/docs/install/railway.mdx

@@ -1,92 +0,0 @@
----
-summary: "Deploy OpenClaw on Railway with one-click template"
-read_when:
-  - Deploying OpenClaw to Railway
-  - You want a one-click cloud deploy with browser-based Control UI
-title: "Railway"
----
-
-# Railway
-
-Deploy OpenClaw on Railway with a one-click template and access it through the web Control UI.
-This is the easiest "no terminal on the server" path: Railway runs the Gateway for you.
-
-## Quick checklist (new users)
-
-1. Click **Deploy on Railway** (below).
-2. Add a **Volume** mounted at `/data`.
-3. Set the required **Variables** (at least `OPENCLAW_GATEWAY_PORT` and `OPENCLAW_GATEWAY_TOKEN`).
-4. Enable **HTTP Proxy** on port `8080`.
-5. Open `https://<your-railway-domain>/openclaw` and connect using the configured shared secret. This template uses `OPENCLAW_GATEWAY_TOKEN` by default; if you replace it with password auth, use that password instead.
-
-## One-click deploy
-
-<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">
-  Deploy on Railway
-</a>
-
-After deploy, find your public URL in **Railway → your service → Settings → Domains**.
-
-Railway will either:
-
-- give you a generated domain (often `https://<something>.up.railway.app`), or
-- use your custom domain if you attached one.
-
-Then open:
-
-- `https://<your-railway-domain>/openclaw` — Control UI
-
-## What you get
-
-- Hosted OpenClaw Gateway + Control UI
-- Persistent storage via Railway Volume (`/data`) so `openclaw.json`,
-  per-agent `auth-profiles.json`, channel/provider state, sessions, and
-  workspace survive redeploys
-
-## Required Railway settings
-
-### Public Networking
-
-Enable **HTTP Proxy** for the service.
-
-- Port: `8080`
-
-### Volume (required)
-
-Attach a volume mounted at:
-
-- `/data`
-
-### Variables
-
-Set these variables on the service:
-
-- `OPENCLAW_GATEWAY_PORT=8080` (required — must match the port in Public Networking)
-- `OPENCLAW_GATEWAY_TOKEN` (required; treat as an admin secret)
-- `OPENCLAW_STATE_DIR=/data/.openclaw` (recommended)
-- `OPENCLAW_WORKSPACE_DIR=/data/workspace` (recommended)
-
-## Connect a channel
-
-Use the Control UI at `/openclaw` or run `openclaw onboard` via Railway's shell for channel setup instructions:
-
-- [Telegram](/channels/telegram) (fastest — just a bot token)
-- [Discord](/channels/discord)
-- [All channels](/channels)
-
-## Backups & migration
-
-Export your state, config, auth profiles, and workspace:
-
-```bash
-openclaw backup create
-```
-
-This creates a portable backup archive with OpenClaw state plus any configured
-workspace. See [Backup](/cli/backup) for details.
-
-## 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/raspberry-pi.md

@@ -1,234 +0,0 @@
----
-summary: "Host FengMing on a Raspberry Pi for always-on self-hosting"
-read_when:
-  - Setting up FengMing on a Raspberry Pi
-  - Running FengMing on ARM devices
-  - Building a cheap always-on personal AI
-title: "Raspberry Pi"
----
-
-Run a persistent, always-on FengMing Gateway on a Raspberry Pi. Since the Pi is just the gateway (models run in the cloud via API), even a modest Pi handles the workload well — typical hardware cost is **$35–80 one-time**, no monthly fees.
-
-## Hardware compatibility
-
-| Pi model    | RAM    | Works? | Notes                               |
-| ----------- | ------ | ------ | ----------------------------------- |
-| Pi 5        | 4/8 GB | Best   | Fastest, recommended.               |
-| Pi 4        | 4 GB   | Good   | Sweet spot for most users.          |
-| Pi 4        | 2 GB   | OK     | Add swap.                           |
-| Pi 4        | 1 GB   | Tight  | Possible with swap, minimal config. |
-| Pi 3B+      | 1 GB   | Slow   | Works but sluggish.                 |
-| Pi Zero 2 W | 512 MB | No     | Not recommended.                    |
-
-**Minimum:** 1 GB RAM, 1 core, 500 MB free disk, 64-bit OS.
-**Recommended:** 2 GB+ RAM, 16 GB+ SD card (or USB SSD), Ethernet.
-
-## Prerequisites
-
-- Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended)
-- MicroSD card (16 GB+) or USB SSD (better performance)
-- Official Pi power supply
-- Network connection (Ethernet or WiFi)
-- 64-bit Raspberry Pi OS (required -- do not use 32-bit)
-- About 30 minutes
-
-## Setup
-
-<Steps>
-  <Step title="Flash the OS">
-    Use **Raspberry Pi OS Lite (64-bit)** -- no desktop needed for a headless server.
-
-    1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/).
-    2. Choose OS: **Raspberry Pi OS Lite (64-bit)**.
-    3. In the settings dialog, pre-configure:
-       - Hostname: `gateway-host`
-       - Enable SSH
-       - Set username and password
-       - Configure WiFi (if not using Ethernet)
-    4. Flash to your SD card or USB drive, insert it, and boot the Pi.
-
-  </Step>
-
-  <Step title="Connect via SSH">
-    ```bash
-    ssh user@gateway-host
-    ```
-  </Step>
-
-  <Step title="Update the system">
-    ```bash
-    sudo apt update && sudo apt upgrade -y
-    sudo apt install -y git curl build-essential
-
-    # Set timezone (important for cron and reminders)
-    sudo timedatectl set-timezone America/Chicago
-    ```
-
-  </Step>
-
-  <Step title="Install Node.js 24">
-    ```bash
-    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
-    sudo apt install -y nodejs
-    node --version
-    ```
-  </Step>
-
-  <Step title="Add swap (important for 2 GB or less)">
-    ```bash
-    sudo fallocate -l 2G /swapfile
-    sudo chmod 600 /swapfile
-    sudo mkswap /swapfile
-    sudo swapon /swapfile
-    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
-
-    # Reduce swappiness for low-RAM devices
-    echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
-    sudo sysctl -p
-    ```
-
-  </Step>
-
-  <Step title="Install FengMing">
-    ```bash
-    curl -fsSL https://fengming.ai/install.sh | bash
-    ```
-  </Step>
-
-  <Step title="Run onboarding">
-    ```bash
-    fengming onboard --install-daemon
-    ```
-
-    Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with.
-
-  </Step>
-
-  <Step title="Verify">
-    ```bash
-    fengming status
-    systemctl --user status fengming-gateway.service
-    journalctl --user -u fengming-gateway.service -f
-    ```
-  </Step>
-
-  <Step title="Access the Control UI">
-    On your computer, get a dashboard URL from the Pi:
-
-    ```bash
-    ssh user@gateway-host 'fengming dashboard --no-open'
-    ```
-
-    Then create an SSH tunnel in another terminal:
-
-    ```bash
-    ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
-    ```
-
-    Open the printed URL in your local browser. For always-on remote access, see [Tailscale integration](/gateway/tailscale).
-
-  </Step>
-</Steps>
-
-## Performance tips
-
-**Use a USB SSD** -- SD cards are slow and wear out. A USB SSD dramatically improves performance. See the [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot).
-
-**Enable module compile cache** -- Speeds up repeated CLI invocations on lower-power Pi hosts:
-
-```bash
-grep -q 'NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
-export NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache
-mkdir -p /var/tmp/fengming-compile-cache
-export FENGMING_NO_RESPAWN=1
-EOF
-source ~/.bashrc
-```
-
-`FENGMING_NO_RESPAWN=1` keeps routine Gateway restarts in-process, which avoids extra process handoffs and keeps PID tracking simple on small hosts.
-
-**Reduce memory usage** -- For headless setups, free GPU memory and disable unused services:
-
-```bash
-echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
-sudo systemctl disable bluetooth
-```
-
-**systemd drop-in for stable restarts** -- If this Pi is mostly running FengMing, add a service drop-in:
-
-```bash
-systemctl --user edit fengming-gateway.service
-```
-
-```ini
-[Service]
-Environment=FENGMING_NO_RESPAWN=1
-Environment=NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache
-Restart=always
-RestartSec=2
-TimeoutStartSec=90
-```
-
-Then `systemctl --user daemon-reload && systemctl --user restart fengming-gateway.service`. On a headless Pi, also enable lingering once so the user service survives logout: `sudo loginctl enable-linger "$(whoami)"`.
-
-## Recommended model setup
-
-Since the Pi only runs the gateway, use cloud-hosted API models:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "anthropic/claude-sonnet-4-6",
-        "fallbacks": ["openai/gpt-5.4-mini"]
-      }
-    }
-  }
-}
-```
-
-Do not run local LLMs on a Pi — even small models are too slow to be useful. Let Claude or GPT do the model work.
-
-## ARM binary notes
-
-Most FengMing features work on ARM64 without changes (Node.js, Telegram, WhatsApp/Baileys, Chromium). The binaries that occasionally lack ARM builds are typically optional Go/Rust CLI tools shipped by skills. Verify a missing binary's release page for `linux-arm64` / `aarch64` artifacts before falling back to building from source.
-
-## Persistence and backups
-
-FengMing state lives under:
-
-- `~/.fengming/` — `fengming.json`, per-agent `auth-profiles.json`, channel/provider state, sessions.
-- `~/.fengming/workspace/` — agent workspace (SOUL.md, memory, artifacts).
-
-These survive reboots. Take a portable snapshot with:
-
-```bash
-fengming backup create
-```
-
-If you keep these on an SSD, both performance and longevity improve over the SD card.
-
-## Troubleshooting
-
-**Out of memory** -- Verify swap is active with `free -h`. Disable unused services (`sudo systemctl disable cups bluetooth avahi-daemon`). Use API-based models only.
-
-**Slow performance** -- Use a USB SSD instead of an SD card. Check for CPU throttling with `vcgencmd get_throttled` (should return `0x0`).
-
-**Service will not start** -- Check logs with `journalctl --user -u fengming-gateway.service --no-pager -n 100` and run `fengming doctor --non-interactive`. If this is a headless Pi, also verify lingering is enabled: `sudo loginctl enable-linger "$(whoami)"`.
-
-**ARM binary issues** -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with `uname -m` (should show `aarch64`).
-
-**WiFi drops** -- Disable WiFi power management: `sudo iwconfig wlan0 power off`.
-
-## Next steps
-
-- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more
-- [Gateway configuration](/gateway/configuration) -- all config options
-- [Updating](/install/updating) -- keep FengMing up to date
-
-## Related
-
-- [Install overview](/install)
-- [Linux server](/vps)
-- [Platforms](/platforms)