Gateway: add safer password-file input for gateway run by vincentkoc · Pull Request #39067 · openclaw/openclaw

vincentkoc · 2026-03-07T17:50:22Z

Summary

Problem: openclaw gateway run --password <secret> exposes the gateway password in local process listings.
Why it matters: operators already have safer env/config SecretRef paths, but the foreground gateway CLI still encouraged an inline secret path.
What changed: added openclaw gateway run --password-file, warn on inline --password, and updated gateway CLI docs/changelog to prefer env or file-backed password input.
What did NOT change (scope boundary): gateway auth semantics, token handling, and remote RPC client credential flows.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

openclaw gateway run now accepts --password-file <path>.
Inline --password still works, but now prints a warning that it can leak through process listings.
Gateway CLI docs now recommend OPENCLAW_GATEWAY_PASSWORD, --password-file, or SecretRef-backed config for password auth.

Security Impact (required)

New permissions/capabilities? (Yes/No): No
Secrets/tokens handling changed? (Yes/No): Yes
New/changed network calls? (Yes/No): No
Command/tool execution surface changed? (Yes/No): No
Data access scope changed? (Yes/No): No
If any Yes, explain risk + mitigation:
Password input for gateway run now has a file-backed path and inline password usage emits a warning. This reduces accidental secret exposure in local process listings without changing gateway auth policy.

Repro + Verification

Environment

OS: macOS
Runtime/container: local pnpm worktree
Model/provider: n/a
Integration/channel (if any): n/a
Relevant config (redacted): none required

Steps

Run openclaw gateway run --auth password --password-file /tmp/gateway-password.txt --allow-unconfigured.
Verify the gateway start path receives the file-backed password.
Run openclaw gateway run --auth password --password secret --allow-unconfigured and verify the warning is printed.

Expected

File-backed passwords are accepted without exposing the secret in argv.
Inline passwords still work but warn.

Actual

Matches expected in the new CLI regression tests.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

Verified scenarios: pnpm test src/cli/gateway-cli/run.option-collisions.test.ts
Edge cases checked: --password-file happy path, inline --password warning, --password + --password-file collision error
What you did not verify: full repo lint/test/build sweep; only the targeted gateway CLI regression test ran in this worktree

Compatibility / Migration

Backward compatible? (Yes/No): Yes
Config/env changes? (Yes/No): No
Migration needed? (Yes/No): No
If yes, exact upgrade steps:

Failure Recovery (if this breaks)

How to disable/revert this change quickly: stop using --password-file and fall back to OPENCLAW_GATEWAY_PASSWORD or prior inline --password behavior
Files/config to restore: src/cli/gateway-cli/run.ts
Known bad symptoms reviewers should watch for: gateway run rejecting valid password-file input or failing to warn on inline --password

Risks and Mitigations

Risk: The new option could conflict with parent/child commander option inheritance.
- Mitigation: added regression coverage in src/cli/gateway-cli/run.option-collisions.test.ts.

greptile-apps · 2026-03-07T17:54:43Z

Greptile Summary

This PR adds a --password-file <path> option to openclaw gateway run as a safer alternative to the existing inline --password flag, which exposes secrets in local process listings. Using --password still works but now emits a warning on stderr; supplying both flags simultaneously is rejected with a clear error. Documentation and the changelog are updated accordingly.

Changes:

src/cli/gateway-cli/run.ts: new resolveGatewayPasswordOption helper handles the mutual-exclusion check, delegates file reads to the existing readSecretFromFile utility, and fires the deprecation warning when --password is used directly.
src/cli/gateway-cli/run.option-collisions.test.ts: three new regression tests cover the file-backed happy path, the inline-password warning, and the collision error.
docs/cli/gateway.md / docs/cli/index.md: --password-file documented; inline-password risk noted; env/file-backed input recommended.
CHANGELOG.md: entry added.

Issues found:

The two new tests that create temp directories via fs.mkdtemp do not clean them up after the test, which can accumulate stale files over repeated CI runs.
The collision error goes through String(err) on an Error object, producing "Error: Use either..." with a redundant prefix that is inconsistent with other error strings emitted in the same function.

Confidence Score: 4/5

This PR is safe to merge; the security improvement is well-scoped, backwards-compatible, and covered by targeted regression tests.
The implementation is straightforward and correctly delegates file reading to an existing utility. All three key scenarios (file path, inline warning, collision) are regression-tested. The only gaps are non-critical: missing temp-file cleanup in tests and a minor inconsistency in how the collision error message is prefixed.
No files require special attention; src/cli/gateway-cli/run.ts is the primary changed file and its logic is correct.

_{Last reviewed commit: 6713793}

src/cli/gateway-cli/run.ts

src/cli/gateway-cli/run.option-collisions.test.ts

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

aisle-research-bot · 2026-03-08T01:59:16Z

🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

#	Severity	Title
1	🔵 Low	Secret file reader lacks permission/symlink/size safeguards for --password-file

1. 🔵 Secret file reader lacks permission/symlink/size safeguards for --password-file

Property	Value
Severity	Low
CWE	CWE-732
Location	`src/acp/secret-file.ts:4-21`

Description

The new --password-file option reads the gateway password via readSecretFromFile(), which performs an unrestricted synchronous file read without basic secret-file safety checks.

Impacts:

Weak file permission handling: the password file may be group/world-readable and the CLI will still accept it, increasing the risk that other local users can read the gateway password.
Symlink/hardlink ambiguity: the function does not check for symlinks or ensure it is reading a regular file, so the resolved path could point somewhere unexpected.
Potential memory DoS: fs.readFileSync() reads the entire file into memory with no size cap.

Vulnerable code:

raw = fs.readFileSync(resolvedPath, "utf8");
const secret = raw.trim();

While the CLI is local, this still matters in shared-host or managed-install scenarios where secret files may be provisioned with overly-permissive modes, or where the CLI could be executed with attacker-influenced paths.

Recommendation

Harden secret-file loading:

Reject non-regular files and symlinks.
Enforce safe permissions (POSIX): require 0600 (or at least no group/other bits), and optionally require the file be owned by the current user.
Enforce a small maximum size (e.g., 4–64 KiB) and read via a file descriptor to avoid TOCTOU between stat and read.
Avoid over-detailed error messages if you consider full paths sensitive (optional).

Example (POSIX-aware) approach:

import fs from "node:fs";

const MAX_SECRET_BYTES = 64 * 1024;

export function readSecretFromFile(filePath: string, label: string): string {
  const resolvedPath = resolveUserPath(filePath.trim());
  if (!resolvedPath) throw new Error(`${label} file path is empty.`);

  // Open first, then fstat to minimize TOCTOU.
  const fd = fs.openSync(resolvedPath, fs.constants.O_RDONLY);
  try {
    const st = fs.fstatSync(fd);
    if (!st.isFile()) throw new Error(`${label} file must be a regular file.`);
    if (st.size > MAX_SECRET_BYTES) throw new Error(`${label} file is too large.`);

    // POSIX permission/ownership checks (skip on platforms without getuid).
    if (typeof process.getuid === "function") {
      if ((st.mode & 0o077) !== 0) {
        throw new Error(`${label} file permissions are too permissive (require 0600).`);
      }
      if (st.uid !== process.getuid()) {
        throw new Error(`${label} file must be owned by the current user.`);
      }
    }

    const buf = Buffer.allocUnsafe(Math.min(st.size, MAX_SECRET_BYTES));
    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
    const raw = buf.subarray(0, bytesRead).toString("utf8").replace(/^\uFEFF/, "");
    const secret = raw.trim();
    if (!secret) throw new Error(`${label} file is empty.`);
    return secret;
  } finally {
    fs.closeSync(fd);
  }
}

Analyzed PR: #39067 at commit a516ca5

_{Last updated on: 2026-03-08T02:25:21Z}

Latest run failed. Keeping previous successful results. Trace ID: 019ccb3ba321ef2c3bdd00d68204d5ee.

_{Last updated on: 2026-03-08T02:25:37Z}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d56b80ca79

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/cli/gateway-cli/run.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 899cddc356

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-08T02:23:21Z

src/acp/secret-file.ts

+  if (stat.isSymbolicLink()) {
+    throw new Error(`${label} file at ${resolvedPath} must not be a symlink.`);


Allow symlink-backed secret files

Hard-failing on stat.isSymbolicLink() breaks file-based auth in environments where mounted secrets are intentionally symlinked (for example, Kubernetes projected secrets where each key path points into ..data). Because readSecretFromFile is shared by gateway run and ACP secret-file flags, those flows now exit even though the secret payload is otherwise readable; this is a behavior regression from the previous implementation that accepted the path and read it.

Useful? React with 👍 / 👎.

* CLI: add gateway password-file option * Docs: document safer gateway password input * Update src/cli/gateway-cli/run.ts Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Tests: clean up gateway password temp dirs * CLI: restore gateway password warning flow * Security: harden secret file reads --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

* CLI: add gateway password-file option * Docs: document safer gateway password input * Update src/cli/gateway-cli/run.ts Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Tests: clean up gateway password temp dirs * CLI: restore gateway password warning flow * Security: harden secret file reads --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> (cherry picked from commit 4062aa5)

vincentkoc added 2 commits March 7, 2026 09:49

CLI: add gateway password-file option

0549498

Docs: document safer gateway password input

6713793

vincentkoc self-assigned this Mar 7, 2026

openclaw-barnacle bot added docs Improvements or additions to documentation cli CLI command changes size: S maintainer Maintainer-authored PR labels Mar 7, 2026

vincentkoc marked this pull request as ready for review March 7, 2026 17:52

greptile-apps bot reviewed Mar 7, 2026

View reviewed changes

src/cli/gateway-cli/run.ts Show resolved Hide resolved

src/cli/gateway-cli/run.option-collisions.test.ts Show resolved Hide resolved

Update src/cli/gateway-cli/run.ts

6a6a1a8

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Tests: clean up gateway password temp dirs

d56b80c

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/cli/gateway-cli/run.ts Show resolved Hide resolved

src/cli/gateway-cli/run.ts Show resolved Hide resolved

vincentkoc added 2 commits March 7, 2026 18:05

CLI: restore gateway password warning flow

a516ca5

Security: harden secret file reads

899cddc

vincentkoc merged commit 4062aa5 into openclaw:main Mar 8, 2026
29 of 35 checks passed

vincentkoc deleted the vincentkoc-code/gateway-password-file branch March 8, 2026 02:21

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

This was referenced Mar 8, 2026

🦞 OpenClaw 生态日报 2026-03-08 rollysys/agents-radar#53

Open

📡 Upstream Digest — 2026-03-08 04:04 UTC curtismercier/openclaw-mods#207

Open

github-actions bot mentioned this pull request Mar 8, 2026

上游更新: v2026.3.7 — 19 P0 + 122 P1 待合并 jiulingyun/openclaw-cn#486

Open

alexey-pelykh mentioned this pull request Mar 10, 2026

Cherry-pick: upstream CLI commands updates (18 commits) remoteclaw/remoteclaw#887

Closed

4 tasks

alexey-pelykh mentioned this pull request Mar 22, 2026

Cherry-pick issue #887: upstream CLI commands updates remoteclaw/remoteclaw#1791

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Gateway: add safer password-file input for gateway run#39067

Gateway: add safer password-file input for gateway run#39067
vincentkoc merged 6 commits intoopenclaw:mainfrom
vincentkoc:vincentkoc-code/gateway-password-file

vincentkoc commented Mar 7, 2026

Uh oh!

greptile-apps bot commented Mar 7, 2026

Uh oh!

Uh oh!

Uh oh!

aisle-research-bot bot commented Mar 8, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		if (stat.isSymbolicLink()) {
		throw new Error(`${label} file at ${resolvedPath} must not be a symlink.`);

Uh oh!

Conversation

vincentkoc commented Mar 7, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

greptile-apps bot commented Mar 7, 2026

Greptile Summary

Confidence Score: 4/5

Uh oh!

Uh oh!

Uh oh!

aisle-research-bot bot commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔒 Aisle Security Analysis

1. 🔵 Secret file reader lacks permission/symlink/size safeguards for --password-file

Description

Recommendation

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aisle-research-bot bot commented Mar 8, 2026 •

edited

Loading