refactor: rename CLOUDFLARE_API_TOKEN to CLOUDFLARE_WORKERS_TOKEN for proxy configuration

CHANGELOG.md

@@ -7,7 +7,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - **Custom OpenAI-compatible provider registration** — HuggingClaw can now register a custom provider at startup with `CUSTOM_PROVIDER_NAME`, `CUSTOM_BASE_URL`, and `CUSTOM_MODEL_ID`, so you can point `LLM_MODEL` at your own OpenAI-compatible endpoint without modifying the OpenClaw CLI
-- **Automatic Cloudflare outbound proxy setup** — HuggingClaw can now provision and use a Cloudflare Worker proxy for blocked outbound traffic from a `CLOUDFLARE_API_TOKEN`, with the same transparent proxy model used in Hugging8n
+- **Automatic Cloudflare outbound proxy setup** — HuggingClaw can now provision and use a Cloudflare Worker proxy for blocked outbound traffic from a `CLOUDFLARE_WORKERS_TOKEN`, using the same transparent proxy model used in Hugging8n
 
 ### Changed
 

README.md

@@ -14,8 +14,8 @@ secrets:
     description: The model ID to use, e.g. openai/gpt-4o or google/gemini-2.5-flash.
   - name: GATEWAY_TOKEN
     description: A strong password or token to secure your OpenClaw Control UI.
-  - name: CLOUDFLARE_API_TOKEN
-    description: Optional Cloudflare API token for automatic outbound proxy setup.
+  - name: CLOUDFLARE_WORKERS_TOKEN
+    description: Optional Cloudflare API token for automatic Cloudflare Worker proxy setup.
 ---
 
 <!-- Badges -->
@@ -105,7 +105,7 @@ To chat via Telegram:
 
 1. Create a bot via [@BotFather](https://t.me/BotFather): send `/newbot`, follow prompts, and copy the bot token.
 2. Find your Telegram user ID with [@userinfobot](https://t.me/userinfobot).
-3. Add `CLOUDFLARE_API_TOKEN` in Space secrets to let HuggingClaw auto-provision the outbound proxy, or set `CLOUDFLARE_PROXY_URL` manually if you already have a Worker.
+3. Add `CLOUDFLARE_WORKERS_TOKEN` in Space secrets to let HuggingClaw auto-provision the outbound proxy, or set `CLOUDFLARE_PROXY_URL` manually if you already have a Worker.
 4. Add these secrets in Settings → Secrets. After restarting, the bot should appear online on Telegram.
 
 | Variable | Default | Description |
@@ -120,10 +120,20 @@ Hugging Face Spaces sometimes blocks outgoing connections to Telegram, WhatsApp-
 
 Automatic setup:
 
-1. Create a Cloudflare API token with Workers edit permissions.
-2. Add `CLOUDFLARE_API_TOKEN` as a Space secret.
+1. Create a Cloudflare API Token for your account's Workers.
+2. Add `CLOUDFLARE_WORKERS_TOKEN` as a Space secret.
 3. Restart the Space.
 
+Recommended token setup:
+
+- Secret name: `CLOUDFLARE_WORKERS_TOKEN`
+- Token type: `API Token`
+- Account permission: `Workers Scripts: Edit`
+- Resource scope: your target Cloudflare account
+- Account auto-discovery is built in; `CLOUDFLARE_ACCOUNT_ID` is not required
+
+Do not use a Global API key, tunnel token, worker secret, or another Cloudflare credential here.
+
 HuggingClaw will:
 
 - create or update a Worker named from your Space host
@@ -143,8 +153,8 @@ Optional variables:
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `CLOUDFLARE_API_TOKEN` | — | Cloudflare API token for automatic Worker setup |
-| `CLOUDFLARE_ACCOUNT_ID` | auto | Optional Cloudflare account override |
+| `CLOUDFLARE_WORKERS_TOKEN` | — | Cloudflare API token for automatic Worker setup |
+| `CLOUDFLARE_ACCOUNT_ID` | auto | Optional Cloudflare account ID override if you want to pin a specific account |
 | `CLOUDFLARE_WORKER_NAME` | derived from Space host | Optional Worker script name |
 | `CLOUDFLARE_PROXY_URL` | auto | Use an existing Worker URL instead of auto-provisioning |
 | `CLOUDFLARE_PROXY_SECRET` | auto | Optional shared secret override |
@@ -286,6 +296,7 @@ Register a custom endpoint at startup without modifying the CLI.
 > `CUSTOM_PROVIDER_NAME` cannot override built-in providers (openai, anthropic, etc.).
 
 **Example (Modal):**
+
 ```bash
 CUSTOM_PROVIDER_NAME=modal
 CUSTOM_BASE_URL=https://api.us-west-2.modal.direct/v1

cloudflare-proxy-setup.py

@@ -138,7 +138,7 @@ def write_env(proxy_url: str, proxy_secret: str) -> None:
 def main() -> int:
     existing_url = os.environ.get("CLOUDFLARE_PROXY_URL", "").strip()
     existing_secret = os.environ.get("CLOUDFLARE_PROXY_SECRET", "").strip()
-    api_token = os.environ.get("CLOUDFLARE_API_TOKEN", "").strip()
+    api_token = os.environ.get("CLOUDFLARE_WORKERS_TOKEN", "").strip()
 
     if existing_url:
       if existing_secret:
@@ -191,6 +191,14 @@ def main() -> int:
         return 0
     except urllib.error.HTTPError as error:
         detail = error.read().decode("utf-8", errors="replace")
+        if error.code == 403 and '"code":9109' in detail:
+            print(
+                "☁️ Cloudflare proxy setup failed: invalid Workers token. "
+                "Use a Cloudflare API Token in CLOUDFLARE_WORKERS_TOKEN "
+                "(not a Global API Key, tunnel token, or worker secret). "
+                "For auto-setup, it should have account-level 'Workers Scripts: Edit'. "
+                "The setup can auto-discover your account; CLOUDFLARE_ACCOUNT_ID is not required."
+            )
         print(f"☁️ Cloudflare proxy setup failed: HTTP {error.code} {detail}")
         return 1
     except Exception as error:

start.sh

@@ -152,7 +152,7 @@ else
 fi
 
 CF_PROXY_ENV_FILE="/tmp/huggingclaw-cloudflare-proxy.env"
-if [ -n "${CLOUDFLARE_API_TOKEN:-}" ] || [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
+if [ -n "${CLOUDFLARE_WORKERS_TOKEN:-}" ] || [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
   echo "☁️ Preparing Cloudflare outbound proxy..."
   python3 /home/node/app/cloudflare-proxy-setup.py || true
   if [ -f "$CF_PROXY_ENV_FILE" ]; then