QwenPaw

QwenPaw: Fixes

This is page 6 of 8. It covers ten common problems, each in the order symptom, likely cause, and fix, starting with installing and ending with how to remove QwenPaw cleanly.

The fixes come from QwenPaw's FAQ, desktop guide, command docs, and source code as checked on 14 November 2026, when the newest release was v2.3.0. Where this guide could not confirm a detail, it says so.

The Windows installer will not run or finish

Symptom: Windows shows a blue SmartScreen warning, or the install script finishes but typing qwenpaw gives an error that it is not recognized.

Likely cause: the installer is not signed by Microsoft, which the desktop guide says is why SmartScreen warns. For the script, the FAQ says Windows LTSC and other locked-down work PCs can run PowerShell in Constrained Language Mode, which stops the script from adding QwenPaw to your Path.

Fix: for SmartScreen, click More info, then Run anyway, but only for the file from the v2.3.0 release page. For the script, add %USERPROFILE%\.qwenpaw\bin to your Path yourself, as the FAQ describes, or use the desktop app instead. If you install with pip, the FAQ says you need Python >= 3.11, < 3.14.

The Mac says the app cannot be opened

Symptom: your Mac refuses to open QwenPaw Desktop and says it cannot check the app for harmful software.

Likely cause: QwenPaw is not notarized by Apple.

Fix: follow the Apple steps on Install and first job: try to open the app once, then click Open Anyway under System Settings → Privacy & Security within about an hour. Do not use the Terminal command from QwenPaw's guide that the guide itself says "completely removes security checks."

The app opens blank or never finishes starting

Symptom: the window stays white, or it is still loading after a few minutes.

Likely cause: on Windows, a blank window means the Microsoft WebView2 part is missing, which the desktop guide says can happen after an offline install. Otherwise, the program running behind the window may have hit an error.

Fix: for a blank window, install WebView2 from Microsoft's WebView2 page and restart the app. For anything else, open the QwenPaw Desktop (Debug) shortcut, which shows the logs live in a terminal window. The log files are %USERPROFILE%\.qwenpaw\desktop.log and %LOCALAPPDATA%\io.agentscope.qwenpaw.desktop\logs\qwenpaw-desktop.log on Windows, or ~/.qwenpaw/desktop.log and ~/Library/Logs/io.agentscope.qwenpaw.desktop/qwenpaw-desktop.log on a Mac.

Windows says port 8088 is in use or forbidden

Symptom: an error such as Address already in use, or your browser cannot connect to http://127.0.0.1:8088/.

Likely cause: the FAQ says Hyper-V and WSL2 on Windows can reserve a range of ports that includes 8088, QwenPaw's default.

Fix: check with this command in PowerShell:

netsh interface ipv4 show excludedportrange protocol=tcp

If 8088 falls inside a listed range, start QwenPaw from PowerShell on another port with qwenpaw app --port 8090 and open http://127.0.0.1:8090/. The FAQ says the desktop app always uses 8088, so this needs the script install. The FAQ's other option changes a Windows setting with administrator rights and "may affect other services," so this guide does not suggest it.

The model says your key is missing or wrong

Symptom: a chat reply shows an error such as You didn't provide an API key with error code 401, or the model name is not found.

Likely cause: the FAQ says either no key is set, or one field is wrong: the base_url, the key itself, or the model name.

Fix: go to Settings → Models, open your provider, and paste the key again with no extra spaces. Check that the model name matches the provider's exactly, because the FAQ says it is case-sensitive. Then click Test Connection. If that still fails, the FAQ says to open a GitHub issue with the error detail file path from the message, your provider, your model, and your QwenPaw version, but remove your key from anything you post.

Replies stop, or the chat shows three dots for minutes

Symptom: the agent stops partway with a rate-limit message, or a chat shows three moving dots and no answer.

Likely cause: your provider sent a rate-limit error, often called a 429, because you used up your free-tier allowance for the minute or the day. QwenPaw's v2.3.0 code retries three times by default and pauses 5 seconds after a rate-limit error. In an earlier version, a user's report of endless dots was traced to background memory and Heartbeat jobs hitting the limit and holding up every chat for up to 5 minutes.

Fix: wait a few minutes and try again, and check your usage on the provider's website. Auto-Memory and Auto-Dream use your model in the background, so turning off long-term memory in Workspace → Configuration saves allowance on a free key. The v2.3.0 release notes say it now tells you about long rate-limit waits, so update if you are on an older version.

A local model forgets the task or gives up early

Symptom: with Ollama or LM Studio, the agent loses track of the job after a few steps, or tool calls fail.

Likely cause: the FAQ says this is usually not a QwenPaw bug but a context length that is set too small in Ollama or LM Studio.

Fix: raise the context length to at least 32K. In LM Studio, the FAQ says to use Settings → Model Defaults → Default Context Length and set 32768 or more. On 8 GB or 16 GB of memory, a small model may still be too weak for multi-step work, so try a cloud key for longer jobs.

The agent repeats itself or goes in circles

Symptom: the agent runs the same step again and again, or keeps asking to approve the same thing.

Likely cause: some models get stuck in a loop. A QwenPaw issue says loop protection arrived in v2.0.0, and the v2.2.2 release notes fixed a case where it ended a task "without new repeated tool calls." Each task also stops after 100 steps by default, which the v2.3.0 code calls max_iters.

Fix: type /stop in the chat to end the task, and reject any repeated approval. Then start a fresh chat with a shorter, clearer prompt, or switch to a stronger model. If loops come back on long jobs, lower max iterations on the ReAct Agent card in Workspace → Configuration so a stuck task ends sooner. This guide could not confirm a setting that turns loop protection on or off.

You need to stop it right now

Symptom: the agent is doing something you did not ask for, or you just want everything to stop.

Likely cause: none needed. Stop first and find out why later.

Fix: type /stop in the chat. The docs call it the "Highest priority command that processes concurrently even when tasks are running," and they warn it "may result in partial data loss." For a task in another chat, use /stop session=<session_id>, and /deny rejects a waiting approval. In v2.3.0, closing the last desktop window asks whether to Run in background or Quit completely, and only Quit completely stops everything, as does Quit App in the tray menu. With the script install, qwenpaw shutdown will "Force stop the running QwenPaw app processes." Afterward, turn off any scheduled task under Control → Cron Jobs and any chat app under Control → Channels before you open QwenPaw again. This guide could not confirm the label of the stop button in the chat window. If the agent already changed a file, read After it does something wrong before the next job.

Update it safely

Make a copy before you update. Read the release notes or GitHub Releases before you install a new version. This guide could not confirm that a current update turns a safety switch off. The older jump from v0.0.x to v0.1.0 migrated the working folder, which is why the copy comes first.

  1. Copy the folders that hold settings, memory, and keys. On Windows, copy %USERPROFILE%\.qwenpaw, %USERPROFILE%\.qwenpaw.secret, and %USERPROFILE%\.qwenpaw.backups. On a Mac, copy ~/.qwenpaw, ~/.qwenpaw.secret, and ~/.qwenpaw.backups. The workspace for this guide is inside .qwenpaw, at workspaces\default on Windows or workspaces/default on a Mac. You can also open Settings, then Backups (called Backup in the docs), click Create Backup, switch the dialog from Full Backup to Partial Backup so Secrets stays unchecked, and click Create. That archive is stored in .qwenpaw.backups. If you run QwenPaw in Docker, do not delete the volumes qwenpaw-data, qwenpaw-secrets, and qwenpaw-backups. Windows File History or Previous Versions, and Mac Time Machine, are places a folder copy can live.

What you should see a dated copy of those three folders, or the same three Docker volume names still in use.

  1. Update with the same method you used to install, after you have read the release notes. In the desktop app, QwenPaw checks for a new version when it starts and prompts you to update. Click Update Now (called Install and Restart in the FAQ), and confirm Close and update, only after you have read the notes and finished open tasks. Download in Background (called Update Later in the FAQ) downloads the update while you keep working. You can also download a build yourself from GitHub Releases or the download page. If you used the one-line script, run that installer again, then start QwenPaw with qwenpaw app. If you used pip, run qwenpaw update, then qwenpaw app. If you used Docker, pull the new image and start the container again with the same three volumes. Stop the old container first if port 8088 is already taken. Do not delete those volumes.
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

What you should see QwenPaw opens again, and your old workspace is still there.

Startup update check.

  1. Check the version, then run one small test. In the chat, type /daemon version. From a terminal, qwenpaw daemon version prints the version, the working folder, and the log path. Then ask QwenPaw to read first-note.md in the default workspace and not change any file. Leave STRICT on.

What you should see a version number, and a reply that quotes the note without writing a new file.

You want to uninstall or start over cleanly

Symptom: you want QwenPaw gone, or you want a fresh start without old settings and memory.

Likely cause: QwenPaw keeps your data in more than one hidden folder in your home folder: .qwenpaw for settings, workspaces, and memory, .qwenpaw.secret for your model keys, and .qwenpaw.backups for backups.

Fix: for the desktop app, uninstall QwenPaw Desktop under Windows Settings, then Apps, then Installed apps, or drag it to the Trash on a Mac. For the script install, the README says qwenpaw uninstall "keeps config and data," while qwenpaw uninstall --purge "removes everything." The v2.3.0 source shows that --purge deletes .qwenpaw but not .qwenpaw.secret or .qwenpaw.backups, so delete those two folders yourself. To reset but keep the program, qwenpaw clean --dry-run lists what would be removed, and qwenpaw clean removes everything under ~/.qwenpaw. Finally, delete or revoke your model key on the provider's website. This guide could not confirm which folders the Windows desktop uninstaller removes.

Sources

Checked 14 November 2026.

Next

Continue to Advanced features.