QwenPaw

QwenPaw: Install and first job

This is page 2 of 8. It installs QwenPaw on Windows or a Mac, turns on its safety switches before anything else, connects a free model, and runs one small job that stays inside the agent's own folder.

Install on Windows

You need Windows 10 or newer on a PC with a regular 64-bit (x64) chip. This guide could not confirm whether the app works on Windows PCs with an ARM chip.

1. Download the installer

Open the official release page:

https://github.com/agentscope-ai/QwenPaw/releases/tag/v2.3.0

Under Assets, download QwenPaw-Tauri-2.3.0-Windows-setup.exe. It is a big file, about 924 MB.

What you should see a downloaded file named QwenPaw-Tauri-2.3.0-Windows-setup.exe.

2. Run the installer

Open the file. The installer is not signed by Microsoft, so Windows may show a blue SmartScreen warning. The QwenPaw desktop guide says to click More info, then Run anyway, but only do this with the file you got from the release page above.

Follow the setup wizard. QwenPaw installs into your own user folder and makes shortcuts on the desktop and in the Start menu.

What you should see the wizard finishes, and QwenPaw Desktop is in your Start menu. There is also a second shortcut called QwenPaw Desktop (Debug), which you only need if something breaks.

3. Open QwenPaw

Open QwenPaw Desktop, and do not choose Run as administrator. The first start can take 10 to 60 seconds, sometimes longer, so wait for the window to open by itself.

If the window stays blank and white, the docs say you are missing a Microsoft part called WebView2. Install it from Microsoft's WebView2 page, then open QwenPaw again.

The app runs QwenPaw's control page, which the docs call the Console, in the background and shows it in this window. The rest of these pages use the Console's menu names, like Settings and Workspace, and this guide could not confirm that every desktop screen matches the Console docs exactly.

To remove QwenPaw later, go to Windows Settings, then Apps, then Installed apps, and uninstall QwenPaw Desktop.

What you should see a QwenPaw window with a menu on the left. Stop here and read "Turn on the safety switches first" below.

4. If the app will not start: paste a command

The desktop app is the path to follow, but if it will not start, the README gives a script that installs everything instead.

Open PowerShell from the Start menu, not as an administrator, and paste:

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

When it finishes, close PowerShell and open a new one. Type these two lines, one at a time:

qwenpaw init --defaults
qwenpaw app

Then open http://127.0.0.1:8088/ in your browser. The address 127.0.0.1 is localhost and 8088 is QwenPaw's port, so the page is not open to the internet, and you should leave it that way.

The README says --defaults also says yes to an anonymous usage report. That report lists the QwenPaw version, the install method, your system version, your chip type, and whether you have a graphics chip, and the README says it sends no personal data or files.

What you should see the QwenPaw Console in your browser at http://127.0.0.1:8088/.

Install on a Mac

You need macOS 14 (Sonoma) or newer. QwenPaw recommends a Mac with Apple silicon (M1, M2, M3, M4), and on an Intel Mac, the docs say the app may work but may not be able to run the built-in local models.

To check your Mac, open the Apple menu and choose About This Mac. Look for the macOS version number, and note that a line that says Chip with an Apple M name means Apple silicon.

1. Download the zip file

Open the official release page:

https://github.com/agentscope-ai/QwenPaw/releases/tag/v2.3.0

Under Assets, download QwenPaw-Tauri-2.3.0-macOS.zip. It is a big file, about 1.2 GB.

What you should see a downloaded file named QwenPaw-Tauri-2.3.0-macOS.zip.

2. Unzip and move it

Double-click the zip file, then drag the QwenPaw Desktop.app that comes out into your Applications folder.

What you should see QwenPaw Desktop in your Applications folder.

3. Get past Apple's warning

QwenPaw is not notarized, which means Apple has not checked it for harmful software, so your Mac will refuse to open it the first time. Apple's own support page warns that overriding this check is the most common way a Mac gets harmful software, so only do it with the file you got from the release page above.

Apple's official way:

Try to open QwenPaw Desktop once. Your Mac will show a warning and stop.
Open the Apple menu, then System Settings, then Privacy & Security.
Scroll down to Security. Click Open Anyway. Apple says this button only shows up for about an hour after you try to open the app.
Enter your login password and click OK.

QwenPaw's own guide also suggests Control-click (or right-click) on the app, choose Open, then click Open again. Either way works, according to the docs.

QwenPaw's guide also lists a Terminal command that strips the warning off. Do not use it, because the QwenPaw guide itself says it "completely removes security checks."

What you should see your Mac saves QwenPaw as an exception. After this, you can open it by double-clicking.

4. Open QwenPaw

The first start can take 10 to 60 seconds, sometimes longer, so wait for the window to open by itself.

Your Mac may ask whether QwenPaw can get to files on your Desktop. Click Don't Allow: the docs say the app still runs, and your agent will work in its own folder, not on your Desktop.

To remove QwenPaw later, drag the app to the Trash. The docs say to also delete the hidden .qwenpaw folder in your home folder.

What you should see a QwenPaw window with a menu on the left. Stop here and read the next section.

5. If the app will not start: paste a command

The desktop app is the path to follow, but if it will not start, the README gives a script that installs everything instead.

Open Terminal (it is in Applications, inside Utilities) and paste:

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

When it finishes, close Terminal and open a new window. Type these two lines, one at a time:

qwenpaw init --defaults
qwenpaw app

Then open http://127.0.0.1:8088/ in your browser. The address 127.0.0.1 is localhost and 8088 is QwenPaw's port, so the page is not open to the internet, and you should leave it that way.

If you already manage Python yourself (version 3.11, 3.12, or 3.13), on either computer, the README also lists pip install qwenpaw followed by the same two lines.

What you should see the QwenPaw Console in your browser at http://127.0.0.1:8088/.

Turn on the safety switches first

Do this whole section before you give QwenPaw any job.

What QwenPaw's walls really do

QwenPaw can put a sandbox around the commands the agent runs, but only when your system has one and its switch is on. It uses Seatbelt on a Mac and a restricted account setting on Windows 10 and 11. On an older system with no sandbox, the mode is none, which means no wall at all.

The switch starts off. In v2.3.0, the setting behind it, security.sandbox_enabled, starts as false, and the Console's own description says that with it off, commands "run directly without the sandbox (no approval prompt)." Step 2 below turns it on. A QwenPaw blog post from July 2026 described the off setting differently, so read the description next to the switch on your own screen.

Even with the sandbox on, the docs say:

The whole disk is readable. By default, a command can read every file your account can read, but it can only write in the agent's own folder. Some private folders, like ~/.ssh, are blocked by default.
The internet is wide open. The network setting allows everything.
On Windows, the full sandbox needs administrator rights. Without them, the docs say you get a weaker version that still limits writing. This guide does not tell you to run QwenPaw as an administrator, because an agent running as administrator turns every yes you click into an administrator-level yes.
On Windows, you get the weaker sandbox, and the Console will suggest more. When you turn the switch on without administrator rights, the Console shows "Sandbox is running in non-administrator mode" and suggests restarting QwenPaw with Run as administrator. Do not. The weaker sandbox is still on: it holds commands to writing in the agent's folder, but it does not limit reading or the network, so keep counting on STRICT and on switching off the command tool.
The sandbox covers commands. This guide could not confirm that QwenPaw's file-writing tool is held to the agent's folder in the same way.

This guide could not find a simple on-screen switch that turns off the "whole disk is readable" default.

QwenPaw also has a checker called Tool Guard. It starts on AUTO, which only stops a command when one of its rules flags it, and everything else runs without asking.

1. Turn Tool Guard up to STRICT

STRICT is the strictest documented setting, because it makes QwenPaw ask you before every tool it uses.

The security docs say to change it under Settings → Agents, on the agent's configuration card, while the Console guide calls that page Settings → Agent management. Open the card for your agent (it starts out named Default Agent) and set the approval level to STRICT.

The four choices are STRICT, SMART, AUTO, and OFF. Do not pick SMART, which lets low-risk steps through, and do not pick OFF.

If you cannot find the approval level, stop, and do not give QwenPaw a job until you can.

What you should see STRICT chosen for your agent.

2. Turn on the extra checks

Go to Settings → Security.

On the Tool Guard tab, make sure Tool Guard is on, and turn on all seven shell evasion checks. These catch tricks that hide a command inside other text, and the docs say they all start off.
On the same Tool Guard tab, turn on Enable Sandbox Execution, just below the Tool Guard switch. On a Mac, a yellow notice may say "Sandbox is running in administrator mode"; that notice is written for Windows, and QwenPaw is not running as an administrator.
On the File Guard tab, make sure File Guard is on. It blocks the folder where QwenPaw keeps your keys.
On the Skill Scanner tab, set the mode to Block. The scanner starts on Warn, which lets a risky skill through with only a warning.

Click Save where the page shows it.

What you should see Tool Guard on with all seven checks on, Enable Sandbox Execution on, File Guard on, and Skill Scanner on Block.

3. Use the agent's own folder

QwenPaw already gives each agent its own workspace, and that is your dedicated folder. Put nothing personal in it, and do not point QwenPaw at your Documents or your whole home folder.

The default workspace is here:

Windows: C:\Users\(your name)\.qwenpaw\workspaces\default
Mac: ~/.qwenpaw/workspaces/default, inside your home folder

This folder is where the sandbox lets commands write, but remember that commands can still read the rest of the disk.

What you should see no extra folders added to QwenPaw.

4. No email, bank, or public chat bot

Stay logged out of email, your bank, and online stores in any browser QwenPaw can open.

Skip QwenPaw's email feature, and leave every chat app off for now. The docs say every chat app starts open to anyone who finds the bot, and there is more on that in Phone and schedules.

What you should see no email and no chat apps connected.

5. Set a spend cap if you use a paid key

QwenPaw has no monthly dollar limit. It has a Token Usage page under Settings that shows how much you used, but that is a record, not a limit.

The built-in local models and a free Gemini key with no card have no bill to cap. If you ever add a paid key, set a monthly limit on that company's website first, before you paste the key into QwenPaw. The screen names for OpenAI and Anthropic are in the safety chapter.

What you should see either no paid key, or a monthly limit saved at the paid company.

Connect a model

Pick one of these two options; both are free.

Option A: the built-in local model

Go to Settings → Models.
Open QwenPaw Local.
Click Download llama.cpp, the free program that runs the model on your computer.
QwenPaw recommends QwenPaw-Flash models that fit your computer. Pick the one it recommends and download it.
Click Start.

The docs say a started model becomes the default model by itself, and only one local model runs at a time.

The docs also say QwenPaw Local is still being tested, and it may have problems with some graphics chips. If it gives you trouble, the docs suggest Ollama or LM Studio instead, and both are in the same Models list.

Remember the research: on 8 GB or 16 GB of memory, expect a chat partner, not a strong agent.

What you should see a QwenPaw-Flash model that says it is running, and a chat box where you can type.

Option B: a free Google Gemini key

Go to Google AI Studio and create an API key. You do not need a card, but Google may use free-tier prompts to improve its products.
In QwenPaw, go to Settings → Models.
Open Google Gemini. Paste your key into the API Key box and save.
Click Test Connection.
At the top of the page, under Default LLM, pick Google Gemini and a model. Click Save.

Put the key only on this page, and do not paste it into the chat.

This guide could not confirm which Gemini models are on the free tier today, so pick one of the Gemini models QwenPaw shows you.

What you should see Google Gemini chosen under Default LLM, and a chat box where you can type.

Or use a local model

QwenPaw Local in Option A is QwenPaw's own way to run a model on your computer, and it needs nothing else installed. If you already use Ollama, or QwenPaw Local gives you trouble, QwenPaw can use Ollama instead. Install Ollama and download a model with Run a local model with Ollama, and note that QwenPaw's model docs ask for a context length of at least 32k in Ollama's settings.

In QwenPaw, go to Settings → Models and open the Ollama provider.
Set its Base URL to http://localhost:11434, Ollama's usual address. When the box is empty, the v2.3.0 code uses http://127.0.0.1:11434, which is the same place.
On the provider's Models page, click Update model list so your Ollama models show up. The docs call this button Discover Models, but the v2.3.0 app text says Update model list.
Click Test Connection.
Under Default LLM, pick Ollama and your model, then click Save.

If you run QwenPaw's Docker image from Advanced features instead of the desktop app, localhost means the container itself. In that case, add --add-host=host.docker.internal:host-gateway to the docker run command and set the Base URL to http://host.docker.internal:11434.

What you should see Test Connection succeeds, and your Ollama model is chosen under Default LLM.

Every agent in this guide reaches Ollama at port 11434, but the exact address differs: agents in Docker use host.docker.internal, and some need /v1 on the end. Connect it to your agent gives each one's address.

Your first safe job

This job stays inside the agent's own folder and does not use the web.

1. Turn off commands and the browser for now

Go to Workspace → Tools, the page that turns built-in tools on and off by name.

Turn off the tool that runs commands (the security docs call it execute_shell_command) and the browser tool (the tool docs call it browser). You can turn them back on later.

What you should see those two tools switched off.

2. Give it the job

Open Chat and click New Chat. You can type:

Work only inside your own workspace folder. Create a new file called first-note.md with a three-line packing list for a weekend trip. Then read it back to me. Do not run commands, open a browser, or touch any other folder.

Because of STRICT, QwenPaw will stop and ask before each step. The request shows up in the chat and on the Inbox page, so read it before you click.

Approve writing or reading first-note.md inside the .qwenpaw workspace folder.
Reject anything that mentions delete, move, your home folder, Documents, Desktop, email, or a browser.

If you walk away, the docs say a request that times out counts as rejected.

What you should see QwenPaw asking before each step, then a three-line packing list in the chat.

3. Check the folder yourself

Open the workspace folder:

Windows: click the address bar in File Explorer, paste %USERPROFILE%\.qwenpaw\workspaces\default, and press Enter.
Mac: in Finder, choose Go, then Go to Folder, paste ~/.qwenpaw/workspaces/default, and press Return.

You will see some files QwenPaw made for itself, like agent.json, and you should leave those alone.

What you should see a new first-note.md with your three lines. Nothing outside that folder should have changed.

Sources

Checked 14 November 2026.

QwenPaw research notes.
First-hour safety checklist.
QwenPaw README, for install options, desktop Beta, Mac warning, API key, local models, usage report.
QwenPaw v2.3.0 release, for both desktop files and their sizes.
QwenPaw desktop app guide, for Windows 10+ x64, macOS 14+, SmartScreen, not notarized, WebView2, uninstall.
QwenPaw quick start.
QwenPaw security, for Tool Guard levels, shell evasion checks, File Guard, sandbox defaults, Windows administrator note, Skill Scanner.
QwenPaw v2.3.0 config source, for security.sandbox_enabled starts as false.
QwenPaw Console text, for Enable Sandbox Execution label, its description, and the Windows "non-administrator mode" warning.
QwenPaw v2.3.0 sandbox status code and Tool Guard tab, for the unelevated sandbox staying on and the warning it shows.
QwenPaw ACP integration, for the sandbox setting "defaults to false".
QwenPaw sandbox blog post, July 2026, for the older description of the off setting.
QwenPaw models, for QwenPaw Local, cloud keys, Default LLM.
QwenPaw v2.3.0 models docs, for the Ollama provider, the 32k context length, Discover Models, Test Connection, and the Docker address http://host.docker.internal:11434.
QwenPaw v2.3.0 Ollama provider code, for the empty Base URL falling back to http://127.0.0.1:11434.
QwenPaw v2.3.0 Console text, for Update model list, Test Connection, and the Ollama address hint http://localhost:11434.
QwenPaw README, Docker section, for --add-host=host.docker.internal:host-gateway.
QwenPaw MCP and built-in tools, for the browser tool name.
QwenPaw Console, for menu names, Inbox approvals, Tools page.
QwenPaw config and working folder, for workspace path, approval level default.
Apple: Open a Mac app from an unknown developer.
Apple: Safely open apps on your Mac.

The QwenPaw docs website, qwenpaw.agentscope.io, only returned its home page to this guide's checks. The links above go to the same docs on GitHub.

Continue to Files, the browser, and memory.