Site icon Efficient Coder

Fix Every OpenClaw & GLM API Error on Windows: Complete Troubleshooting Guide

高效码农

OpenClaw + GLM API on Windows: A Complete Troubleshooting Guide (With Every Error Solved)

Getting OpenClaw Gateway running on Windows with a GLM model backend is absolutely doable — but the path there involves a handful of non-obvious errors that can stall you for hours if you don’t know what to look for.

This guide documents every failure point encountered during a real setup: garbled error messages, PowerShell execution blocks, a Gateway that claimed to start but didn’t, persistent API rate limits, and a misconfigured base URL hiding in plain sight. Each section opens with the exact error, explains why it happens, and gives you the precise fix.

Table of Contents

  1. Error 1 — schtasks Fails With Garbled Output
  2. Error 2 — PowerShell Refuses to Run the Script
  3. Error 3 — Gateway Says “Restarted” But Isn’t Actually Running
  4. Error 4 — API Rate Limit Reached on GLM
  5. Error 5 — Wrong Base URL in the Config File
  6. Choosing the Right GLM Model for Your Quota
  7. Concurrency Settings and Rate Limits
  8. Gateway Local Auth and Token Security
  9. Full Troubleshooting Flowchart
  10. Quick-Reference Checklist
  11. One-Page Summary Table
  12. FAQ

Error 1 — schtasks Fails With Garbled Output {#error-1}

The core question: Why does the installer show question marks and boxes instead of a real error message?

The garbled output is not a sign that your system is incompatible with OpenClaw. It is a character encoding mismatch. Windows Chinese-locale systems output error messages in GBK encoding by default, while OpenClaw reads the output as UTF-8. The result looks like this:

Gateway install failed: Error: schtasks create failed: ����: �ܾ����ʡ�

How to Read the Real Error

Switch the active code page to UTF-8 before running the installer:

chcp 65001

Once the encoding is aligned, the actual error message becomes readable. In most cases it translates to something like “Access is denied” — a permissions issue, not a compatibility problem.

Fix: Run as Administrator

The installer needs to create a Windows Scheduled Task, which requires elevated privileges.

  • Right-click PowerShell → Run as Administrator
  • Re-run the install command in the elevated window:
openclaw gateway install

On corporate machines joined to a domain, Group Policy may prevent even administrators from creating scheduled tasks. If that is the case, the fix has to come from your IT team at the domain policy level.

Lesson learned: Garbled output is never the real error — it is a mask over the real error. The first step in any Windows debugging session should be aligning encodings so you can actually read what the system is telling you.

Error 2 — PowerShell Refuses to Run the Script {#error-2}

The core question: What does “running scripts is disabled on this system” mean, and how do you fix it safely?

After resolving the permissions issue, the next run may produce this:

openclaw : File C:\nvm4w\nodejs\openclaw.ps1 cannot be loaded
because running scripts is disabled on this system.
    + CategoryInfo : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

This is Windows PowerShell’s Execution Policy — a security feature that controls which scripts are allowed to run. The default setting on many systems blocks locally created or unsigned scripts entirely.

Three Ways to Fix It

Method Command Scope Recommendation
Per-session only Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass Current window only ✅ Safest
Current user permanent Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned Your user account ✅ Good for regular use
Machine-wide Set-ExecutionPolicy -ExecutionPolicy Unrestricted Entire system ❌ Avoid

The recommended approach for a one-off installation:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
openclaw gateway install

-Scope Process means the policy change evaporates when you close the PowerShell window. Nothing is permanently altered on the system.

Check Your Current Policy

Get-ExecutionPolicy -List

This shows the effective policy at every scope level: MachinePolicy, UserPolicy, Process, CurrentUser, and LocalMachine. If MachinePolicy or UserPolicy is set to Restricted, a domain administrator controls that setting and local changes won’t override it.

Error 3 — Gateway Says “Restarted” But Isn’t Actually Running {#error-3}

The core question: Does “Restarted Scheduled Task: OpenClaw Gateway” mean the Gateway is running?

No. It means the scheduled task was triggered. Whether the underlying process is actually alive is a separate question.

After a successful install, OpenClaw outputs:

Restarted Scheduled Task: OpenClaw Gateway

This is easy to misread as a confirmation that the Gateway is up. In practice, the task can be triggered and then exit immediately due to a missing dependency, port conflict, or configuration error — all without any visible indication.

Verify the Gateway Is Actually Running

Step 1 — Check the scheduled task status:

schtasks /query /tn "OpenClaw*" /fo LIST /v

Look for two fields:

  • Status — should be Running. If it shows Ready or Unknown, the process is not active.
  • Last Result — should be 0. Any non-zero value indicates the last run ended with an error.

Step 2 — Check for the live process:

Get-Process | Where-Object { $_.Name -like "*openclaw*" -or $_.Name -like "*gateway*" }

If this returns nothing, the Gateway process does not exist.

Why this matters for rate limiting: In the troubleshooting session documented here, the Gateway was not actually running during early API tests. Every request bypassed the local proxy and hit the GLM API directly. Combined with the retry logic and high concurrency settings in the config, this flooded the API with requests and triggered rate limiting — a problem that looked like a quota issue but was actually caused by the Gateway not running.

Error 4 — API Rate Limit Reached on GLM {#error-4}

The core question: Why does GLM keep returning a rate limit error even after Gateway starts?

The exact error from the OpenClaw agent log:

[agent/embedded] embedded run agent end:
runId=0040b97a-dc26-45a2-81ba-ad63e33bd46b
isError=true
error=⚠️ API rate limit reached. Please try again later.

Rate limiting on GLM can have multiple causes, and they often stack. The two most common in this setup:

  1. Gateway was not running, so requests hit the API directly at full concurrency
  2. The base URL was misconfigured, routing requests to an endpoint with stricter limits (covered in the next section)

Diagnosis Sequence

Before assuming it is a quota problem, work through this order:

  1. Confirm Gateway is running (see Error 3 above)
  2. Verify the base URL in config.json (see Error 5 below)
  3. Temporarily switch to a less rate-limited model to isolate whether the problem is configuration or quota
  4. If the issue persists on all models, log into open.bigmodel.cn and check remaining token balance and RPM limits

Error 5 — Wrong Base URL in the Config File {#error-5}

The core question: Can a single extra path segment in a URL cause rate limiting instead of a 404?

Yes — and that is exactly what happened here. The configuration wizard generated a non-standard base URL:

https://open.bigmodel.cn/api/coding/paas/v4

The correct standard endpoint is:

https://open.bigmodel.cn/api/paas/v4

The extra /coding/ segment is the difference. The wrong URL does not return a 404. Instead, it appears to route to a more restricted endpoint that applies tighter rate limits — so the error surface looks like a quota issue, not a configuration mistake.

How to Fix It

Open your OpenClaw config.json and locate the models.providers.zai node. Update the baseUrl field:

"zai": {
  "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
  "api": "openai-completions",
  "models": [
    {
      "id": "glm-4.7-flashx",
      "name": "GLM-4.7 FlashX",
      "reasoning": true,
      "input": ["text"],
      "contextWindow": 204800,
      "maxTokens": 131072
    }
  ]
}

After saving, restart the Gateway and re-test.

Reflection: This is the kind of bug that is hard to catch because the system does not tell you the URL is wrong — it just behaves differently than expected. Any time API errors appear without a clear cause, auditing the base URL should be one of the first checks, not the last.

Choosing the Right GLM Model for Your Quota {#model-selection}

Start with the most permissive model to validate your setup. Switch to the target model once everything is confirmed working.

The configuration supports four GLM models with meaningfully different rate limit characteristics:

Model ID Display Name Rate Limit Tolerance Best Use Case
glm-5 GLM-5 Strictest Production, after quota confirmed
glm-4.7 GLM-4.7 Moderate General use
glm-4.7-flash GLM-4.7 Flash Lenient High-frequency tasks
glm-4.7-flashx GLM-4.7 FlashX Most permissive Debugging and validation

During initial setup and troubleshooting, set the primary model to glm-4.7-flashx:

"agents": {
  "defaults": {
    "model": {
      "primary": "zai/glm-4.7-flashx"
    }
  }
}

If FlashX responds normally: the configuration and network path are correct. The rate limit you saw with GLM-5 is a quota issue — upgrade your plan on the BigModel platform.

If FlashX also rate limits: the problem is account-wide, not model-specific. Check your account balance and overall API limits.

Once everything is verified working, switch primary back to your intended model.

Concurrency Settings and Rate Limits {#concurrency}

High concurrency with a low-quota API key is a reliable recipe for rate limiting.

The default configuration in this setup is:

"maxConcurrent": 4,
"subagents": {
  "maxConcurrent": 8
}

This means up to 12 simultaneous requests can reach the GLM API at once. For a free-tier or entry-level API key with a low RPM cap, this will trigger rate limiting almost immediately under any real workload.

Recommended Starting Values for Low-Quota Accounts

"maxConcurrent": 1,
"subagents": {
  "maxConcurrent": 2
}

Test at these settings first. Once you confirm your account’s actual RPM limit from the BigModel dashboard, raise the concurrency values incrementally until you find the stable ceiling.

Gateway Local Auth and Token Security {#auth}

The Gateway token is stored in plaintext. On shared machines, file permissions matter.

The Gateway auth section of config.json looks like this:

"gateway": {
  "mode": "local",
  "auth": {
    "mode": "token",
    "token": "2e8e1c7ac18d0e5299aee47f2a642985aa50a3f159c2bab9"
  }
}

The local mode means the Gateway only serves requests on the local machine. The token provides a basic layer of authentication between OpenClaw clients and the Gateway process.

Since this token is stored as plaintext in a JSON file, access control at the filesystem level is important. On a shared development machine, restrict read access to the config file using Windows file permissions (right-click → Properties → Security) or ACL rules, so other users on the same machine cannot read and reuse the token.

Full Troubleshooting Flowchart {#flowchart}

Install command runs
  └─ Garbled output / schtasks fails
       └─ Run: chcp 65001 → read actual error
            └─ "Access denied" → Re-run as Administrator
                 └─ "Scripts disabled" → Set-ExecutionPolicy Bypass (Process scope)
                      └─ Install succeeds
                           └─ "Restarted Scheduled Task" shown
                                └─ Verify with schtasks /query + Get-Process
                                     └─ Gateway not actually running → check logs
                                     └─ Gateway confirmed running
                                          └─ API rate limit error
                                               └─ Check baseUrl in config.json
                                                    └─ Remove /coding/ from path
                                               └─ Switch to glm-4.7-flashx to isolate
                                                    └─ FlashX works → GLM-5 quota issue
                                                    └─ FlashX also fails → account-level quota

Quick-Reference Checklist {#checklist}

Use this before reporting an issue or opening a support ticket:

  • [ ] Opened PowerShell as Administrator
  • [ ] Set execution policy: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  • [ ] Ran openclaw gateway install in the elevated window
  • [ ] Confirmed Gateway process exists: Get-Process | Where-Object { $_.Name -like "*openclaw*" }
  • [ ] Confirmed task status: schtasks /query /tn "OpenClaw*" /fo LIST /v — Status = Running, Last Result = 0
  • [ ] Verified baseUrl in config.json is https://open.bigmodel.cn/api/paas/v4 (no /coding/)
  • [ ] Temporarily set primary model to zai/glm-4.7-flashx for validation
  • [ ] Lowered maxConcurrent to 1–2 while confirming account quota
  • [ ] Restricted read access to config.json on shared machines

One-Page Summary {#summary}

Problem Root Cause Fix
Garbled install error GBK/UTF-8 encoding mismatch chcp 65001, then re-read the actual message
schtasks create failed Insufficient privileges Run PowerShell as Administrator
Scripts disabled error PowerShell Execution Policy Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Gateway “restarted” but not running Task triggered ≠ process alive Get-Process + schtasks /query to confirm
Persistent API rate limit Gateway not running + wrong baseURL + high concurrency Fix all three in sequence
Wrong baseUrl Config wizard generated non-standard path Remove /coding/ from the URL
GLM-5 rate limited Model quota too low Switch to glm-4.7-flashx to test; upgrade quota if needed
Rate limit under normal load maxConcurrent too high for account tier Start at 1, raise incrementally

FAQ {#faq}

Q: The installer shows question marks and symbols. Is OpenClaw incompatible with my Windows version?

No. The symbols are a character encoding mismatch between the Windows error output (GBK) and how OpenClaw reads it (UTF-8). Run chcp 65001 in PowerShell to switch the code page, then re-run the installer. The real error will be readable — usually a permissions issue.

Q: Is it safe to set PowerShell Execution Policy to Bypass?

When scoped to -Scope Process, yes. The change only applies to the current PowerShell session and disappears when you close the window. It does not permanently alter system or user-level policy settings.

Q: OpenClaw showed “Restarted Scheduled Task: OpenClaw Gateway” — is the Gateway running?

Not necessarily. That message confirms the scheduled task was triggered, not that the process is alive. Always verify with Get-Process and schtasks /query before assuming the Gateway is operational.

Q: Why does the wrong base URL cause rate limiting instead of a 404 error?

The erroneous /coding/ path segment appears to route to a different, more restricted API endpoint on BigModel’s infrastructure rather than returning a “not found” response. The endpoint exists — it just has tighter limits, which surfaces as rate limiting rather than a routing error.

Q: What is the practical difference between GLM-5 and GLM-4.7 FlashX?

Based on the configuration, both models share the same context window (204,800 tokens) and max token output (131,072). The key difference is rate limit tolerance: GLM-5 is the flagship reasoning model with stricter quota limits, while GLM-4.7 FlashX is designed for high-frequency use with more permissive rate limits. Use FlashX to validate your setup before switching to GLM-5.

Q: How high should I set maxConcurrent?

Start at 1 for both maxConcurrent and subagents.maxConcurrent. Check your account’s RPM limit on the BigModel dashboard, then raise the values incrementally. The default values of 4 and 8 can easily exceed free-tier or low-tier quota limits.

Q: The config file stores the Gateway token in plaintext — should I be concerned?

On a single-user personal machine, the risk is low. On a shared development server or multi-user workstation, you should restrict read access to the config.json file at the OS level to prevent other users from reading and reusing the token.

Q: My company’s domain policy blocks the Execution Policy change. What now?

Domain-level policies (MachinePolicy or UserPolicy scope) override local changes made with Set-ExecutionPolicy. You will need your IT administrator to either adjust the domain policy or sign the OpenClaw .ps1 script with a trusted certificate. There is no end-user workaround for domain-enforced restrictions.

Exit mobile version