From de0e5af9422fb05faf083c7942a88d90227dd9ab Mon Sep 17 00:00:00 2001 From: GodsBoy Date: Tue, 17 Mar 2026 17:13:03 +0200 Subject: [PATCH] fix(install): auto-set NODE_EXTRA_CA_CERTS for nvm Node.js on Linux --- docs/help/environment.md | 19 ++++++++++ src/cli/daemon-cli/install.ts | 50 ++++++++++++++++++++++++ src/daemon/service-env.test.ts | 69 ++++++++++++++++++++++++++++++++++ src/daemon/service-env.ts | 31 ++++++++++++++- 4 files changed, 168 insertions(+), 1 deletion(-) diff --git a/docs/help/environment.md b/docs/help/environment.md index 45faad7c66c..bf531f23f67 100644 --- a/docs/help/environment.md +++ b/docs/help/environment.md @@ -133,6 +133,25 @@ When set, `OPENCLAW_HOME` replaces the system home directory (`$HOME` / `os.home `OPENCLAW_HOME` can also be set to a tilde path (e.g. `~/svc`), which gets expanded using `$HOME` before use. +## nvm users: web_fetch TLS failures + +If Node.js was installed via **nvm** (not the system package manager), the built-in `fetch()` uses +nvm's bundled CA store, which may be missing modern root CAs (ISRG Root X1/X2 for Let's Encrypt, +DigiCert Global Root G2, etc.). This causes `web_fetch` to fail with `"fetch failed"` on most HTTPS sites. + +Since `v2026.3.17`, `openclaw gateway install` on Linux automatically detects nvm and writes the +fix to both the systemd service environment and `~/.openclaw/.env`. + +**Manual fix (for older versions or manual gateway starts):** + +Add to `~/.openclaw/.env`: + +``` +NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt +``` + +Then restart the gateway. This appends the system CA bundle to Node's bundled store. + ## Related - [Gateway configuration](/gateway/configuration) diff --git a/src/cli/daemon-cli/install.ts b/src/cli/daemon-cli/install.ts index 023ea5e520e..7d7c06d01e3 100644 --- a/src/cli/daemon-cli/install.ts +++ b/src/cli/daemon-cli/install.ts @@ -1,3 +1,5 @@ +import fs from "node:fs"; +import path from "node:path"; import { buildGatewayInstallPlan } from "../../commands/daemon-install-helpers.js"; import { DEFAULT_GATEWAY_DAEMON_RUNTIME, @@ -5,6 +7,8 @@ import { } from "../../commands/daemon-runtime.js"; import { resolveGatewayInstallToken } from "../../commands/gateway-install-token.js"; import { readBestEffortConfig, resolveGatewayPort } from "../../config/config.js"; +import { resolveGatewayStateDir } from "../../daemon/paths.js"; +import { isNvmNode } from "../../daemon/service-env.js"; import { resolveGatewayService } from "../../daemon/service.js"; import { isNonFatalSystemdInstallProbeError } from "../../daemon/systemd.js"; import { defaultRuntime } from "../../runtime.js"; @@ -119,4 +123,50 @@ export async function runDaemonInstall(opts: DaemonInstallOptions) { }); }, }); + + // On Linux with nvm-installed Node, ensure NODE_EXTRA_CA_CERTS is in ~/.openclaw/.env + // so manual `openclaw gateway run` also picks up the system CA bundle via dotenv. + ensureNvmCaCertsInDotEnv({ env: process.env, json, warnings }); +} + +/** + * When Node.js is installed via nvm on Linux, write NODE_EXTRA_CA_CERTS to + * the global .env file so non-service runs (e.g. `openclaw gateway run`) + * also get the system CA bundle. The service environment already handles this + * via buildServiceEnvironment, but dotenv covers the manual-start path. + */ +function ensureNvmCaCertsInDotEnv(params: { + env: Record; + json: boolean; + warnings: string[]; +}): void { + if (process.platform !== "linux" || !isNvmNode(params.env, process.execPath)) { + return; + } + if (params.env.NODE_EXTRA_CA_CERTS) { + return; + } + + try { + const stateDir = resolveGatewayStateDir(params.env); + const envFile = path.join(stateDir, ".env"); + const existing = fs.existsSync(envFile) ? fs.readFileSync(envFile, "utf8") : ""; + if (existing.includes("NODE_EXTRA_CA_CERTS")) { + return; + } + const line = "NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n"; + const content = existing.endsWith("\n") || !existing ? existing + line : `${existing}\n${line}`; + fs.mkdirSync(stateDir, { recursive: true }); + fs.writeFileSync(envFile, content, "utf8"); + + const message = + "nvm detected: wrote NODE_EXTRA_CA_CERTS to ~/.openclaw/.env for TLS compatibility"; + if (params.json) { + params.warnings.push(message); + } else { + defaultRuntime.log(message); + } + } catch { + // Best-effort; the service environment already has the var via buildServiceEnvironment. + } } diff --git a/src/daemon/service-env.test.ts b/src/daemon/service-env.test.ts index f8297a28554..89753dd99eb 100644 --- a/src/daemon/service-env.test.ts +++ b/src/daemon/service-env.test.ts @@ -8,6 +8,7 @@ import { buildServiceEnvironment, getMinimalServicePathParts, getMinimalServicePathPartsFromEnv, + isNvmNode, } from "./service-env.js"; describe("getMinimalServicePathParts - Linux user directories", () => { @@ -500,6 +501,74 @@ describe("shared Node TLS env defaults", () => { }); }); +describe("isNvmNode", () => { + it("returns true when NVM_DIR env var is set", () => { + expect(isNvmNode({ NVM_DIR: "/home/user/.nvm" })).toBe(true); + }); + + it("returns true when execPath contains /.nvm/", () => { + expect(isNvmNode({}, "/home/user/.nvm/versions/node/v22.22.0/bin/node")).toBe(true); + }); + + it("returns false when neither NVM_DIR nor nvm execPath", () => { + expect(isNvmNode({}, "/usr/bin/node")).toBe(false); + }); + + it("returns false for empty env and system execPath", () => { + expect(isNvmNode({}, "/usr/local/bin/node")).toBe(false); + }); + + it("returns true when NVM_DIR is set even with system execPath", () => { + expect(isNvmNode({ NVM_DIR: "/home/user/.nvm" }, "/usr/bin/node")).toBe(true); + }); +}); + +describe("shared Node TLS env — Linux nvm detection", () => { + const builders = [ + { + name: "gateway service env", + build: (env: Record, platform?: NodeJS.Platform) => + buildServiceEnvironment({ env, port: 18789, platform }), + }, + { + name: "node service env", + build: (env: Record, platform?: NodeJS.Platform) => + buildNodeServiceEnvironment({ env, platform }), + }, + ] as const; + + it.each(builders)( + "$name defaults NODE_EXTRA_CA_CERTS on Linux when NVM_DIR is set", + ({ build }) => { + const env = build({ HOME: "/home/user", NVM_DIR: "/home/user/.nvm" }, "linux"); + expect(env.NODE_EXTRA_CA_CERTS).toBe("/etc/ssl/certs/ca-certificates.crt"); + }, + ); + + it.each(builders)( + "$name does not default NODE_EXTRA_CA_CERTS on Linux without nvm", + ({ build }) => { + const env = build({ HOME: "/home/user" }, "linux"); + expect(env.NODE_EXTRA_CA_CERTS).toBeUndefined(); + }, + ); + + it.each(builders)( + "$name respects user-provided NODE_EXTRA_CA_CERTS on Linux with nvm", + ({ build }) => { + const env = build( + { + HOME: "/home/user", + NVM_DIR: "/home/user/.nvm", + NODE_EXTRA_CA_CERTS: "/custom/ca-bundle.crt", + }, + "linux", + ); + expect(env.NODE_EXTRA_CA_CERTS).toBe("/custom/ca-bundle.crt"); + }, + ); +}); + describe("resolveGatewayStateDir", () => { it("uses the default state dir when no overrides are set", () => { const env = { HOME: "/Users/test" }; diff --git a/src/daemon/service-env.ts b/src/daemon/service-env.ts index cb26c210efb..0d3f189f351 100644 --- a/src/daemon/service-env.ts +++ b/src/daemon/service-env.ts @@ -15,6 +15,28 @@ import { resolveNodeWindowsTaskName, } from "./constants.js"; +/** Standard system CA bundle path on Debian/Ubuntu/Alpine Linux. */ +const LINUX_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt"; + +/** + * Detect if Node.js was installed via nvm. + * nvm-installed Node uses a bundled CA certificate store that may be missing modern + * root CAs (ISRG Root X1/X2, DigiCert Global Root G2, etc.), causing TLS failures + * with Node's built-in fetch (undici) for the majority of real-world HTTPS sites. + * + * Pass `execPath` explicitly to also check the binary path (e.g. `process.execPath`). + * Without it, only the `NVM_DIR` env var is checked. + */ +export function isNvmNode(env?: Record, execPath?: string): boolean { + if (env?.NVM_DIR) { + return true; + } + if (execPath !== undefined) { + return execPath.includes("/.nvm/"); + } + return false; +} + export type MinimalServicePathOptions = { platform?: NodeJS.Platform; extraDirs?: string[]; @@ -325,8 +347,15 @@ function resolveSharedServiceEnvironmentFields( // On macOS, launchd services don't inherit the shell environment, so Node's undici/fetch // cannot locate the system CA bundle. Default to /etc/ssl/cert.pem so TLS verification // works correctly when running as a LaunchAgent without extra user configuration. + // On Linux, nvm-installed Node uses a bundled CA store that is missing modern root CAs. + // Default to the system CA bundle when nvm is detected so TLS works out of the box. const nodeCaCerts = - env.NODE_EXTRA_CA_CERTS ?? (platform === "darwin" ? "/etc/ssl/cert.pem" : undefined); + env.NODE_EXTRA_CA_CERTS ?? + (platform === "darwin" + ? "/etc/ssl/cert.pem" + : platform === "linux" && isNvmNode(env) + ? LINUX_SYSTEM_CA_BUNDLE + : undefined); const nodeUseSystemCa = env.NODE_USE_SYSTEM_CA ?? (platform === "darwin" ? "1" : undefined); return { stateDir,