OpenPawlet

Languages: 中文说明

What it is

OpenPawlet (PyPI package name open-pawlet) is a single-process web console for the OpenPawlet ecosystem. It exposes an HTTP API, a browser UI, an OpenAI-compatible /v1/* surface and the embedded agent runtime (agent loop, channels, cron, heartbeat) over a single FastAPI port so you can manage bot-related resources locally or in deployment.

Stack: FastAPI backend (consistent error envelope and OpenAPI; Swagger/ReDoc/openapi.json are served by default at /docs, /redoc, /openapi.json — set each *_url to empty to hide) and a Vite frontend under src/console/web (HMR in development, production build supported).

Feature areas

The console roughly covers the areas below (see the UI and OpenAPI for the exact surface):

Typical use: start console start; the embedded OpenPawlet runtime comes up in the same process so you can immediately inspect status, debug sessions, and manage these resources from the console without supervising a separate gateway.

Screenshots

The OpenPawlet web UI (branded “OpenPawlet · AI Assistant” in the console) provides a sidebar for Chat, Control, Agent, and Management areas, plus a top bar for workspace selection, language, theme, and gateway status.

Dashboard overview

The overview page surfaces key metrics (status, uptime, active sessions, messages, tokens, cost), the current model, and charts such as daily token usage and usage by model—useful for at-a-glance monitoring in local or deployed setups.

Chat

The chat view supports multiple sessions (list with message counts and last activity), streaming-style replies with optional thinking / progress indicators, and an input area with token budget hints. Navigation to channels, MCP, memory, workspace, agents, skills, and related tools stays one click away in the sidebar.

Channels

Channels lists integrations for your bot (for example WebSocket, Weixin, DingTalk, Discord, Email, Feishu, Matrix, MoChat, Microsoft Teams, QQ, Slack, Telegram, WeCom, and WhatsApp). You can enable or edit each channel from the grid; the UI notes that changes are saved to config.json and that you should restart the bot for them to take effect.

Architecture notes

• Backend: FastAPI-based OpenPawlet service with a consistent error envelope and OpenAPI documentation.
• Frontend: Vite app under src/console/web, with HMR in development and a production build path.

Tech stack

Quick start

1. Virtual environment and install

A project-local .venv is recommended:

python3.11 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -e ".[dev]"

The openpawlet Python package ships inside this repository; pip install -e ".[dev]" installs the console and agent framework together.

2. Frontend dependencies

cd src/console/web && npm install && cd ../../..

3. Run

console and open-pawlet are the same command (both entry points map
to console.cli:main). Use whichever name you prefer; the examples below use
the shorter console alias.

Since 0.3.x all services are collapsed into a single FastAPI process:
REST API, SPA, OpenAI-compatible /v1/*, queues admin /queues/*,
WebSocket /openpawlet-ws/* and the embedded OpenPawlet runtime (AgentLoop,
Channels, Cron, Heartbeat) share the same event loop and expose one HTTP
port. The legacy standalone gateway / serve commands,
open-pawlet-queue-manager, Procfile and honcho entrypoints have all
been removed.

Single-command production (recommended for local use)

npm --prefix src/console/web run build
console start   # open http://localhost:8000

console start runs the unified FastAPI server, mounts the prebuilt SPA
from src/console/web/dist (so the UI and /api/v1/* share a single origin
and port) and starts the OpenPawlet runtime in the same event loop (no
subprocess fork; no ZeroMQ broker). All WebSocket / channel / cron tasks
live inside the FastAPI lifespan. On first launch run openpawlet onboard once
if ~/.openpawlet/config.json is missing. Press Ctrl+C to gracefully stop the
process.

Flags:

• --no-spa — skip mounting the prebuilt SPA. Useful for headless API-only
  deployments where the UI is hosted elsewhere.

Re-run npm run build (or console web build) after frontend changes.

Frontend dev mode (hot reload)

Run the unified server and the Vite dev server in two terminals:

console start         # single process: FastAPI + embedded OpenPawlet, on http://localhost:8000
console web dev       # Vite dev server on http://localhost:3000 (open this for the UI)

Open the Vite URL (http://localhost:3000); Vite proxies /api/*,
/v1/*, /queues/* and /openpawlet-ws/* to :8000. You no longer need a
separate gateway or queue-manager process.

Cross-platform notes

• The single-process layout runs unchanged on Windows and Linux; the
  CLI flips to WindowsSelectorEventLoopPolicy automatically on Windows.
• Signal handling lives in console.server.signals: Linux uses
  loop.add_signal_handler, Windows falls back to signal.signal.
• pytest -q passes on both platforms (only one ExecTool case unrelated to
  this repository is skipped on Windows because sleep is not on PATH).

Configuration

Settings are resolved with the following priority (highest first):

1. Environment variables prefixed with OPENPAWLET_SERVER_ (e.g.
   OPENPAWLET_SERVER_PORT=9000)
2. Optional .env file in the working directory
3. ~/.openpawlet/openpawlet_web.json under the top-level server key
4. Built-in defaults (see console.server.config.schema.ServerSettings)

The JSON file is opt-in: it is no longer written automatically on first
boot. Create a starter file with console init-config when you want to
persist non-default values to disk.

Version history (timeline)

Major releases for the open-pawlet PyPI package (matches [project] version in the root pyproject.toml). The console is built for the OpenPawlet stack; the agent framework lives under src/openpawlet and ships with each install. Newest at the top; older entries below. Add new rows at the top when you cut a release.

2026-04-26 ──●── 0.3.0  Unified single-process FastAPI: console + OpenPawlet OpenAI API + queues admin + gateway collapsed into one entrypoint; ZMQ broker / Procfile / honcho removed; in-process MessageBus; cross-platform Win/Linux hardening; new unified-app end-to-end tests
              │
2026-04-20 ──●── 0.2.2  OpenPawlet WebSocket (session lifecycle, delta stream, busy state); tests/docs; UI & dashboard
              │
2026-04-19 ──●── 0.2.1  Aligned versions (pyproject, API schema, web); OpenPawlet framework + console version metadata
              │
2026-04-19 ──●── 0.2.0  Deps & packaging; README; bundled OpenPawlet framework; WhatsApp bridge under bridge/
              │
2026-04-19 ──●── 0.1.0  First release: FastAPI console for the OpenPawlet agent, CLI, workspace, README / Procfile

License

MIT — see LICENSE in the repository root.