fix(digitalocean): use canonical DIGITALOCEAN_ACCESS_TOKEN env var

Replaces all references to DO_API_TOKEN with DIGITALOCEAN_ACCESS_TOKEN,
matching DigitalOcean's official CLI and API documentation. This includes
TypeScript source, tests, shell scripts, Packer config, CI workflows,
and documentation.

Supersedes #3068 (rebased onto current main).

Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: louisgv

.claude/skills/setup-agent-team/qa-fixtures-prompt.md

@@ -31,7 +31,7 @@ Cloud credentials are stored in `~/.config/spawn/{cloud}.json` (loaded by `sh/sh
 
 For each cloud with a fixture directory, check if its required env vars are set:
 - **hetzner**: `HCLOUD_TOKEN`
-- **digitalocean**: `DO_API_TOKEN`
+- **digitalocean**: `DIGITALOCEAN_ACCESS_TOKEN`
 - **aws**: `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`
 
 Skip clouds where credentials are missing (log which ones).
@@ -53,11 +53,11 @@ curl -s -H "Authorization: Bearer ${HCLOUD_TOKEN}" "https://api.hetzner.cloud/v1
 curl -s -H "Authorization: Bearer ${HCLOUD_TOKEN}" "https://api.hetzner.cloud/v1/locations"
 ```
 
-### DigitalOcean (needs DO_API_TOKEN)
+### DigitalOcean (needs DIGITALOCEAN_ACCESS_TOKEN)
 ```bash
-curl -s -H "Authorization: Bearer ${DO_API_TOKEN}" "https://api.digitalocean.com/v2/account/keys"
-curl -s -H "Authorization: Bearer ${DO_API_TOKEN}" "https://api.digitalocean.com/v2/sizes"
-curl -s -H "Authorization: Bearer ${DO_API_TOKEN}" "https://api.digitalocean.com/v2/regions"
+curl -s -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" "https://api.digitalocean.com/v2/account/keys"
+curl -s -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" "https://api.digitalocean.com/v2/sizes"
+curl -s -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" "https://api.digitalocean.com/v2/regions"
 ```
 
 For any other cloud directories found, read their TypeScript module in `packages/cli/src/{cloud}/` to discover the API base URL and auth pattern, then call equivalent GET-only endpoints.

.github/workflows/packer-snapshots.yml

@@ -71,18 +71,18 @@ jobs:
       - name: Generate variables file
         run: |
           jq -n \
-            --arg token "$DO_API_TOKEN" \
+            --arg token "$DIGITALOCEAN_ACCESS_TOKEN" \
             --arg agent "$AGENT_NAME" \
             --arg tier "$TIER" \
             --argjson install "$INSTALL_COMMANDS" \
             '{
-              do_api_token: $token,
+              digitalocean_access_token: $token,
               agent_name: $agent,
               cloud_init_tier: $tier,
               install_commands: $install
             }' > packer/auto.pkrvars.json
         env:
-          DO_API_TOKEN: ${{ secrets.DO_API_TOKEN }}
+          DIGITALOCEAN_ACCESS_TOKEN: ${{ secrets.DO_API_TOKEN }}
           AGENT_NAME: ${{ matrix.agent }}
           TIER: ${{ steps.config.outputs.tier }}
           INSTALL_COMMANDS: ${{ steps.config.outputs.install }}
@@ -96,7 +96,7 @@ jobs:
         if: cancelled()
         run: |
           # Filter by spawn-packer tag to avoid destroying builder droplets from other workflows
-          DROPLET_IDS=$(curl -s -H "Authorization: Bearer ${DO_API_TOKEN}" \
+          DROPLET_IDS=$(curl -s -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" \
             "https://api.digitalocean.com/v2/droplets?per_page=200&tag_name=spawn-packer" \
             | jq -r '.droplets[].id')
 
@@ -107,28 +107,28 @@ jobs:
 
           for ID in $DROPLET_IDS; do
             echo "Destroying orphaned builder droplet: ${ID}"
-            curl -s -X DELETE -H "Authorization: Bearer ${DO_API_TOKEN}" \
+            curl -s -X DELETE -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" \
               "https://api.digitalocean.com/v2/droplets/${ID}" || true
           done
         env:
-          DO_API_TOKEN: ${{ secrets.DO_API_TOKEN }}
+          DIGITALOCEAN_ACCESS_TOKEN: ${{ secrets.DO_API_TOKEN }}
 
       - name: Cleanup old snapshots
         if: success()
         run: |
           PREFIX="spawn-${AGENT_NAME}-"
-          SNAPSHOTS=$(curl -s -H "Authorization: Bearer ${DO_API_TOKEN}" \
+          SNAPSHOTS=$(curl -s -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" \
             "https://api.digitalocean.com/v2/images?private=true&per_page=100" \
             | jq -r --arg prefix "$PREFIX" \
               '[.images[] | select(.name | startswith($prefix))] | sort_by(.created_at) | reverse | .[1:] | .[].id')
 
           for ID in $SNAPSHOTS; do
             echo "Deleting old snapshot: ${ID}"
-            curl -s -X DELETE -H "Authorization: Bearer ${DO_API_TOKEN}" \
+            curl -s -X DELETE -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" \
               "https://api.digitalocean.com/v2/images/${ID}" || true
           done
         env:
-          DO_API_TOKEN: ${{ secrets.DO_API_TOKEN }}
+          DIGITALOCEAN_ACCESS_TOKEN: ${{ secrets.DO_API_TOKEN }}
           AGENT_NAME: ${{ matrix.agent }}
 
       - name: Submit to DO Marketplace
@@ -162,7 +162,7 @@ jobs:
           HTTP_CODE=$(curl -s -o /tmp/mp-response.json -w "%{http_code}" \
             -X PATCH \
             -H "Content-Type: application/json" \
-            -H "Authorization: Bearer ${DO_API_TOKEN}" \
+            -H "Authorization: Bearer ${DIGITALOCEAN_ACCESS_TOKEN}" \
             -d "$(jq -n \
               --arg reason "Nightly rebuild — $(date -u '+%Y-%m-%d')" \
               --argjson imageId "$IMG_ID" \
@@ -177,6 +177,6 @@ jobs:
                  exit 1 ;;
           esac
         env:
-          DO_API_TOKEN: ${{ secrets.DO_API_TOKEN }}
+          DIGITALOCEAN_ACCESS_TOKEN: ${{ secrets.DO_API_TOKEN }}
           AGENT_NAME: ${{ matrix.agent }}
           MARKETPLACE_APP_IDS: ${{ secrets.MARKETPLACE_APP_IDS }}

README.md

@@ -206,7 +206,7 @@ export OPENROUTER_API_KEY=sk-or-v1-xxxxx
 # Cloud-specific credentials (varies by provider)
 # Note: Sprite uses `sprite login` for authentication
 export HCLOUD_TOKEN=...           # For Hetzner
-export DO_API_TOKEN=...           # For DigitalOcean
+export DIGITALOCEAN_ACCESS_TOKEN=...  # For DigitalOcean
 
 # Run non-interactively
 spawn claude hetzner
@@ -258,7 +258,7 @@ If spawn fails to install, try these steps:
 2. **Set credentials via environment variables** before launching:
    ```powershell
    $env:OPENROUTER_API_KEY = "sk-or-v1-xxxxx"
-   $env:DO_API_TOKEN = "dop_v1_xxxxx"      # For DigitalOcean
+   $env:DIGITALOCEAN_ACCESS_TOKEN = "dop_v1_xxxxx"  # For DigitalOcean
    $env:HCLOUD_TOKEN = "xxxxx"              # For Hetzner
    spawn openclaw digitalocean
    ```

manifest.json

@@ -411,7 +411,7 @@
       "description": "Cloud servers (account + payment method required)",
       "url": "https://www.digitalocean.com/",
       "type": "api",
-      "auth": "DO_API_TOKEN",
+      "auth": "DIGITALOCEAN_ACCESS_TOKEN",
       "provision_method": "POST /v2/droplets with user_data",
       "exec_method": "ssh root@IP",
       "interactive_method": "ssh -t root@IP",

packages/cli/src/__tests__/commands-exported-utils.test.ts

@@ -47,8 +47,8 @@ describe("parseAuthEnvVars", () => {
     });
 
     it("should extract env var starting with letter followed by digits", () => {
-      expect(parseAuthEnvVars("DO_API_TOKEN")).toEqual([
-        "DO_API_TOKEN",
+      expect(parseAuthEnvVars("DIGITALOCEAN_ACCESS_TOKEN")).toEqual([
+        "DIGITALOCEAN_ACCESS_TOKEN",
       ]);
     });
   });

packages/cli/src/__tests__/do-cov.test.ts

@@ -259,7 +259,7 @@ describe("digitalocean/getServerIp", () => {
     );
     const { getServerIp } = await import("../digitalocean/digitalocean");
     // Need to set the token state
-    process.env.DO_API_TOKEN = "test-token";
+    process.env.DIGITALOCEAN_ACCESS_TOKEN = "test-token";
     // getServerIp calls doApi which uses internal state token - need to set via ensureDoToken
     // But doApi will use _state.token. Since we can't easily set _state, we test the 404 path
     // by mocking fetch to always return 404

packages/cli/src/__tests__/do-payment-warning.test.ts

@@ -25,9 +25,15 @@ describe("ensureDoToken — payment method warning for first-time users", () =>
   let warnSpy: ReturnType<typeof spyOn>;
 
   beforeEach(() => {
-    // Save and clear DO_API_TOKEN
-    savedEnv["DO_API_TOKEN"] = process.env.DO_API_TOKEN;
-    delete process.env.DO_API_TOKEN;
+    // Save and clear all accepted DigitalOcean token env vars
+    for (const v of [
+      "DIGITALOCEAN_ACCESS_TOKEN",
+      "DIGITALOCEAN_API_TOKEN",
+      "DO_API_TOKEN",
+    ]) {
+      savedEnv[v] = process.env[v];
+      delete process.env[v];
+    }
 
     // Fail OAuth connectivity check → tryDoOAuth returns null immediately
     globalThis.fetch = mock(() => Promise.reject(new Error("Network unreachable")));
@@ -73,7 +79,25 @@ describe("ensureDoToken — payment method warning for first-time users", () =>
     expect(warnMessages.some((msg: string) => msg.includes("payment method"))).toBe(false);
   });
 
-  it("does NOT show payment warning when DO_API_TOKEN env var is set", async () => {
+  it("does NOT show payment warning when DIGITALOCEAN_ACCESS_TOKEN env var is set", async () => {
+    process.env.DIGITALOCEAN_ACCESS_TOKEN = "dop_v1_invalid_env_token";
+
+    await expect(ensureDoToken()).rejects.toThrow();
+
+    const warnMessages = warnSpy.mock.calls.map((c: unknown[]) => String(c[0]));
+    expect(warnMessages.some((msg: string) => msg.includes("payment method"))).toBe(false);
+  });
+
+  it("does NOT show payment warning when DIGITALOCEAN_API_TOKEN env var is set", async () => {
+    process.env.DIGITALOCEAN_API_TOKEN = "dop_v1_invalid_env_token";
+
+    await expect(ensureDoToken()).rejects.toThrow();
+
+    const warnMessages = warnSpy.mock.calls.map((c: unknown[]) => String(c[0]));
+    expect(warnMessages.some((msg: string) => msg.includes("payment method"))).toBe(false);
+  });
+
+  it("does NOT show payment warning when legacy DO_API_TOKEN env var is set", async () => {
     process.env.DO_API_TOKEN = "dop_v1_invalid_env_token";
 
     await expect(ensureDoToken()).rejects.toThrow();

packages/cli/src/__tests__/run-path-credential-display.test.ts

@@ -68,7 +68,7 @@ function makeManifest(overrides?: Partial<Manifest>): Manifest {
         price: "test",
         url: "https://digitalocean.com",
         type: "api",
-        auth: "DO_API_TOKEN",
+        auth: "DIGITALOCEAN_ACCESS_TOKEN",
         provision_method: "api",
         exec_method: "ssh root@IP",
         interactive_method: "ssh -t root@IP",
@@ -138,6 +138,8 @@ describe("prioritizeCloudsByCredentials", () => {
     // Save and clear credential env vars
     for (const v of [
       "HCLOUD_TOKEN",
+      "DIGITALOCEAN_ACCESS_TOKEN",
+      "DIGITALOCEAN_API_TOKEN",
       "DO_API_TOKEN",
       "UPCLOUD_USERNAME",
       "UPCLOUD_PASSWORD",
@@ -191,7 +193,7 @@ describe("prioritizeCloudsByCredentials", () => {
 
   it("should move multiple credential clouds to front", () => {
     process.env.HCLOUD_TOKEN = "test-token";
-    process.env.DO_API_TOKEN = "test-do-token";
+    process.env.DIGITALOCEAN_ACCESS_TOKEN = "test-do-token";
     const manifest = makeManifest();
     const clouds = [
       "upcloud",
@@ -290,7 +292,7 @@ describe("prioritizeCloudsByCredentials", () => {
 
   it("should preserve relative order within each group", () => {
     process.env.HCLOUD_TOKEN = "token";
-    process.env.DO_API_TOKEN = "token";
+    process.env.DIGITALOCEAN_ACCESS_TOKEN = "token";
     const manifest = makeManifest();
     // Input order: digitalocean before hetzner (both have creds)
     const clouds = [
@@ -331,7 +333,7 @@ describe("prioritizeCloudsByCredentials", () => {
 
   it("should count all credential clouds correctly with all set", () => {
     process.env.HCLOUD_TOKEN = "t1";
-    process.env.DO_API_TOKEN = "t2";
+    process.env.DIGITALOCEAN_ACCESS_TOKEN = "t2";
     process.env.UPCLOUD_USERNAME = "u";
     process.env.UPCLOUD_PASSWORD = "p";
     const manifest = makeManifest();
@@ -350,4 +352,30 @@ describe("prioritizeCloudsByCredentials", () => {
     expect(result.sortedClouds.slice(3)).toContain("sprite");
     expect(result.sortedClouds.slice(3)).toContain("localcloud");
   });
+
+  it("should recognize legacy DO_API_TOKEN as alias for DIGITALOCEAN_ACCESS_TOKEN", () => {
+    process.env.DO_API_TOKEN = "legacy-token";
+    const manifest = makeManifest();
+    const clouds = [
+      "digitalocean",
+      "hetzner",
+    ];
+    const result = prioritizeCloudsByCredentials(clouds, manifest);
+
+    expect(result.credCount).toBe(1);
+    expect(result.sortedClouds[0]).toBe("digitalocean");
+  });
+
+  it("should recognize DIGITALOCEAN_API_TOKEN as alias for DIGITALOCEAN_ACCESS_TOKEN", () => {
+    process.env.DIGITALOCEAN_API_TOKEN = "alt-token";
+    const manifest = makeManifest();
+    const clouds = [
+      "digitalocean",
+      "hetzner",
+    ];
+    const result = prioritizeCloudsByCredentials(clouds, manifest);
+
+    expect(result.credCount).toBe(1);
+    expect(result.sortedClouds[0]).toBe("digitalocean");
+  });
 });

packages/cli/src/__tests__/script-failure-guidance.test.ts

@@ -209,28 +209,28 @@ describe("getScriptFailureGuidance", () => {
 
     it("should show specific env var name and setup hint for default case when authHint is provided", () => {
       const savedOR = process.env.OPENROUTER_API_KEY;
-      const savedDO = process.env.DO_API_TOKEN;
+      const savedDO = process.env.DIGITALOCEAN_ACCESS_TOKEN;
       delete process.env.OPENROUTER_API_KEY;
-      delete process.env.DO_API_TOKEN;
-      const lines = stripped_getScriptFailureGuidance(42, "digitalocean", "DO_API_TOKEN");
+      delete process.env.DIGITALOCEAN_ACCESS_TOKEN;
+      const lines = stripped_getScriptFailureGuidance(42, "digitalocean", "DIGITALOCEAN_ACCESS_TOKEN");
       const joined = lines.join("\n");
-      expect(joined).toContain("DO_API_TOKEN");
+      expect(joined).toContain("DIGITALOCEAN_ACCESS_TOKEN");
       expect(joined).toContain("OPENROUTER_API_KEY");
       expect(joined).toContain("spawn digitalocean");
       expect(joined).toContain("setup");
       if (savedOR !== undefined) {
         process.env.OPENROUTER_API_KEY = savedOR;
       }
       if (savedDO !== undefined) {
-        process.env.DO_API_TOKEN = savedDO;
+        process.env.DIGITALOCEAN_ACCESS_TOKEN = savedDO;
       }
     });
 
     it("should show generic setup hint for default case when no authHint", () => {
       const lines = stripped_getScriptFailureGuidance(42, "digitalocean");
       const joined = lines.join("\n");
       expect(joined).toContain("spawn digitalocean");
-      expect(joined).not.toContain("DO_API_TOKEN");
+      expect(joined).not.toContain("DIGITALOCEAN_ACCESS_TOKEN");
     });
 
     it("should handle multi-credential auth hint", () => {

packages/cli/src/commands/index.ts

@@ -58,6 +58,7 @@ export {
   getImplementedClouds,
   hasCloudCli,
   hasCloudCredentials,
+  isAuthEnvVarSet,
   isInteractiveTTY,
   levenshtein,
   loadManifestWithSpinner,