QwenPaw Documentation

1. Project Overview & Quickstart (agentscope-ai/QwenPaw) Copy Chapter

File: README.md Copy Chapter

Your personal AI assistant — deploy locally or in the cloud, extend with Skills & Plugins, connect across every channel.

What you can do with QwenPaw

• Automation & scheduling: Set up recurring tasks — news digests, report generation, multi-channel broadcasting — all on your schedule.
• Code & development: Read, edit, review, and test code in your projects with the unified file workspace.
• Document processing: Read, write, and convert PDF, Word, Excel, and PowerPoint files.
• Information gathering: Search the web, follow subscriptions, summarize videos, and find what you need in your personal knowledge base.
• Multi-channel ops: Push alerts, summaries, or AI-generated content to DingTalk, Lark, Discord, Telegram, and more — simultaneously or per channel.
• Custom workflows: Combine built-in capabilities, plugins, and scheduled tasks into workflows tailored to your needs.

News Copy Chapter

• [2026-08-13] v2.1.0 | QwenPaw OS Shell, unified Files workspace, QwenPaw Creator, Codex/Qoder Agent integration, Browser-use, Computer-use, workspace checkpoints, and long-running conversation continuity. v2.1.0 Release Notes →

• [2026-07-24] v2.0.1 | PawApp mini-app platform, user-editable Agent Modes, Oh-My-Paw plugins, ReMe memory enhancements, desktop UX improvements, and more. v2.0.1 Release Notes →

• [2026-07-10] v2.0.0 — QwenPaw 2.0 Official Release 🎉 | An AgentScope 2.0 based ground-up rewrite delivering the Agent OS architecture, Loop Engineering, Scroll Context, ReMe v0.4 Self-evolving Personal Knowledge Base, and a bundled Terminal UI.

  Highlight	What's new
  Agent OS — Workspace	Three pillars per agent: Resources (transparent on disk), Governance (allow/deny/ask/sandbox), Sandbox (macOS / Linux / Windows).
  Agent OS — Drivers	Protocol-neutral MCP / A2A / ACP connector layer with encrypted credentials and per-call policy gate.
  Loop Engineering	Advanced agent loop templates (Coding Mode, Mission Mode, more to come) with composable approval gates.
  Scroll Context	Every turn persisted; evicted turns indexed with on-demand recall — nothing summarized away.
  ReMe v0.4 Self-evolving Personal Knowledge Base	Continuously turns conversations and resources into readable, editable, searchable, and linked Markdown memory.
  Terminal UI (TUI)	Full-screen terminal chat — same agent, memory, and sessions as Console and channels.

  Built on Agent OS, we will be launching out-of-box QwenPaw applications — such as QwenPaw Creator and QwenPaw Insight — stay tuned. v2.0.0 Release Notes →

• [2026-06-17] v1.1.12 — Models Page Overhaul & Simple Mode | Redesigned Models page with provider aggregation; new Simple Mode for streamlined navigation. v1.1.12 Release Notes →

• [2026-06-11] AgentScope Platform is live — Free QwenPaw deployment, plugin sharing, and Skill marketplace. Try it now →

• [2026-06-10] v1.1.11 — Free Model OAuth, Plugin Market, MCP Tool Whitelisting. v1.1.11 Release Notes →

All release notes →

Table of Contents Copy Chapter

• News
• Quick Start
• API Key
• Local Models
• Security Features
• Documentation
• FAQ
• Roadmap
• Contributing
• Install From Source
• Why QwenPaw?
• Built By
• License

Quick Start Copy Chapter

Option 1: Pip Install Copy Section

If you prefer managing Python yourself (requires Python >= 3.11, < 3.14):

pip install qwenpaw
qwenpaw init --defaults
qwenpaw app

Then open the Console in your browser at http://127.0.0.1:8088/ to configure your model. To chat in DingTalk, Lark, WeChat, etc., see the Channel setup documentation.

Option 2: Script Install Copy Section

No Python setup required, one command installs everything. The script will automatically download uv (Python package manager), create a virtual environment, and install QwenPaw with all dependencies (including Node.js and frontend assets). Note: May not work in restricted network environments or corporate firewalls.

macOS / Linux:

curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash

Windows (CMD):

curl -fsSL https://qwenpaw.agentscope.io/install.bat -o install.bat && install.bat

Windows (PowerShell):

irm https://qwenpaw.agentscope.io/install.ps1 | iex

Note: The installer will automatically check the status of uv. If it is not installed, it will attempt to download and configure it automatically. If the automatic installation fails, please follow the on-screen prompts or execute python -m pip install -U uv, then rerun the installer.

⚠️ Special Notice for Windows Enterprise LTSC Users

If you are using Windows LTSC or an enterprise environment governed by strict security policies, PowerShell may run in Constrained Language Mode, potentially causing the following issue:

1. If using CMD (.bat): Script executes successfully but fails to write to Path

   The script completes file installation. Due to Constrained Language Mode, it cannot automatically update environment variables. Manually configure as follows:

   • Locate the installation directory:
     • Check if uv is available: Enter uv --version in CMD. If a version number appears, only configure the QwenPaw path. If you receive the prompt 'uv' is not recognized as an internal or external command, operable program or batch file, configure both paths.
     • uv path (choose one based on installation location; use if uv fails): Typically %USERPROFILE%\.local\bin, %USERPROFILE%\AppData\Local\uv, or the Scripts folder within your Python installation directory
     • QwenPaw path: Typically located at %USERPROFILE%\.qwenpaw\bin.
   • Manually add to the system's Path environment variable:
     • Press Win + R, type sysdm.cpl and press Enter to open System Properties.
     • Click “Advanced” -> “Environment Variables”.
     • Under “System variables”, locate and select Path, then click “Edit”.
     • Click “New”, enter both directory paths sequentially, then click OK to save.

2. If using PowerShell (.ps1): Script execution interrupted

Due to Constrained Language Mode, the script may fail to automatically download uv.

• Manually install uv: Refer to the GitHub Release to download uv.exe and place it in %USERPROFILE%\.local\bin or %USERPROFILE%\AppData\Local\uv; or ensure Python is installed and run python -m pip install -U uv.
• Configure uv environment variables: Add the uv directory and %USERPROFILE%\.qwenpaw\bin to your system's Path variable.
• Re-run the installation: Open a new terminal and execute the installation script again to complete the QwenPaw installation.
• Configure the QwenPaw environment variable: Add %USERPROFILE%\.qwenpaw\bin to your system's Path variable.

Once installed, open a new terminal and run:

qwenpaw init --defaults   # or: qwenpaw init (interactive)
qwenpaw app

Install options

macOS / Linux:

# Install a specific version
curl -fsSL ... | bash -s -- --version 1.1.0

# Install from source (dev/testing)
curl -fsSL ... | bash -s -- --from-source

# Upgrade — just re-run the installer
curl -fsSL ... | bash

# Uninstall
qwenpaw uninstall          # keeps config and data
qwenpaw uninstall --purge  # removes everything

Windows (PowerShell):

# Install a specific version
irm ... | iex; .\install.ps1 -Version 1.1.12

# Install from source (dev/testing)
.\install.ps1 -FromSource

# Upgrade — just re-run the installer
irm ... | iex

# Uninstall
qwenpaw uninstall          # keeps config and data
qwenpaw uninstall --purge  # removes everything

Option 3: Docker Copy Section

Images are on Docker Hub (agentscope/qwenpaw). Image tags: latest (stable); pre (PyPI pre-release).

docker pull agentscope/qwenpaw:latest
docker run -p 127.0.0.1:8088:8088 \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

Also available on Alibaba Cloud Container Registry (ACR) for users in China: agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw (same tags).

Then open http://127.0.0.1:8088/ for the Console. Config, memory, and skills are stored in the qwenpaw-data volume; model provider settings and API keys are in the qwenpaw-secrets volume; backup archives are stored in the qwenpaw-backups volume. To pass API keys (e.g. DASHSCOPE_API_KEY), add -e VAR=value or --env-file .env to docker run.

Connecting to Ollama or other services on the host machine

Inside a Docker container, localhost refers to the container itself, not your host machine. If you run Ollama (or other model services) on the host and want QwenPaw in Docker to reach them, use one of these approaches:

Option A — Explicit host binding (all platforms):

bash Copy

docker run -p 127.0.0.1:8088:8088 \
  --add-host=host.docker.internal:host-gateway \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

Then in QwenPaw Settings → Models, change the Base URL to http://host.docker.internal: — for example, http://host.docker.internal:11434 for Ollama, or http://host.docker.internal:1234/v1 for LM Studio.

Option B — Host networking (Linux only):

bash Copy

docker run --network=host \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

No port mapping (-p) is needed; the container shares the host network directly. Note that all container ports are exposed on the host, which may cause conflicts if the port is already in use.

The image is built from scratch. To build the image yourself, please refer to the Build Docker image section in scripts/README.md, and then push to your registry.

Option 4: Deploy on Alibaba Cloud ECS Copy Section

To run QwenPaw on Alibaba Cloud (ECS), use the one-click deployment: open the QwenPaw on Alibaba Cloud (ECS) deployment link and follow the prompts. For step-by-step instructions, see Alibaba Cloud Developer: Deploy your AI assistant in 3 minutes.

Option 5: AgentScope Platform Copy Section

AgentScope Platform provides one-click cloud QwenPaw deployment, plugin sharing, and a Skill marketplace. Free, 7/24 online.

Option 6: Using ModelScope Copy Section

ModelScope Studio also supports cloud QwenPaw deployment. Note: set your Studio to non-public so others cannot control your QwenPaw.

Option 7: Desktop Application (Beta) Copy Section

Beta Notice: The desktop application is currently in Beta testing phase with the following known limitations:

• Incomplete compatibility testing: Not fully tested across all system versions and hardware configurations
• Potential performance issues: Startup time, memory usage, and other performance aspects may need further optimization
• Features under development: Some features may be unstable or missing

If you're not comfortable with command-line tools, you can download and use QwenPaw's desktop application without manually configuring Python environments or running commands.

Download

Download the desktop app (Tauri build) from the official download page:

• Windows: QwenPaw-Tauri-<version>-Windows-setup.exe
• macOS: QwenPaw-Tauri-<version>-macOS.zip (Apple Silicon recommended)

Features

• ✅ Zero configuration: Download and double-click to run, no need to install Python or configure environment variables
• ✅ Cross-platform: Supports Windows 10+ and macOS 14+
• ✅ Visual interface: Automatically opens the app window, no need to manually enter addresses
• ⚠️ Beta stage: Features are continuously being improved, feedback welcome

First Launch

Important: The first launch may take 10-60 seconds (depending on your system configuration). The application needs to initialize the Python environment and load dependencies. Please wait patiently for the window to open automatically.

macOS: Bypass System Security Restrictions

When you download the QwenPaw macOS app from Releases, macOS may show: "Apple cannot verify that 'QwenPaw' contains no malicious software". This happens because the app is not notarized. You can still open it as follows:

• Right-click to open (recommended)
  Right-click (or Control+click) the QwenPaw app → Open → in the dialog click Open again. This tells Gatekeeper you trust the app; after that you can double-click to launch as usual.

• Allow in System Settings
  If it is still blocked, go to System Settings → Privacy & Security, scroll to the message like "QwenPaw was blocked because it is from an unidentified developer", and click Open Anyway or Allow.

• Remove quarantine attribute (not recommended for most users)
  In Terminal run:
  xattr -cr "/Applications/QwenPaw Desktop.app"
  (or use the path to the .app after unzipping). This clears the "downloaded from the internet" quarantine flag so the warning usually does not appear, but is less safe and controllable than using Right-click → Open.

For detailed usage instructions, troubleshooting, and common issues, see the Desktop Application Guide.

What's Next? Copy Section

After installation, configure your model in Console → Settings → Models, then explore:

• Add Skills to extend capabilities (PDF, Office, browser, news, etc.)
• Set up Channels for DingTalk, Lark, Discord, and more
• Configure Cron for scheduled tasks and automation
• See the full Quick Start guide for all options and verification steps

Terminal UI (TUI) Copy Chapter

Prefer to stay in the terminal? Run qwenpaw to open a full-screen chat TUI that drives the same agent as the Console and the IM Channels — same memory, skills, MCP tools, and sessions — without leaving your keyboard.

qwenpaw                     # open a chat with the active agent
qwenpaw tui --resume    # resume a previous session
qwenpaw .                   # start in the current repo (Coding Mode)

It supports streaming replies, slash commands (/help, /resume, /theme, plus the agent's own /model, /clear, …), pasting files/long text as attachments, and inline tool-permission prompts. See the Terminal UI guide for details.

API Key Copy Chapter

If you use a cloud LLM API (e.g., DashScope / Qwen, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, OpenRouter, and more), you must configure an API key before chatting. QwenPaw will not work until a valid key is set. See the official docs for details.

How to configure:

1. Console (recommended) — After running qwenpaw app, open http://127.0.0.1:8088/ → Settings → Models. Choose a provider, enter the API Key, and enable that provider and model.
2. qwenpaw init — When you run qwenpaw init, it will guide you through configuring the LLM provider and API key. Follow the prompts to choose a provider and enter your key.
3. Environment variable — For DashScope you can set DASHSCOPE_API_KEY in your shell or in a .env file in the working directory.

Tools that need extra keys (e.g. TAVILY_API_KEY for web search) can be set in Console Settings → Environment variables, see Config for details.

Using local models only? If you use Local Models (QwenPaw Local / Ollama / LM Studio), you do not need any API key.

Local Models Copy Chapter

QwenPaw can run LLMs entirely on your machine — no API keys or cloud services required. See the official docs for details.

QwenPaw also provides the QwenPaw-Flash series — purpose-trained 2B / 4B / 9B models for agent scenarios, with Q4 and Q8 quantizations. Available on ModelScope and Hugging Face.

Security Features Copy Chapter

QwenPaw includes four core security layers:

• Sandbox — Kernel-level execution isolation using Seatbelt (macOS), Bubblewrap / Landlock (Linux), and AppContainer (Windows). Shell commands run inside a restricted filesystem view.
• Tool Guard — YAML rule engine with ShellEvasionGuardian inspects every tool call before execution, detecting command injection, path traversal, reverse shells, and obfuscated attacks. Configurable approval levels: STRICT / SMART / AUTO / OFF.
• File Guard — Independent of Tool Guard; blocks agent access to sensitive files and directories (default-protects ~/.qwenpaw.secret/, ~/.ssh, etc.).
• Skill Scanner — Pre-activation scanning with block / warn / off modes and whitelist support. Detects prompt injection, hardcoded secrets, data exfiltration, and more.

See Security for details.

Documentation Copy Chapter

Full documentation: qwenpaw.agentscope.io/docs

FAQ Copy Chapter

For common questions, troubleshooting tips, and known issues, please visit the FAQ page.

Roadmap Copy Chapter

Status: In Progress — actively being worked on; Seeking Contributors — we strongly encourage community contributions.

Contributing Copy Chapter

QwenPaw evolves through open collaboration, and we welcome all forms of contribution! Check the Roadmap above (especially items marked Seeking Contributors) to find areas that interest you, and read CONTRIBUTING to get started. We particularly welcome:

• Horizontal expansion — new channels, model providers, skills, MCPs.
• Existing feature extension & refinement — display and interaction improvements, download hints, Windows path compatibility, etc.

Join GitHub Discussions to discuss ideas or pick up tasks.

Install From Source Copy Chapter

git clone https://github.com/agentscope-ai/QwenPaw.git
cd QwenPaw

# Build console frontend first (required for web UI)
cd console && npm ci && npm run build
cd ..

# Copy console build output to package directory
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/

# Install Python package
pip install -e .

• Dev (tests, formatting): pip install -e ".[dev,test,full]"
• Then: Run qwenpaw init --defaults, then qwenpaw app.

Note for updates: When updating to a new major version after git pull, please also rebuild the frontend, reinstall the package (pip install -e .), restart qwenpaw app, and clear your browser cache with Ctrl+Shift+R (or Cmd+Shift+R on macOS).

Why QwenPaw? Copy Chapter

QwenPaw stands for Qwen Personal Agent Workstation, and also embodies the wisdom of Qwen and the warmth of a Paw.
We hope it is not a cold tool, but an intelligent and warm "little paw" always ready to help—a most intuitive partner in your digital life.

Built By Copy Chapter

AgentScope team · AgentScope · AgentScope Runtime · ReMe

Contact Us Copy Chapter

Staying Ahead Copy Chapter

Star QwenPaw on GitHub and be instantly notified of new releases.

Telemetry Copy Chapter

QwenPaw collects anonymous usage data during qwenpaw init to help us understand our user base and prioritize improvements. Data is sent once per version — when you upgrade QwenPaw, telemetry is re-collected so we can track version adoption.

What we collect:

• QwenPaw version (e.g., 1.1.12)
• Install method (pip, Docker, or desktop app)
• OS and version (e.g., macOS 14.0, Ubuntu 22.04)
• Python version (e.g., 3.13)
• CPU architecture (e.g., x86_64, arm64)
• GPU availability (yes/no)

What we do NOT collect: No personal data, no files, no credentials, no IP addresses, no identifiable information.

When running qwenpaw init interactively, you will be asked whether to opt in. If you choose --defaults, telemetry is accepted automatically. The prompt appears once per version and never affects QwenPaw's functionality.

License Copy Chapter

QwenPaw is released under the Apache License 2.0.

Contributors Copy Chapter

All thanks to our contributors:

File: scripts/pack/README.md Copy Chapter

QwenPaw Desktop packaging scripts

⚠️ Legacy (rollback-only). These conda-pack based packaging scripts have
been superseded by the Tauri desktop build (see console/src-tauri/ and
scripts/pack-tauri/). They are kept only for short-term rollback and are no
longer used by the release pipeline. For the current desktop app, refer to the
Desktop Application Guide.

One-click build: each script first builds a wheel via
scripts/wheel_build.sh (includes the console frontend), then uses a
temporary conda environment and conda-pack (no current dev env).
Dependencies follow pyproject.toml.

• Windows: wheel → conda-pack → unpack → NSIS installer (.exe)
• macOS: wheel → conda-pack → unpack into .app → optional zip

System Requirements Copy Chapter

• Windows: Windows 10 or later
• macOS: macOS 14 (Sonoma) or later, Apple Silicon (M1/M2/M3/M4) recommended

Prerequisites Copy Chapter

• conda (Miniconda/Anaconda) on PATH
• Node.js / npm (for the console frontend)
• (Windows only) NSIS: makensis on PATH
• Icons: Pre-generated icon.ico (Windows) and icon.icns (macOS) are included in scripts/pack/assets/

One-click build Copy Chapter

From the repo root:

macOS

bash ./scripts/pack/build_macos.sh
# Output: dist/QwenPaw.app

CREATE_ZIP=1 bash ./scripts/pack/build_macos.sh   # also create .zip

Windows (PowerShell)

./scripts/pack/build_win.ps1
# Output: dist/QwenPaw-Setup-<version>.exe
# Creates two launchers:
#   - QwenPaw Desktop.vbs (silent, no console window)
#   - QwenPaw Desktop (Debug).bat (shows console for troubleshooting)
# Note: Pre-compiles all Python files to .pyc for faster startup

Run from terminal and see logs (macOS) Copy Chapter

If the .app crashes on double-click, run it from Terminal to see the full error and logs:

# From repo root; force packed env only (no system conda / PYTHONPATH). Adjust path if needed.
APP_ENV="$(pwd)/dist/QwenPaw.app/Contents/Resources/env"
PYTHONNOUSERSITE=1 PYTHONPATH= PYTHONHOME="$APP_ENV" "$APP_ENV/bin/python" -m qwenpaw desktop

The PYTHONNOUSERSITE=1 prevents Python from loading packages from ~/.local/lib/pythonX.Y/site-packages, which can conflict with the packaged environment. All stdout/stderr (including Python tracebacks) will appear in the terminal. Use this to debug startup errors or to run with --log-level debug.

When you double-click the .app and nothing appears, the launcher writes stderr/stdout to ~/.qwenpaw/desktop.log. Inspect that file for errors.

On first launch macOS may ask for “Desktop” or “Files and Folders” access: click Allow so the app can run properly; if you click Don’t Allow, the window may close.

macOS: if “Apple cannot verify” / Gatekeeper blocks the app Copy Chapter

When users download the QwenPaw macOS app (e.g. from Releases) as a .app (in a zip), macOS may show: "Apple cannot verify that 'QwenPaw' contains no malicious software". The app is not notarized. They can still open it as follows:

• Right-click to open (recommended)
  Right-click (or Control+click) the QwenPaw app → Open → in the dialog click Open again. Gatekeeper will allow it; after that double-click works as usual.

• Allow in System Settings
  If still blocked, go to System Settings → Privacy & Security, find the message like "QwenPaw was blocked because it is from an unidentified developer", and click Open Anyway or Allow.

• Remove quarantine attribute (not recommended for most users)
  In Terminal: xattr -cr /Applications/QwenPaw.app (or the path to the .app after unzipping). This clears the download quarantine flag; less safe than right-click → Open.

CI Copy Chapter

.github/workflows/desktop-release.yml:

• Triggers: Release publish or manual workflow_dispatch
• Windows: Build console → temporary conda env + conda-pack → NSIS → upload artifact
• macOS: Build console → temporary conda env + conda-pack → .app → zip → upload artifact
• Release: When triggered by a release, uploads the Windows installer and macOS zip as release assets

Script reference Copy Chapter

File: scripts/pack/README_zh.md Copy Chapter

QwenPaw Desktop 打包脚本

⚠️ 旧版（仅用于回滚）。 这套基于 conda-pack 的打包脚本已被 Tauri
桌面版构建取代（详见 console/src-tauri/ 与 scripts/pack-tauri/），仅作
短期回滚保留，发布流程已不再使用。当前桌面应用请参考
桌面应用指南。

一键打包：脚本会先运行 scripts/wheel_build.sh 构建 wheel
（包含 console 前端产物），再用 临时 conda 环境 + conda-pack
（不依赖当前开发环境）。依赖以 pyproject.toml 为准。

• Windows: wheel → conda-pack → 解压 → NSIS 安装包 (.exe)
• macOS: wheel → conda-pack → 解压到 .app → 可选打 zip

系统要求 Copy Chapter

• Windows: Windows 10 或更高版本
• macOS: macOS 14 (Sonoma) 或更高版本，推荐 Apple Silicon (M1/M2/M3/M4)

前置 Copy Chapter

• conda（Miniconda/Anaconda）在 PATH
• Node.js / npm（用于构建 console 前端）
• （仅 Windows）NSIS：makensis 在 PATH
• 图标：预生成的 icon.ico (Windows) 和 icon.icns (macOS) 已包含在 scripts/pack/assets/ 中

一键打包 Copy Chapter

在仓库根目录执行：

macOS

bash ./scripts/pack/build_macos.sh
# 产出: dist/QwenPaw.app

CREATE_ZIP=1 bash ./scripts/pack/build_macos.sh   # 同时生成 .zip

Windows (PowerShell)

./scripts/pack/build_win.ps1
# 产出: dist/QwenPaw-Setup-<version>.exe
# 创建两个启动器：
#   - QwenPaw Desktop.vbs (静默启动，无终端窗口)
#   - QwenPaw Desktop (Debug).bat (显示终端，便于调试)

从终端启动并查看日志（macOS） Copy Chapter

如果双击 .app 会闪退，可以在终端里运行以查看完整报错和日志：

# 在仓库根目录执行，强制只用打包环境（不用系统 conda / PYTHONPATH）。路径按需改。
APP_ENV="$(pwd)/dist/QwenPaw.app/Contents/Resources/env"
PYTHONNOUSERSITE=1 PYTHONPATH= PYTHONHOME="$APP_ENV" "$APP_ENV/bin/python" -m qwenpaw desktop

PYTHONNOUSERSITE=1 可防止 Python 加载 ~/.local/lib/pythonX.Y/site-packages 中的包，避免与打包环境冲突。所有标准输出和错误（包括 Python traceback）都会打在终端里；可加 --log-level debug 查看更详细日志。

若双击 .app 没有任何窗口出现，启动器会把 stderr/stdout 写入 ~/.qwenpaw/desktop.log，可打开该文件查看报错。

首次打开时，macOS 可能弹出「请求访问桌面的文件」：请点允许，否则部分功能可能不可用或窗口会关闭。

macOS：提示「无法验证开发者」/ Gatekeeper 拦截时怎么打开 Copy Chapter

用户从 Release 等渠道下载的 QwenPaw macOS 应用（zip 内的 .app）未经过 Apple 公证，可能看到「Apple 无法验证“QwenPaw”是否包含可能危害 Mac 安全或泄漏隐私的恶意软件」。可按以下方式打开：

• 右键打开（推荐）
  在 QwenPaw 应用上 右键（或 Control + 点击） → 选 「打开」 → 在弹窗里再点一次 「打开」。即表示你确认运行该应用，Gatekeeper 会放行，之后双击即可正常打开。

• 在系统设置里放行
  若仍被拦截，进入 系统设置 → 隐私与安全性，往下找到类似「已阻止使用 QwenPaw，因为无法验证开发者」的提示，点 「仍要打开」 或 「允许」 即可。

• 用终端去掉隔离属性（不推荐普通用户）
  在终端执行：xattr -cr /Applications/QwenPaw.app（或解压后 .app 的实际路径）。会去掉「从互联网下载」的隔离标记，一般就不再弹恶意软件提示，但不如「右键 → 打开」安全、可控。

CI Copy Chapter

.github/workflows/desktop-release.yml：

• 触发: Release 发布 或 手动 workflow_dispatch
• Windows: 构建 console → 临时 conda 环境 + conda-pack → NSIS → 上传 artifact
• macOS: 构建 console → 临时 conda 环境 + conda-pack → .app → zip → 上传 artifact
• Release: 若由 release 触发，则把 Windows 安装包与 macOS zip 上传到该 Release 的附件

脚本说明 Copy Chapter

File: scripts/startup_profile/README.md Copy Chapter

🚀 QwenPaw Startup Performance Analyzer

One-click analysis of QwenPaw startup performance, identify bottlenecks, and provide optimization suggestions.

Quick Start Copy Chapter

# 1. Generate report
python scripts/startup_profile/analyze.py

# 2. Start local server to view (recommended)
python scripts/startup_profile/serve.py

After execution:

1. Collect import time data
2. Collect function execution trace (optional)
3. Generate JSON data
4. View report via HTTP server

Note: Due to browser security restrictions (CORS), opening HTML directly with file:// protocol cannot load data.
Please use serve.py or manually start an HTTP server:

cd /path/to/QwenPaw
python -m http.server 8000
# Visit: http://localhost:8000/scripts/startup_profile/output/report.html

Generated Files Copy Chapter

output/
├── importtime.log         # Import time raw log
├── execution_trace.json   # Function execution trace (if successful)
├── analysis.json          # Analysis data (core)
└── report.html            # Visual report ⭐

Report Features Copy Chapter

• Import Time Analysis - QwenPaw modules and third-party library import time ranking
• Function Execution Time - Top 20 function execution time statistics
• Function Call Tree - Complete function call hierarchy and timing (limited to 5 levels deep, top 10 calls per level)
• Interactive Charts - Chart.js horizontal bar chart visualization
• Bilingual Support - Chinese/English one-click toggle
• Performance Markers - Auto-mark fast/medium/slow functions based on timing (green/yellow/red)

How It Works Copy Chapter

1. Data Collection

   • Use Python -X importtime to collect import time
   • Use exec_tracer to track function calls

2. Data Analysis

   • Parse log files
   • Categorize statistics (QwenPaw/third-party/stdlib)
   • Calculate percentages and performance metrics

3. Visualization

   • HTML reads JSON data
   • Interactive charts and tables
   • Supports search, sort, filter

File Description Copy Chapter

• analyze.py - Data collection and analysis script
• viewer.html - Visualization interface (bilingual)
• README.md - Chinese documentation
• README_EN.md - English documentation

FAQ Copy Chapter

Q: Why do results vary each run?
A: Import time is affected by system load. Run multiple times and take average.

Q: How to compare before/after optimization?
A: Save output/ directory, re-run after optimization and compare.

Q: Function trace fails?
A: Normal, doesn't affect import analysis. Can use exec_tracer separately.

Technical Details Copy Chapter

• Python 3.8+
• No extra dependencies (except QwenPaw itself)
• Pure JSON data output
• HTML runs standalone, viewable offline

Related Tools Copy Chapter

• src/qwenpaw/utils/startup_display.py - Startup banner display

Version: 2.0.0
Author: QwenPaw Team
Updated: 2026-04-17

File: scripts/startup_profile/README_zh.md Copy Chapter

🚀 QwenPaw 启动性能分析工具

一键分析 QwenPaw 启动性能，识别瓶颈，提供优化建议。

快速开始 Copy Chapter

# 1. 生成报告
python scripts/startup_profile/analyze.py

# 2. 启动本地服务器查看（推荐）
python scripts/startup_profile/serve.py

执行后：

1. 收集 import 时间数据
2. 收集函数执行追踪（可选）
3. 生成 JSON 数据
4. 使用 HTTP 服务器查看报告

注意：由于浏览器安全限制（CORS），直接用 file:// 协议打开 HTML 无法加载数据。
请使用 serve.py 或手动启动 HTTP 服务器：

cd /path/to/QwenPaw
python -m http.server 8000
# 访问: http://localhost:8000/scripts/startup_profile/output/report.html

生成文件 Copy Chapter

output/
├── importtime.log         # Import 时间原始日志
├── execution_trace.json   # 函数执行追踪（如果成功）
├── analysis.json          # 分析数据（核心）
└── report.html            # 可视化报告 ⭐

报告功能 Copy Chapter

• Import 时间分析 - QwenPaw 模块和第三方库导入耗时排名
• 函数执行时间 - Top 20 函数执行时间统计
• 函数调用树 - 完整的函数调用层级关系和耗时（限制深度 5 层，每层最多显示前 10 个调用）
• 交互式图表 - Chart.js 横向柱状图可视化
• 双语支持 - 中英文一键切换
• 性能标记 - 根据耗时自动标记快/中/慢函数（绿/黄/红）

工作原理 Copy Chapter

1. 数据收集

   • 使用 Python -X importtime 收集 import 时间
   • 使用 exec_tracer 追踪函数调用

2. 数据分析

   • 解析日志文件
   • 分类统计（QwenPaw/第三方/标准库）
   • 计算占比和性能指标

3. 可视化展示

   • HTML 读取 JSON 数据
   • 交互式图表和表格
   • 支持搜索、排序、过滤

文件说明 Copy Chapter

• analyze.py - 数据收集和分析脚本
• viewer.html - 可视化界面（双语）
• README.md - 中文文档
• README_EN.md - 英文文档

常见问题 Copy Chapter

Q: 为什么每次结果不同？
A: Import 时间受系统负载影响，建议多次运行取平均值。

Q: 如何对比优化前后？
A: 保存 output/ 目录，优化后重新运行对比。

Q: 函数追踪失败怎么办？
A: 正常现象，不影响 import 分析。可单独使用 exec_tracer。

技术细节 Copy Chapter

• Python 3.8+
• 无额外依赖（除了 QwenPaw 本身）
• 纯 JSON 数据输出
• HTML 独立运行，可离线查看

相关工具 Copy Chapter

• src/qwenpaw/utils/startup_display.py - 启动横幅显示

版本: 2.0.0
作者: QwenPaw Team
更新: 2026-04-17

File: scripts/README.md Copy Chapter

Scripts

Run from repo root.

Build wheel (with latest console) Copy Chapter

bash scripts/wheel_build.sh

• Builds the console frontend (console/), copies console/dist to src/qwenpaw/console/dist, then builds the wheel. Output: dist/*.whl.

Build website Copy Chapter

bash scripts/website_build.sh

• Installs dependencies (pnpm or npm) and runs the Vite build. Output: website/dist/.

Build Docker image Copy Chapter

bash scripts/docker_build.sh [IMAGE_TAG] [EXTRA_ARGS...]

• Default tag: qwenpaw:latest. Uses deploy/Dockerfile (multi-stage: builds console then Python app).
• Example: bash scripts/docker_build.sh myreg/qwenpaw:v1 --no-cache.

Run Test Copy Chapter

# Run all tests
python scripts/run_tests.py

# Run all unit tests
python scripts/run_tests.py -u

# Run unit tests for a specific module
python scripts/run_tests.py -u providers

# Run integration tests
python scripts/run_tests.py -i

# Run all tests and generate a coverage report
python scripts/run_tests.py -a -c

# Run tests in parallel (requires pytest-xdist)
python scripts/run_tests.py -p

# Show help
python scripts/run_tests.py -h

File: website/public/docs/acp-integration.en.md Copy Chapter

ACP Integration

QwenPaw supports ACP (Agent Client Protocol) in two complementary ways:

1. QwenPaw using ACP as a Tool: QwenPaw connects to external ACP runners and uses them as delegated collaborators
2. QwenPaw as an ACP Server: external clients connect to QwenPaw over ACP

This page explains both modes and the scenarios each one fits best.

QwenPaw using ACP as a Tool Copy Chapter

In this mode, QwenPaw acts as an ACP client / orchestrator, connecting to configured and enabled external ACP runners and bringing them into the current session as delegated collaboration capabilities.

The actual entry point for this mode is the built-in tool delegate_external_agent. It is intended for scenarios where QwenPaw needs to collaborate with other ACP-capable external agent runtimes, such as the built-in examples opencode, qwen_code, claude_code, and codex. For more ACP-compatible agents, see the official ACP agent list and integration guide: https://agentclientprotocol.com/get-started/agents. In other words, QwenPaw does not directly talk to arbitrary external agents. It talks to runners that have been registered in ACP configuration, and it starts, continues, responds to, and closes delegated collaboration sessions through them.

What this mode does Copy Section

In this mode, QwenPaw uses the built-in delegate_external_agent tool to:

• start a session with an external ACP runner
• send follow-up messages to that runner
• respond to permission requests raised by that runner
• close the delegated session when the work is complete

Conceptually, this lets QwenPaw treat an external agent as a collaborative, tool-like capability while keeping QwenPaw as the primary orchestrator of the main conversation.

How to configure external runners Copy Section

Before using an external runner, make sure you have installed an ACP-compatible external agent and completed any required login or API key setup so it can be launched and used normally from the command line. You can refer to the official ACP agent list here: https://agentclientprotocol.com/get-started/agents.

Once the command-line side is ready, you can configure a custom runner in QwenPaw or collaborate with one of the built-in runners directly.

External runners must be configured and enabled on the Workspace → ACP page before they can be used by delegate_external_agent.

The current ACP configuration UI supports these fields for each runner:

• enabled
• command
• args
• env
• trusted
• tool_parse_mode
• stdio_buffer_limit_bytes

Specifically:

• command and args define the command and arguments used to launch the external runner;
• env passes environment variables;
• tool_parse_mode and stdio_buffer_limit_bytes control ACP output parsing and stdio buffering behavior. In most cases, the default values are fine and do not need to be changed.

On Linux/macOS, command is usually the command that starts the external agent in ACP mode, such as opencode or qwen, or the command that launches the corresponding ACP plugin, such as npx. Put the remaining flags and arguments in args, such as --acp or -y. Each argument must be entered on its own line. The source code ships with these built-in runner examples: opencode, qwen_code, claude_code, and codex. You can also add custom runners on the ACP page as long as they can run via ACP and are configured correctly.

On Windows, after confirming the external agent can be launched normally from the command line, set command to cmd and put /c as the first line in args, followed by the actual command and its arguments, again one per line. Example:

After configuration, enable the delegate_external_agent tool in the toolbar.

You can then explicitly specify which external agent you want to collaborate with in the conversation.

Typical workflow Copy Section

A typical delegated ACP workflow looks like this:

1. Configure and enable a runner on the Workspace → ACP page.
2. In a conversation, call delegate_external_agent(action="start", runner="...", message="...") to start a new delegated session for that runner.
3. If you want to continue the collaboration, call delegate_external_agent(action="message", runner="...", message="...") to send follow-up instructions to the existing runner session.
4. If the external runner raises a permission request, first let the user choose from the options shown in the UI, then call delegate_external_agent(action="respond", runner="...", message="<exact option id>") to resume execution. Here, message must be the exact option id returned by that permission request.
5. After the delegated work is complete, call delegate_external_agent(action="close", runner="...") to close the runner session.

You can pass task prompts such as "analyze the current working directory structure" or "write your self-introduction into a Markdown file" in start or message, but the underlying flow always maps to the same four actions: start, message, respond, and close.

Supported delegated actions Copy Section

The built-in delegation flow supports these action types:

Permission handling Copy Section

When an external ACP runner asks for permission, QwenPaw does not decide on the user's behalf.

Instead, it:

• pauses the delegated flow
• shows the permission details and available options
• waits for the user to choose how to proceed

This keeps delegated ACP execution aligned with the same user-controlled safety model used elsewhere in QwenPaw.

When to use ACP as a Tool Copy Section

Use this mode when:

• you want QwenPaw to collaborate with another agent runtime
• you have a specialized ACP-compatible external runner for a certain class of tasks
• you want QwenPaw to remain the primary orchestrator while delegating part of the work outward

ACP Tool vs MCP Copy Section

ACP as a Tool and MCP solve different problems:

• MCP connects QwenPaw to external services and tool servers
• ACP as a Tool connects QwenPaw to an external agent runtime

If you need APIs, databases, filesystems, or service integrations, use MCP.
If you need agent-to-agent collaboration, use ACP as a Tool.

QwenPaw as an ACP Server Copy Chapter

In this mode, QwenPaw exposes itself as an Agent Client Protocol (ACP) compliant agent service over stdio JSON-RPC. External clients, such as Zed, OpenCode, or any ACP-compatible editor, can connect to QwenPaw via the qwenpaw acp command and interact with it programmatically.

Quick Start Copy Section

# Start QwenPaw as an ACP agent
qwenpaw acp

# Use a specific agent profile
qwenpaw acp --agent mybot

# Use a custom workspace directory
qwenpaw acp --workspace /path/to/workspace

# Enable debug logging to stderr
qwenpaw acp --debug

The process communicates over stdin/stdout using the ACP JSON-RPC protocol. stderr is used for logging.

Supported ACP Methods Copy Section

Streaming Updates Copy Section

During a prompt call, the agent streams real-time updates back to the client via session_update notifications:

Declared Capabilities Copy Section

The agent declares the following capabilities during initialize:

{
  "load_session": true,
  "session_capabilities": {
    "close": {},
    "list": {},
    "resume": {}
  }
}

Session Config Options Copy Section

When a new session is created, the agent returns config options that the client can change via set_config_option:

Configuration Copy Section

The ACP agent resolves its configuration in the following order:

1. CLI arguments: --agent and --workspace take highest priority
2. WORKING_DIR config: read agents.active_agent from config.json inside WORKING_DIR (default ~/.qwenpaw, or ~/.copaw for legacy installations; overridable via the QWENPAW_WORKING_DIR environment variable)
3. Defaults: fall back to agent ID "default" and workspace directory WORKING_DIR/workspaces/default/

ACP Server vs ACP Tool Copy Chapter

Summary Copy Chapter

ACP in QwenPaw is not just one feature. It supports both directions:

• Expose QwenPaw outward as an ACP server
• Reach outward from QwenPaw to external ACP agents as delegated tools

If you are integrating QwenPaw into another client, start with ACP Server.
If you want QwenPaw to coordinate with another agent runtime, use ACP as a Tool.

File: website/public/docs/acp-integration.zh.md Copy Chapter

ACP 集成

QwenPaw 对 ACP（Agent Client Protocol） 提供两种互补的支持方式：

1. QwenPaw 将 ACP 作为 Tool 使用：QwenPaw 连接外部 ACP runner，并将其作为委托协作能力使用
2. QwenPaw 作为 ACP Server：外部客户端通过 ACP 连接到 QwenPaw

本页会同时介绍这两种模式，以及各自适合的使用场景。

QwenPaw 将 ACP 作为 Tool 使用 Copy Chapter

在这种模式下，QwenPaw 会作为 ACP client / orchestrator，连接已配置并启用的外部 ACP runner，并将它们接入当前会话，作为委托协作能力使用。

这类能力的实际调用入口是内置工具 delegate_external_agent。它适用于你希望 QwenPaw 与其他支持 ACP 的外部 agent runtime 协作的场景，例如源码中默认内置的 opencode、qwen_code、claude_code、codex。这些 agent 可参考 ACP 官方的 Agent 列表与接入说明：https://agentclientprotocol.com/get-started/agents。换句话说，QwenPaw 不是“直接和任意外部 agent 交互”，而是通过 ACP 配置中已注册的 runner，在会话内发起、继续、响应和关闭一次委托式协作。

这种模式能做什么 Copy Section

在这种模式下，QwenPaw 会通过内置的 delegate_external_agent 工具来：

• 启动一个外部 ACP runner 会话
• 向该 runner 发送后续消息
• 响应该 runner 发起的权限请求
• 在任务完成后关闭委托会话

从概念上看，这让 QwenPaw 可以把一个外部 agent 当作“可协作的工具能力”来使用，同时仍然由 QwenPaw 负责主会话编排。

如何配置外部 runner Copy Section

在使用外部 runner 之前，请先安装一个支持 ACP 协议的外部 agent，并完成登录、API Key 等必要配置，确保它可以在命令行中正常启动和使用。可参考 ACP 官方提供的 agent 列表：https://agentclientprotocol.com/get-started/agents。

命令行侧准备完成后，你可以在 QwenPaw 中配置自定义 runner，或直接使用内置 runner 与其协作。

外部 runner 需要先在 Workspace → ACP 页面中完成配置并启用，之后才能被 delegate_external_agent 调用。

当前 ACP 配置页支持为每个 runner 设置以下字段：

• enabled
• command
• args
• env
• trusted
• tool_parse_mode
• stdio_buffer_limit_bytes

其中：

• command 与 args 用于定义外部 runner 的启动命令及参数；
• env 用于传递环境变量；
• tool_parse_mode 与 stdio_buffer_limit_bytes 用于控制 ACP 输出解析方式及 stdio 缓冲行为。通常保持默认值即可，一般不需要修改。

对于 Linux/macOS，command 一般填写外部 agent 以 ACP 模式启动时使用的命令，例如 opencode、qwen，或者相应 ACP 插件的启动命令，例如 npx；args 则填写后续参数，例如 --acp、-y 等。注意每个参数都需要单独占一行。源码中默认内置了这些 runner 示例：opencode、qwen_code、claude_code、codex。你也可以在 ACP 页面中添加自定义 runner，只要它能够以 ACP 方式运行并被正确配置即可。

对于 Windows，在确保外部 agent 可以在命令行中正常启动和使用后，command 字段填写 cmd，args 的第一行填写 /c，后续再逐行填写真正要执行的命令及参数。注意每个参数都需要单独占一行。示例如下：

配置完成后，在工具栏中启用 delegate_external_agent 工具。

随后，你就可以在对话中明确指定要与哪个外部 agent 进行协作。

典型工作流 Copy Section

一个典型的委托式 ACP 工作流如下：

1. 在 Workspace → ACP 页面中配置并启用一个 runner。
2. 在会话中调用 delegate_external_agent(action="start", runner="...", message="...")，为该 runner 启动一条新的委托会话。
3. 如果需要继续协作，调用 delegate_external_agent(action="message", runner="...", message="...")，向已开启的 runner 会话发送后续消息。
4. 如果外部 runner 发起权限请求，先由用户从界面展示的选项中做出选择，再调用 delegate_external_agent(action="respond", runner="...", message="<exact option id>") 恢复执行。这里的 message 必须是权限请求中返回的精确 option id。
5. 委托任务完成后，调用 delegate_external_agent(action="close", runner="...") 关闭该 runner 会话。

你也可以在 start 或 message 时传入类似“请分析当前工作目录结构”或“请把你的自我介绍写入一个 Markdown 文件”这样的任务说明，但底层流程始终对应上述四种 action：start、message、respond、close。

支持的委托动作 Copy Section

当前委托流程支持以下动作类型：

权限处理 Copy Section

当外部 ACP runner 请求权限时，QwenPaw 不会替用户做决定。

相反，它会：

• 暂停当前委托流程
• 展示权限详情和可选项
• 等待用户明确选择如何继续

这样可以让委托式 ACP 执行与 QwenPaw 其他能力保持一致的用户可控安全模型。

什么时候使用 ACP as Tool Copy Section

以下场景适合使用这种模式：

• 你希望 QwenPaw 与另一个 agent runtime 协作
• 你有一个专门处理某类任务的 ACP-compatible 外部 runner
• 你希望由 QwenPaw 作为主控编排者，把部分工作委托给外部 agent

ACP Tool 与 MCP 的区别 Copy Section

ACP as Tool 和 MCP 解决的问题并不相同：

• MCP：让 QwenPaw 连接外部服务和工具服务器
• ACP as Tool：让 QwenPaw 连接外部 agent runtime

如果你需要接入 API、数据库、文件系统或服务能力，优先使用 MCP。
如果你需要 agent 与 agent 之间的协作，优先使用 ACP as Tool。

QwenPaw as ACP Server Copy Chapter

在这种模式下，QwenPaw 会通过 stdio JSON-RPC 将自己暴露为一个符合 Agent Client Protocol (ACP) 规范的智能体服务。外部客户端，如 Zed、OpenCode 或任何兼容 ACP 的编辑器，都可以通过 qwenpaw acp 命令连接到 QwenPaw，并以编程方式与之交互。

快速开始 Copy Section

# 启动 QwenPaw 作为 ACP 智能体
qwenpaw acp

# 使用指定的智能体配置
qwenpaw acp --agent mybot

# 使用自定义工作区目录
qwenpaw acp --workspace /path/to/workspace

# 启用调试日志（输出到 stderr）
qwenpaw acp --debug

进程通过 stdin/stdout 使用 ACP JSON-RPC 协议通信，stderr 用于日志输出。

支持的 ACP 方法 Copy Section

流式更新 Copy Section

在 prompt 调用过程中，智能体会通过 session_update 通知向客户端实时推送更新：

声明的能力 Copy Section

智能体会在 initialize 阶段声明以下能力：

{
  "load_session": true,
  "session_capabilities": {
    "close": {},
    "list": {},
    "resume": {}
  }
}

会话配置选项 Copy Section

创建新会话时，智能体会返回可通过 set_config_option 切换的配置项：

配置 Copy Section

ACP 智能体按以下优先级解析配置：

1. CLI 参数：--agent 和 --workspace 优先级最高
2. WORKING_DIR 配置：从 WORKING_DIR 内的 config.json 中读取 agents.active_agent（默认 ~/.qwenpaw，旧版安装为 ~/.copaw；可通过 QWENPAW_WORKING_DIR 环境变量覆盖）
3. 默认值：回退到智能体 ID "default" 和工作区目录 WORKING_DIR/workspaces/default/

ACP Server vs ACP Tool Copy Chapter

总结 Copy Chapter

ACP 在 QwenPaw 中并不是单一能力，而是支持两个方向：

• 向外暴露 QwenPaw：作为 ACP server
• 从 QwenPaw 向外协作：把外部 ACP agent 当作委托工具使用

如果你是要把 QwenPaw 接入另一个客户端，优先看 ACP Server。
如果你是希望 QwenPaw 去协调另一个 agent runtime，优先看 ACP as Tool。

File: website/public/docs/api-tutorial.en.md Copy Chapter

RESTful API

This document will guide you through using the RESTful API to interact with QwenPaw Agents.

Protocol Details: QwenPaw's API is based on an extension of the AgentScope Runtime protocol. For more details, see:
AgentScope Runtime Protocol Documentation (English)

⚠️ Security Warning:
If your QwenPaw instance is exposed to the public internet, strongly recommend enabling Web Login Authentication!
Public instances without authentication pose serious security risks, allowing anyone to access and control your Agents.
See the Web Authentication Token section at the end of this document.

Overview Copy Chapter

QwenPaw provides a RESTful API interface that allows you to interact with Agents via HTTP requests. Through the API, you can:

• Send messages to Agents and receive responses
• Manage multiple Agent instances
• Integrate with different channels

API Endpoint Copy Chapter

The main chat interface is:

POST /api/console/chat

Important: Note the path is /api/console/chat not /console/chat - all APIs are under the /api prefix.

Authentication Copy Chapter

Agent ID (Required) Copy Section

Specify the Agent to interact with via the X-Agent-Id header:

-H "X-Agent-Id: default"

Getting Your Agent ID:

1. Check the currently selected Agent in the top-left corner of Console
2. The Agent ID is typically displayed in the Agent selector
3. The default Agent ID is default

Localhost Auto-Bypass Authentication Copy Section

⚠️ Important Notice:

• Requests from localhost (127.0.0.1 or ::1) automatically bypass Web authentication
• This is designed for local development and CLI tools (qwenpaw) convenience
• Even if Web authentication is enabled, local requests do NOT require an Authorization token
• If accessing from a remote machine, you must provide a valid authentication token

Examples:

# Local request - No Authorization token needed
curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{"input": [...]}'

# Remote request - Authorization token required
curl -X POST http://your-server.com:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "X-Agent-Id: default" \
  -d '{"input": [...]}'

Tip: If Web Login Authentication is enabled and you're accessing remotely, you'll need to provide an authentication token. See the Web Authentication Token section at the end of this document.

Request Format Copy Chapter

The API uses a specific message format, similar to OpenAI's message format:

{
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Your message here"
        }
      ]
    }
  ],
  "session_id": "my-session",
  "user_id": "user-001",
  "channel": "console"
}

Parameter Explanation Copy Section

• input (required): Message array
  • role: Role, typically "user"
  • content: Content array
    • type: Content type, typically "text"
    • text: Actual text content
• session_id (optional): Session ID for maintaining context continuity
• user_id (optional): User ID to identify different users
• channel (recommended): Channel name, recommend setting to "console"

Making API Calls with cURL Copy Chapter

Basic Example Copy Section

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Hello, please introduce yourself"
          }
        ]
      }
    ],
    "session_id": "my-session",
    "user_id": "my-user",
    "channel": "console"
  }' \
  --no-buffer

Parameter Explanation Copy Section

• URL: http://localhost:8088/api/console/chat (modify if deployed elsewhere)
• Headers:
  • Content-Type: application/json: Specifies JSON format for the request body
  • X-Agent-Id: default: Specifies the Agent ID, defaults to default
• --no-buffer: Disables buffering for real-time streaming response

Complete Example Copy Section

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Please summarize today'\''s tasks for me"
          }
        ]
      }
    ],
    "session_id": "my-session-001",
    "user_id": "user-001",
    "channel": "console"
  }' \
  --no-buffer

Response Format Copy Chapter

The API returns Server-Sent Events (SSE) streaming responses, with each event prefixed with data::

data: {"sequence_number":0,"object":"response","status":"created",...}

data: {"sequence_number":1,"object":"response","status":"in_progress",...}

data: {"sequence_number":2,"object":"response","status":"in_progress","output":[{"role":"assistant","content":[{"type":"text","text":"Hello! I'm QwenPaw..."}]}],...}

data: {"sequence_number":3,"object":"response","status":"completed",...}

Response Field Explanation Copy Section

• sequence_number: Event sequence number
• object: Object type, typically "response"
• status: Status
  • created: Created
  • in_progress: In progress
  • completed: Completed
  • failed: Failed
• output: Output content (included during processing and completion)
  • role: Role, typically "assistant"
  • content: Content array
    • type: Content type
    • text: Text content
• error: Error information (included on failure)
• session_id: Session ID
• usage: Token usage statistics (included on completion)

Multi-turn Conversation Copy Chapter

QwenPaw automatically manages conversation context through session_id and user_id. Simply use the same session_id across different requests, and the system will automatically save and load conversation history:

First turn:

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "My name is Alice"}]
      }
    ],
    "session_id": "my-session-001",
    "user_id": "user-001",
    "channel": "console"
  }'

Second turn (using the same session_id):

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "Do you remember my name?"}]
      }
    ],
    "session_id": "my-session-001",
    "user_id": "user-001",
    "channel": "console"
  }'

Important:

• No need to include message history in input - the system automatically loads context based on session_id
• Keep session_id and user_id consistent to maintain conversation continuity

Error Handling Copy Chapter

Common Errors Copy Section

405 Method Not Allowed

{"detail":"Method Not Allowed"}

Solutions:

• Confirm you're using the POST method
• Verify the URL path is correct: /api/console/chat (note the /api prefix)

400 Bad Request

{
  "detail": "Validation error"
}

Solutions:

• Check the request body format is correct
• Ensure the input field exists and is properly formatted
• Verify JSON format is valid

404 Agent Not Found

{
  "detail": "Agent not found"
}

Solutions:

• Check the value of the X-Agent-Id header
• Confirm the Agent has been created in Console

503 Channel Not Found

{
  "detail": "Channel Console not found"
}

Solutions:

• Confirm the Console channel is enabled
• Check channel status in Console → Settings → Channels

Complete Python Example Copy Chapter

Using standard library urllib and json to handle SSE streams:

/* Detailed source-code truncated for AI context efficiency. */

Using requests Library (Recommended) Copy Section

If you have the requests library installed, you can use this more concise code:

/* Detailed source-code truncated for AI context efficiency. */

Complete JavaScript Example Copy Chapter

Using the fetch API in Node.js:

/* Detailed source-code truncated for AI context efficiency. */

Best Practices Copy Chapter

1. Session Management: Use consistent session_id to maintain conversation context
2. Error Handling: Always handle network errors and API error responses
3. Stream Processing: Use streaming reads to avoid memory issues
4. Connection Timeout: Set reasonable timeout values to avoid long waits
5. Retry Mechanism: Implement retry logic with exponential backoff
6. Logging: Log API calls for debugging and monitoring

Advanced Usage Copy Chapter

Multi-Agent Switching Copy Section

Interact with different Agents by changing the X-Agent-Id header:

# Chat with Agent 1
curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: agent-1" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"Hello"}]}],"channel":"console"}'

# Chat with Agent 2
curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: agent-2" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"Hello"}]}],"channel":"console"}'

Web Authentication Token (Optional) Copy Section

If Web Login Authentication is enabled (QWENPAW_AUTH_ENABLED=true), all API requests require an authentication token.

Register Account

First-time setup requires registering an admin account (QwenPaw uses single-user mode):

curl -X POST http://localhost:8088/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

Response Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

Register with Custom Token Expiration:

# Register and get a permanent token
curl -X POST http://localhost:8088/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "expires_in": 0
  }'

Important Notes:

• Registration endpoint can only be called once (single-user mode)
• Registration returns a login token immediately
• Returns {"detail":"User already registered"} error if a user already exists
• Supports custom token expiration via expires_in parameter (same as login)

If you need to re-register (e.g., forgot password or want to change account):

Method 1: Use CLI to reset password

qwenpaw auth reset-password

Method 2: Delete auth file and re-register

# Delete auth file
rm ~/.qwenpaw.secret/auth.json

# Or use QWENPAW_SECRET_DIR environment variable
rm "${QWENPAW_SECRET_DIR}/auth.json"

# Restart QwenPaw and re-register
qwenpaw app

Docker Deployment:

# Enter container to delete auth file
docker exec -it <container_name> rm /app/working.secret/auth.json

# Or use CLI to reset password
docker exec -it <container_name> qwenpaw auth reset-password

Auto-Registration (Optional):

You can also auto-create an account via environment variables when starting QwenPaw:

export QWENPAW_AUTH_ENABLED=true
export QWENPAW_AUTH_USERNAME=admin
export QWENPAW_AUTH_PASSWORD=admin123
qwenpaw app

This eliminates the need to manually call the registration API.

Obtaining an Authentication Token

After registration, use the login API to get a token

curl -X POST http://localhost:8088/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

Response Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

Customize Token Expiration:

You can specify token expiration time using the expires_in parameter (in seconds):

# Request a 30-day token
curl -X POST http://localhost:8088/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "expires_in": 2592000
  }'

# Request a permanent token (100-year validity)
curl -X POST http://localhost:8088/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "expires_in": 0
  }'

Common Expiration Values:

• 604800 = 7 days (default)
• 2592000 = 30 days
• 31536000 = 1 year
• 0 or -1 = permanent token (100 years)

Step 2: Use Token in API Requests

Add the returned token to the Authorization header:

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "Hello"}]
      }
    ],
    "session_id": "my-session",
    "user_id": "my-user",
    "channel": "console"
  }'

Token Characteristics

• Validity:
  • Default: 7 days
  • Customizable via expires_in parameter (supports permanent tokens)
  • Maximum: 100 years
• Format: HMAC-SHA256 signed token
• Storage: Store securely, do not hardcode in code
• Local Bypass: Requests from 127.0.0.1 or ::1 automatically skip authentication
• Multiple Tokens:
  • ⚠️ Each login creates a new token; old tokens are NOT automatically revoked
  • Multiple tokens can be used simultaneously if they are valid and not expired
  • If a token is compromised, you need to manually revoke all tokens

Revoking Tokens

If you need to invalidate tokens (e.g., logout, token leak, or security incident):

Method 1: Revoke a Single Token (Recommended for logout or specific device revocation)

# Revoke current token (logout current session)
curl -X POST http://localhost:8088/api/auth/revoke-token \
  -H "Authorization: Bearer <YOUR_CURRENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

# Revoke a specific token (e.g., leaked token)
curl -X POST http://localhost:8088/api/auth/revoke-token \
  -H "Authorization: Bearer <YOUR_CURRENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOi..."
  }'

Response Example:

{
  "message": "Current token has been revoked. Please login again.",
  "revoked": true,
  "revoked_current_token": true
}

Method 2: Revoke All Tokens (For security incidents or password reset)

curl -X POST http://localhost:8088/api/auth/revoke-all-tokens \
  -H "Authorization: Bearer <YOUR_CURRENT_TOKEN>"

Response Example:

{
  "message": "All tokens have been revoked. Please login again.",
  "revoked": true
}

Method 3: Change Password (Also revokes all tokens)

Changing your password automatically rotates the JWT secret, invalidating all old tokens:

curl -X POST http://localhost:8088/api/auth/update-profile \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "old_password",
    "new_password": "new_password"
  }'

Comparison of Revocation Methods:

Important Notes:

• After revocation, all clients must re-login to get new tokens
• Revocation is irreversible
• Recommended to revoke immediately when tokens are compromised or devices are lost
• If using permanent tokens (expires_in: 0), strongly recommend periodic manual revocation and reissuance

Disabling Authentication

If you don't want to use Web authentication, you can disable it:

Method 1: Remove Environment Variable

# Linux / macOS
unset QWENPAW_AUTH_ENABLED
qwenpaw app

# Windows (CMD)
set QWENPAW_AUTH_ENABLED=
qwenpaw app

# Windows (PowerShell)
Remove-Item Env:\QWENPAW_AUTH_ENABLED
qwenpaw app

Method 2: Docker Deployment

Remove the -e QWENPAW_AUTH_ENABLED=true parameter:

docker run -p 127.0.0.1:8088:8088 \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

Important:

• After disabling authentication, all API requests do not need the Authorization header
• If authentication is not enabled, no Authorization header is needed
• Check authentication status: GET /api/auth/status

Troubleshooting Copy Chapter

Cannot Connect to Server Copy Section

Verify QwenPaw service is running:

# Check service status
curl http://localhost:8088/api/version

Response Interrupted Copy Section

If streaming response is interrupted, check:

1. Network connection stability
2. Server is running properly
3. Model configuration is correct

Model Execution Failed Copy Section

If you see MODEL_EXECUTION_FAILED error:

1. Confirm models are properly configured in Console → Settings → Models
2. Check if API Key is valid
3. Verify model name is correct
4. Check the error details file (path provided in error message)

Related Documentation Copy Chapter

• Console Guide
• Security Settings
• Multi-Agent
• Channels Configuration

Getting Help Copy Chapter

If you encounter issues using the API:

1. Check the FAQ for common questions
2. Join the Community for assistance
3. Submit an Issue on GitHub

File: website/public/docs/api-tutorial.zh.md Copy Chapter

RESTful API 接口

本文档将指导你如何使用 RESTful API 调用 QwenPaw 的 Agent。

协议详情：QwenPaw 的 API 基于 AgentScope Runtime 协议的拓展。更多详细信息请参考：
AgentScope Runtime 协议文档（中文）

⚠️ 安全提醒：
如果您的 QwenPaw 实例对公网开放，强烈建议启用 Web 登录认证！
未启用认证的公网实例存在严重安全风险，任何人都可以访问和控制您的 Agent。
详见文档末尾的 Web 认证令牌 章节。

概述 Copy Chapter

QwenPaw 提供了 RESTful API 接口，允许你通过 HTTP 请求与 Agent 进行交互。通过 API，你可以：

• 发送消息给 Agent 并获取回复
• 管理多个 Agent 实例
• 与不同的频道集成

API 端点 Copy Chapter

主要的聊天接口为：

POST /api/console/chat

重要提示：请注意路径是 /api/console/chat 而不是 /console/chat，所有 API 都在 /api 前缀下。

认证 Copy Chapter

Agent ID（必需） Copy Section

通过 X-Agent-Id 头部指定要交互的 Agent：

-H "X-Agent-Id: default"

获取 Agent ID：

1. 在 Console 左上角查看当前选中的 Agent
2. Agent ID 通常显示在 Agent 选择器中
3. 默认的 Agent ID 为 default

Localhost 自动免认证 Copy Section

⚠️ 重要提示：

• 来自 localhost (127.0.0.1 或 ::1) 的请求会自动跳过 Web 认证
• 这是为了方便本地开发和 CLI 工具（qwenpaw）使用
• 即使启用了 Web 认证，本地请求也不需要提供 Authorization 令牌
• 如果从远程机器访问，则必须提供有效的认证令牌

示例：

# 本地请求 - 不需要 Authorization 令牌
curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{"input": [...]}'

# 远程请求 - 需要 Authorization 令牌
curl -X POST http://your-server.com:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "X-Agent-Id: default" \
  -d '{"input": [...]}'

提示：如果启用了 Web 登录认证并从远程访问，需要提供身份验证令牌。详见文档末尾的 Web 认证令牌 部分。

请求格式 Copy Chapter

API 使用特定的消息格式，与 OpenAI 的消息格式类似：

{
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "你的消息内容"
        }
      ]
    }
  ],
  "session_id": "my-session",
  "user_id": "user-001",
  "channel": "console"
}

参数说明 Copy Section

• input（必需）：消息数组
  • role: 角色，通常为 "user"
  • content: 内容数组
    • type: 内容类型，通常为 "text"
    • text: 实际的文本内容
• session_id（可选）：会话 ID，用于维持上下文连续性
• user_id（可选）：用户 ID，用于标识不同的用户
• channel（推荐）：频道名称，建议设置为 "console"

使用 cURL 调用 API Copy Chapter

基本示例 Copy Section

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "你好，请介绍一下自己"
          }
        ]
      }
    ],
    "session_id": "my-session",
    "user_id": "my-user",
    "channel": "console"
  }' \
  --no-buffer

参数说明 Copy Section

• URL：http://localhost:8088/api/console/chat（如果部署在其他地址，请相应修改）
• Headers：
  • Content-Type: application/json：指定请求体为 JSON 格式
  • X-Agent-Id: default：指定 Agent ID，默认为 default
• --no-buffer：禁用缓冲，实时显示流式响应

完整示例 Copy Section

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "帮我总结一下今天的任务"
          }
        ]
      }
    ],
    "session_id": "my-session-001",
    "user_id": "user-001",
    "channel": "console"
  }' \
  --no-buffer

响应格式 Copy Chapter

API 返回 Server-Sent Events (SSE) 流式响应，每个事件以 data: 开头：

data: {"sequence_number":0,"object":"response","status":"created",...}

data: {"sequence_number":1,"object":"response","status":"in_progress",...}

data: {"sequence_number":2,"object":"response","status":"in_progress","output":[{"role":"assistant","content":[{"type":"text","text":"你好！我是 QwenPaw..."}]}],...}

data: {"sequence_number":3,"object":"response","status":"completed",...}

响应字段说明 Copy Section

• sequence_number: 事件序号
• object: 对象类型，通常为 "response"
• status: 状态
  • created: 已创建
  • in_progress: 处理中
  • completed: 已完成
  • failed: 失败
• output: 输出内容（处理中和完成时包含）
  • role: 角色，通常为 "assistant"
  • content: 内容数组
    • type: 内容类型
    • text: 文本内容
• error: 错误信息（失败时包含）
• session_id: 会话 ID
• usage: 令牌使用统计（完成时包含）

多轮对话 Copy Chapter

QwenPaw 通过 session_id 和 user_id 自动管理对话上下文。只需在不同的请求中使用相同的 session_id，系统会自动保存和加载对话历史：

第一轮对话：

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "我的名字是小明"}]
      }
    ],
    "session_id": "my-session-001",
    "user_id": "user-001",
    "channel": "console"
  }'

第二轮对话（使用相同的 session_id）：

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "你还记得我的名字吗？"}]
      }
    ],
    "session_id": "my-session-001",
    "user_id": "user-001",
    "channel": "console"
  }'

重要提示：

• 无需在 input 中包含历史消息，系统会自动基于 session_id 加载上下文
• 保持 session_id 和 user_id 一致即可维持对话连续性

错误处理 Copy Chapter

常见错误 Copy Section

405 Method Not Allowed

{"detail":"Method Not Allowed"}

解决方法：

• 确认使用的是 POST 方法
• 确认 URL 路径正确：/api/console/chat（注意 /api 前缀）

400 Bad Request

{
  "detail": "Validation error"
}

解决方法：

• 检查请求体格式是否正确
• 确认 input 字段存在且格式正确
• 验证 JSON 格式有效

404 Agent Not Found

{
  "detail": "Agent not found"
}

解决方法：

• 检查 X-Agent-Id 头部的值
• 确认该 Agent 已在 Console 中创建

503 Channel Not Found

{
  "detail": "Channel Console not found"
}

解决方法：

• 确认 Console 频道已启用
• 在 Console → Settings → Channels 中检查频道状态

完整 Python 示例 Copy Chapter

使用标准库 urllib 和 json 处理 SSE 流：

/* Detailed source-code truncated for AI context efficiency. */

使用 requests 库（推荐） Copy Section

如果你安装了 requests 库，可以使用以下更简洁的代码：

/* Detailed source-code truncated for AI context efficiency. */

完整 JavaScript 示例 Copy Chapter

在 Node.js 中使用 fetch API：

/* Detailed source-code truncated for AI context efficiency. */

最佳实践 Copy Chapter

1. 会话管理：使用一致的 session_id 来维持对话上下文
2. 错误处理：始终处理网络错误和 API 错误响应
3. 流式处理：使用流式读取避免内存问题
4. 连接超时：设置合理的超时时间，避免长时间等待
5. 重试机制：实现指数退避的重试逻辑
6. 日志记录：记录 API 调用日志，便于调试和监控

进阶用法 Copy Chapter

多 Agent 切换 Copy Section

与不同的 Agent 交互只需更改 X-Agent-Id 头部：

# 与 Agent 1 对话
curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: agent-1" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"你好"}]}],"channel":"console"}'

# 与 Agent 2 对话
curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: agent-2" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"你好"}]}],"channel":"console"}'

Web 认证令牌（可选） Copy Section

如果启用了 Web 登录认证（QWENPAW_AUTH_ENABLED=true），所有 API 请求都需要提供身份验证令牌。

注册账号

首次使用需要先注册管理员账号（QwenPaw 采用单用户模式）：

curl -X POST http://localhost:8088/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

响应示例：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

注册时指定令牌有效期：

# 注册并获取永久令牌
curl -X POST http://localhost:8088/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "expires_in": 0
  }'

注意事项：

• 注册接口只能调用一次（单用户模式）
• 注册成功后会直接返回登录令牌
• 如果已有用户，会返回 {"detail":"User already registered"} 错误
• 支持通过 expires_in 参数自定义令牌有效期（同登录接口）

如果需要重新注册（例如忘记密码或想更换账号）：

方法 1：使用 CLI 重置密码

qwenpaw auth reset-password

方法 2：删除认证文件后重新注册

# 删除认证文件
rm ~/.qwenpaw.secret/auth.json

# 或者使用 QWENPAW_SECRET_DIR 环境变量
rm "${QWENPAW_SECRET_DIR}/auth.json"

# 重启 QwenPaw 后重新注册
qwenpaw app

Docker 部署：

# 进入容器删除认证文件
docker exec -it <容器名> rm /app/working.secret/auth.json

# 或者使用 CLI 重置密码
docker exec -it <容器名> qwenpaw auth reset-password

自动注册（可选）：

你也可以在启动 QwenPaw 时通过环境变量自动创建账号：

export QWENPAW_AUTH_ENABLED=true
export QWENPAW_AUTH_USERNAME=admin
export QWENPAW_AUTH_PASSWORD=admin123
qwenpaw app

这样就无需手动调用注册 API。

获取认证令牌

注册后，使用登录 API 获取令牌

curl -X POST http://localhost:8088/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

响应示例：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

自定义令牌有效期：

你可以通过 expires_in 参数指定令牌的有效时长（单位：秒）：

# 申请 30 天有效期的令牌
curl -X POST http://localhost:8088/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "expires_in": 2592000
  }'

# 申请永久令牌（100 年有效期）
curl -X POST http://localhost:8088/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "expires_in": 0
  }'

常用有效期：

• 604800 = 7 天（默认）
• 2592000 = 30 天
• 31536000 = 1 年
• 0 或 -1 = 永久令牌（100 年）

步骤 2：在 API 请求中使用令牌

将返回的 token 添加到 Authorization 头部：

curl -X POST http://localhost:8088/api/console/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Agent-Id: default" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "你好"}]
      }
    ],
    "session_id": "my-session",
    "user_id": "my-user",
    "channel": "console"
  }'

令牌特性

• 有效期：
  • 默认：7 天
  • 可通过 expires_in 参数自定义（支持永久令牌）
  • 最长：100 年
• 格式：HMAC-SHA256 签名令牌
• 存储：建议安全存储，不要硬编码在代码中
• 本地免认证：来自 127.0.0.1 或 ::1 的请求自动跳过认证
• 多令牌共存：
  • ⚠️ 每次登录都会创建新令牌，旧令牌不会自动失效
  • 只要令牌未过期且签名有效，多个令牌可以同时使用
  • 这意味着如果令牌泄露，需要手动撤销

撤销令牌

如果你想使令牌失效（例如令牌泄露、注销登录或安全事件），有以下方法：

方法 1：撤销单个令牌（推荐用于注销或撤销特定设备）

# 撤销当前令牌（注销当前会话）
curl -X POST http://localhost:8088/api/auth/revoke-token \
  -H "Authorization: Bearer <YOUR_CURRENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

# 撤销指定令牌（例如泄露的令牌）
curl -X POST http://localhost:8088/api/auth/revoke-token \
  -H "Authorization: Bearer <YOUR_CURRENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOi..."
  }'

响应示例：

{
  "message": "Current token has been revoked. Please login again.",
  "revoked": true,
  "revoked_current_token": true
}

方法 2：撤销所有令牌（用于安全事件或密码重置）

curl -X POST http://localhost:8088/api/auth/revoke-all-tokens \
  -H "Authorization: Bearer <YOUR_CURRENT_TOKEN>"

响应示例：

{
  "message": "All tokens have been revoked. Please login again.",
  "revoked": true
}

方法 3：修改密码（同时撤销所有令牌）

修改密码时会自动轮换 JWT 密钥，使所有旧令牌失效：

curl -X POST http://localhost:8088/api/auth/update-profile \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "old_password",
    "new_password": "new_password"
  }'

撤销方法对比：

注意事项：

• 撤销后，所有客户端都需要重新登录获取新令牌
• 撤销操作不可逆
• 建议在令牌泄露或设备丢失时立即撤销
• 如果使用永久令牌（expires_in: 0），强烈建议定期手动撤销并重新申请

关闭认证

如果你不想使用 Web 认证，可以关闭它：

方法 1：移除环境变量

# Linux / macOS
unset QWENPAW_AUTH_ENABLED
qwenpaw app

# Windows (CMD)
set QWENPAW_AUTH_ENABLED=
qwenpaw app

# Windows (PowerShell)
Remove-Item Env:\QWENPAW_AUTH_ENABLED
qwenpaw app

方法 2：Docker 部署

移除 -e QWENPAW_AUTH_ENABLED=true 参数：

docker run -p 127.0.0.1:8088:8088 \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

重要提示：

• 关闭认证后，所有 API 请求无需 Authorization 头部
• 如果未启用认证，无需提供 Authorization 头部
• 检查认证状态：GET /api/auth/status

故障排查 Copy Chapter

无法连接到服务器 Copy Section

确认 QwenPaw 服务正在运行：

# 检查服务状态
curl http://localhost:8088/api/version

响应中断 Copy Section

如果流式响应中断，检查：

1. 网络连接是否稳定
2. 服务器是否正常运行
3. 模型配置是否正确

模型执行失败 Copy Section

如果看到 MODEL_EXECUTION_FAILED 错误：

1. 确认在 Console → Settings → Models 中正确配置了模型
2. 检查 API Key 是否有效
3. 验证模型名称是否正确
4. 查看错误详情文件（错误消息中会提供路径）

相关文档 Copy Chapter

• Console 使用指南
• 安全设置
• 多智能体
• 频道配置

获取帮助 Copy Chapter

如果你在使用 API 时遇到问题：

1. 查看 FAQ 了解常见问题
2. 加入 社区 寻求帮助
3. 在 GitHub 上提交 Issue

2. Official Technical Reference & Guides (agentscope-ai/docs) Copy Chapter

File: README.md Copy Chapter

AgentScope Documentation

This repository is the source for the unified
AgentScope documentation site. It publishes English and
Chinese documentation for AgentScope and
ReMe with
Mintlify.

Documentation Sets Copy Chapter

The two projects share one site but keep separate content and release models:

ReMe Documentation Copy Chapter

The ReMe repository README is the concise
project entry point. This repository owns the complete public documentation: concepts,
verified workflows, integrations, reference material, troubleshooting, and contribution
guidance.

ReMe documentation should preserve the product principles expressed by its README:

• memory files are user-owned source data;
• indexes, graphs, and caches are rebuildable derived state;
• conversations and resources become correctable, traceable Markdown memory;
• Python, AgentScope, MCP, CLI, HTTP, plugins, and Skills are integration boundaries over
  the same file-native memory model.

The current ReMe content is organized by user goal:

Chinese pages mirror the same structure under reme/latest/zh/. Update both languages
together and keep their intent, headings, examples, and links aligned.

Local Development Copy Chapter

Use an active Node.js LTS release (Node 20 or 22).

Install the Mintlify CLI:

npm i mint

From the repository root, validate the site or start a preview:

mint validate
mint dev

The preview is available at http://localhost:3000 by default.

Repository Structure Copy Chapter

.
├── versions/
│   └── <version>/{en,zh}/   # Versioned AgentScope documentation
├── reme/
│   └── latest/{en,zh}/      # Current ReMe documentation
├── images/                  # Shared static assets
├── scripts/                 # Documentation maintenance scripts
├── docs.json                # Mintlify navigation and redirects
└── CLAUDE.md                # Writing and review guidelines

Content Boundaries Copy Chapter

Keep public documentation focused on user goals and stable behavior:

• Verify ReMe behavior against current code, public schemas, tests, CLI help, and
  reme/config/default.yaml.
• Explain the stable contract and link to authoritative source instead of duplicating
  implementation details.
• Keep concepts focused on product intent; place detailed development mechanics in source
  code, tests, and repository-local guidance.
• Lead with the outcome, use direct language, and introduce every table, image, diagram,
  and code block.
• Start each MDX page with title and description frontmatter.

See CLAUDE.md for the complete writing and component guidelines.

Version Management Copy Chapter

AgentScope documentation is immutable within each published version directory. For a new
AgentScope release:

1. Copy the latest relevant version into a new project version directory.
2. Update every version-specific internal link in the copied pages.
3. Add the version under the matching project tab for both languages in docs.json.
4. Point the relevant latest or stable redirect at the new version.
5. Run mint validate before submitting the change.

AgentScope versions can be created with scripts/create-version.sh.

ReMe does not keep historical release directories. Update reme/latest/{en,zh}/
directly, keep canonical internal links under /reme/latest/..., and leave its
docs.json version label as latest. The /reme/stable/... alias and obsolete
numeric-version URLs redirect to the current pages for compatibility.

Contribution Workflow Copy Chapter

When adding or updating documentation:

1. Verify the behavior in the corresponding project source.
2. Update the correct project, version, and language pages.
3. For ReMe, make the equivalent English and Chinese changes in reme/latest/.
4. Update docs.json when navigation, versions, or compatibility redirects change.
5. Check page links and run mint validate before submitting a pull request.

Run these checks from the repository root before submitting:

git diff --check
mint validate

Resources Copy Chapter

• AgentScope GitHub
• ReMe GitHub
• ReMe English documentation
• ReMe 中文文档
• Mintlify Documentation

File: reme/README.md Copy Chapter

ReMe documentation

ReMe documentation is part of the unified Mintlify site in this repository.

• latest/ contains the current en/ and zh/ MDX pages and is updated in place.
• ReMe does not maintain numbered or historical documentation directories.
• Shared ReMe media lives in images/reme/.
• Navigation is defined by the ReMe tab for each language in docs.json.
• Canonical internal links use /reme/latest/...; compatibility redirects preserve old URLs.

Keep the documentation focused on product philosophy, verified user workflows, and stable contracts. Implementation details belong in the ReMe source, schemas, tests, and runtime help.