diff --git a/src/config/io.eacces.test.ts b/src/config/io.eacces.test.ts
new file mode 100644
index 00000000000..f22b9d8905d
--- /dev/null
+++ b/src/config/io.eacces.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { createConfigIO } from "./io.js";
+
+function makeEaccesFs(configPath: string) {
+  const eaccesErr = Object.assign(new Error(`EACCES: permission denied, open '${configPath}'`), {
+    code: "EACCES",
+  });
+  return {
+    existsSync: (p: string) => p === configPath,
+    readFileSync: (p: string): string => {
+      if (p === configPath) {
+        throw eaccesErr;
+      }
+      throw new Error(`unexpected readFileSync: ${p}`);
+    },
+    promises: {
+      readFile: () => Promise.reject(eaccesErr),
+      mkdir: () => Promise.resolve(),
+      writeFile: () => Promise.resolve(),
+      appendFile: () => Promise.resolve(),
+    },
+  } as unknown as typeof import("node:fs").default;
+}
+
+describe("config io EACCES handling", () => {
+  it("returns a helpful error message when config file is not readable (EACCES)", async () => {
+    const configPath = "/data/.openclaw/openclaw.json";
+    const errors: string[] = [];
+    const io = createConfigIO({
+      configPath,
+      fs: makeEaccesFs(configPath),
+      logger: {
+        error: (msg: unknown) => errors.push(String(msg)),
+        warn: () => {},
+      },
+    });
+
+    const snapshot = await io.readConfigFileSnapshot();
+    expect(snapshot.valid).toBe(false);
+    expect(snapshot.issues).toHaveLength(1);
+    expect(snapshot.issues[0].message).toContain("EACCES");
+    expect(snapshot.issues[0].message).toContain("chown");
+    expect(snapshot.issues[0].message).toContain(configPath);
+    // Should also emit to the logger
+    expect(errors.some((e) => e.includes("chown"))).toBe(true);
+  });
+
+  it("includes configPath in the chown hint for the correct remediation command", async () => {
+    const configPath = "/home/myuser/.openclaw/openclaw.json";
+    const io = createConfigIO({
+      configPath,
+      fs: makeEaccesFs(configPath),
+      logger: { error: () => {}, warn: () => {} },
+    });
+
+    const snapshot = await io.readConfigFileSnapshot();
+    expect(snapshot.issues[0].message).toContain(configPath);
+    expect(snapshot.issues[0].message).toContain("container");
+  });
+});
diff --git a/src/config/io.ts b/src/config/io.ts
index bff292048fb..8dbcf10936c 100644
--- a/src/config/io.ts
+++ b/src/config/io.ts
@@ -936,6 +936,25 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) {
         envSnapshotForRestore: readResolution.envSnapshotForRestore,
       };
     } catch (err) {
+      const nodeErr = err as NodeJS.ErrnoException;
+      let message: string;
+      if (nodeErr?.code === "EACCES") {
+        // Permission denied — common in Docker/container deployments where the
+        // config file is owned by root but the gateway runs as a non-root user.
+        const uid = process.getuid?.();
+        const uidHint = typeof uid === "number" ? String(uid) : "$(id -u)";
+        message = [
+          `read failed: ${String(err)}`,
+          ``,
+          `Config file is not readable by the current process. If running in a container`,
+          `or 1-click deployment, fix ownership with:`,
+          `  chown ${uidHint} "${configPath}"`,
+          `Then restart the gateway.`,
+        ].join("\n");
+        deps.logger.error(message);
+      } else {
+        message = `read failed: ${String(err)}`;
+      }
       return {
         snapshot: {
           path: configPath,
@@ -946,7 +965,7 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) {
           valid: false,
           config: {},
           hash: hashConfigRaw(null),
-          issues: [{ path: "", message: `read failed: ${String(err)}` }],
+          issues: [{ path: "", message }],
           warnings: [],
           legacyIssues: [],
         },