piclaw Agent工作流

Other install methods

Install without Docker

bun add -g github:rcarmo/piclaw

Experimental. Linux/macOS/Windows. See docs/install-from-repo.md.

On Windows, PiClaw remains a secondary / not-officially-supported target. Shell-like child processes now run attached there (detached=false) so stdout/stderr remain capturable; Unix-like hosts still use detached process groups for cleaner tree termination on abort/shutdown.

Build from source

See docs/development.md.

Quick start

mkdir -p ./home ./workspace

docker run -d \
  --init \
  --name piclaw \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PICLAW_WEB_PORT=8080 \
  -v "$(pwd)/home:/config" \
  -v "$(pwd)/workspace:/workspace" \
  ghcr.io/rcarmo/piclaw:latest

Open http://localhost:8080 and type /login to configure your LLM provider, including custom OpenAI-compatible endpoints when you are not using one of the built-in hosted providers. The web UI currently ships with English, Simplified Chinese, and Japanese strings; use the Settings language switcher when English is not the hill you want to die on today.

[!TIP] Keep --init enabled for docker run / podman run so the runtime inserts a tiny init process for signal forwarding and zombie reaping. The bundled docker-compose.yml now sets the equivalent init: true flag.

[!NOTE] In the container image, /home/agent/.pi is backed by /config/.pi. With the stock docker run / docker-compose.yml examples above, Pi home state therefore persists on the host under ./home/.pi/agent/. That means provider login state and model metadata should survive rebuilds/recreates when stored under files such as: - ./home/.pi/agent/auth.json - ./home/.pi/agent/models.json Mounting directly to /home/agent or /home/agent/.pi/agent can also work, but /config is the canonical documented persistence path for the container image.

[!WARNING] Never delete /workspace/.piclaw/store/messages.db. It contains chat history, media, and task state.

[!IMPORTANT] You do not need to set provider API keys in piclaw environment variables. PiClaw reuses provider credentials configured in Pi Agent settings.

[!NOTE] Power users can place workspace-scoped shell environment overrides in /workspace/.env.sh. PiClaw sources that file for the embedded terminal and on runtime startup, which is useful for things like PATH tweaks or persisting gh auth login with GH_CONFIG_DIR=/workspace/.config/gh. This hook is user-controlled: if its contents break PiClaw startup, shell behavior, or tool resolution, that breakage is the user's responsibility.

Configuration

Most users only need a few environment variables:

For the full list, auth setup (TOTP/passkeys), session-scoped SSH-backed remote tools, reverse proxy configuration, SSHFS/FUSE support, and the workspace environment hook, see docs/configuration.md.