PR #78095: fix(doctor): surface GH_CONFIG_DIR hint when gh auth lives at a different HOME

• Repository: openclaw/openclaw
• Author: tmimmanuel
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78095

Description (problem / solution / changelog)

Summary

• Problem: When an OpenClaw agent shell runs with a different HOME than the user that ran gh auth login (per-agent codex homes, systemd User= services, sudo'd shells), gh looks up its config under $XDG_CONFIG_HOME/gh or $HOME/.config/gh and reports not logged into any GitHub hosts, even though the operator HOME has a valid hosts.yml. Issue #78063 reports the symptom: HOME=/root/.openclaw/agents/main/agent/codex-home/home gh auth status returns "not logged in" while gh is fully authenticated under /root/.config/gh.
• Why it matters: The user-facing symptom looks like the GitHub skill is broken; operators try GH_TOKEN / GITHUB_TOKEN rabbit holes when the real fix is to set GH_CONFIG_DIR=/root/.config/gh (or equivalent) on the gateway service environment.
• What changed: New pure helper detectGhConfigDirMismatch in src/agents/skills/gh-config-discovery.ts that takes process env + a fileExists probe and reports either auth-discoverable, no-known-auth, explicit-gh-config-dir-set, or mismatch with the alternate config dir, hosts file, and a suggested GH_CONFIG_DIR value. src/commands/doctor-skills.ts now calls the helper from the doctor skills health flow when the github skill is reported and the gh binary is present, printing a "GitHub CLI" note with the operator-actionable fix before any unavailable-skill repair prompt. skills/github/SKILL.md gains a troubleshooting subsection documenting GH_CONFIG_DIR for service/agent environments.
• What did NOT change (scope boundary): No core credential migration; OpenClaw does not copy or move gh auth between homes. No new config option added; we read existing process env. The requirement engine is unchanged. No changes to gh itself or its skill metadata other than docs.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #78063
• Related #65958 (GitHub skill needs OpenClaw restart after CLI install; restart guidance unclear)
• Related #75169 (docs(github): clarify restart after gh setup)
• Related #53628 (${XDG_CONFIG_HOME} not processed when installing a skill)
• Related #257 (per-session GitHub authentication setup guide)
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: gh resolves its config dir as $GH_CONFIG_DIR -> $XDG_CONFIG_HOME/gh -> $HOME/.config/gh (Linux/macOS) or $AppData/GitHub CLI (Windows). When OpenClaw spawns an agent shell with HOME redirected to a per-agent codex home, the gh lookup misses the operator's authenticated config. The previous doctor flow only checked whether the gh binary was on PATH and never inspected config-dir layout, so the GitHub skill looked ready while runtime calls failed.
• Missing detection / guardrail: No code path on main correlated the running process's effective gh config dir against well-known operator homes that might hold a hosts.yml.
• Contributing context (if known): Per-agent codex homes are a documented isolation feature (docs/plugins/codex-harness.md), and several adjacent issues (#65958, #75169, #53628) already point at gh-skill setup gaps. This PR closes the specific HOME-mismatch case without changing the isolation model.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/skills/gh-config-discovery.test.ts (new, 13 cases for the pure helper) and src/commands/doctor-skills.test.ts (4 new cases covering describeGhConfigDirHintFromDiscovery).
• Scenario the test should lock in: A reproduction of the issue's HOME=/root/.openclaw/agents/main/agent/codex-home/home setup yields a mismatch result whose suggestedEnvValue equals /root/.config/gh, and the formatted hint contains GH_CONFIG_DIR=/root/.config/gh. SUDO_USER and USER fallbacks resolve to the right candidate dirs. GH_CONFIG_DIR already set, missing gh binary, missing github skill, and aligned HOME all correctly suppress the hint. Linux, macOS, and Windows path layouts are exercised.
• Why this is the smallest reliable guardrail: The mismatch decision is a pure function of process env + filesystem state; covering it as a pure helper test keeps coverage deterministic without mocking the doctor flow. The doctor wiring tests cover the skill-presence and gh-binary preconditions.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

openclaw doctor now prints a "GitHub CLI" note when it detects an authenticated hosts.yml outside the agent process's effective gh config dir, including the suggested GH_CONFIG_DIR env value. No new config keys; no changes to existing skill behavior. The GitHub skill docs gain a troubleshooting subsection.

Diagram (if applicable)

Before:
  agent shell HOME=/root/.openclaw/agents/main/agent/codex-home/home
  gh -> $HOME/.config/gh -> not present -> "not logged in"
  doctor -> gh binary on PATH? yes -> github skill reported as ready

After:
  agent shell HOME=/root/.openclaw/agents/main/agent/codex-home/home
  gh -> same lookup, still misses
  doctor -> finds /root/.config/gh/hosts.yml at a candidate operator HOME
        -> prints "GitHub CLI" note:
             Process gh config dir: /root/.openclaw/agents/main/agent/codex-home/home/.config/gh
             Authenticated config:  /root/.config/gh (contains hosts.yml)
             Authenticated HOME:    /root
             Fix: set GH_CONFIG_DIR=/root/.config/gh on the OpenClaw service environment, then restart the gateway.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No (helper reads HOME/USER/SUDO_USER/APPDATA from process env and probes hosts.yml existence; never reads token contents)
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Ubuntu workstation, Linux 6.8.0-110-generic
• Runtime/container: Node 22.22.0 via nvm, pnpm 10.33.2
• Model/provider: N/A (skill diagnostic)
• Integration/channel (if any): GitHub skill (gh CLI)
• Relevant config (redacted): N/A

Steps

1. Check out the branch on top of upstream/main.
2. Run the bot-prescribed acceptance tests: pnpm test src/commands/doctor-skills.test.ts src/agents/skills-status.test.ts (plus the new src/agents/skills/gh-config-discovery.test.ts).
3. Run pnpm tsgo:core and pnpm tsgo:core:test.
4. Reproduce the issue scenario by invoking detectGhConfigDirMismatch directly via node (through tsx), passing the same HOME the issue reports and a synthetic fileExists that pretends /root/.config/gh/hosts.yml is present.

Expected

• All test files pass with the new cases.
• Both typecheck lanes exit 0.
• The helper returns kind: "mismatch" with alternateConfigDir = /root/.config/gh and suggestedEnvValue = /root/.config/gh.
• The formatted hint contains the operator-actionable GH_CONFIG_DIR=/root/.config/gh line.

Actual

• pnpm test for the three test files: 28 passed in 15.68s.
• pnpm tsgo:core exit 0; pnpm tsgo:core:test exit 0.
• Live node/tsx invocation against the helper produced the expected mismatch result and the operator hint (transcript below).

Real behavior proof

• Behavior or issue addressed: Issue #78063 - agent shells with HOME=/root/.openclaw/agents/main/agent/codex-home/home reported gh as unauthenticated even though /root/.config/gh/hosts.yml was a valid login. The doctor flow had no diagnostic for this HOME mismatch.

• Real environment tested: Ubuntu 24.04 workstation, Node 22.22.0, pnpm 10.33.2, branch fix/78063-gh-config-dir-mismatch at head dd5ed0fa64. Live invocation of the new helper via node (through tsx for ESM TypeScript path resolution).

• Exact steps or command run after this patch:

  1. Built a small node proof script that imports the new helper by absolute path and runs three scenarios: the exact HOME=/root/.openclaw/agents/main/agent/codex-home/home reproduction from the issue, the operator's already-applied GH_CONFIG_DIR=/root/.config/gh workaround, and an aligned HOME=/root baseline.
  2. Executed node_modules/.bin/tsx /tmp/proof-78063.mts and captured stdout.
  3. Confirmed the operator-actionable hint matches what openclaw doctor will print on the affected systems.

• Evidence after fix:

  Live console output captured at branch head dd5ed0fa64 (real node/tsx invocations against the new helper, not lint/test gates):

  $ git rev-parse HEAD
  dd5ed0fa64...
  
  $ node_modules/.bin/tsx /tmp/proof-78063.mts
  == Reproducing #78063 scenario: agent HOME differs from /root ==
  {
    "kind": "mismatch",
    "effectiveConfigDir": "/root/.openclaw/agents/main/agent/codex-home/home/.config/gh",
    "alternateConfigDir": "/root/.config/gh",
    "alternateHostsFile": "/root/.config/gh/hosts.yml",
    "alternateHomeHint": "/root",
    "suggestedEnvValue": "/root/.config/gh"
  }
  
  -- Operator hint that doctor will print --
  GitHub CLI auth was found at a different HOME than the one this OpenClaw process uses.
    Process gh config dir: /root/.openclaw/agents/main/agent/codex-home/home/.config/gh
    Authenticated config:  /root/.config/gh (contains hosts.yml)
    Authenticated HOME:    /root
    Fix: set GH_CONFIG_DIR=/root/.config/gh on the OpenClaw service environment, then restart the gateway.
  
  == Already-set GH_CONFIG_DIR (operator already applied workaround) ==
  {
    "kind": "explicit-gh-config-dir-set",
    "ghConfigDir": "/root/.config/gh"
  }
  
  == Auth resolves correctly (HOME and gh config aligned) ==
  {
    "kind": "auth-discoverable",
    "effectiveConfigDir": "/root/.config/gh"
  }

• Observed result after fix: With the agent HOME from the issue, detectGhConfigDirMismatch correctly identifies the /root/.config/gh candidate, reports it as a mismatch, and produces the exact operator hint a user would need to copy into the gateway service env file. With GH_CONFIG_DIR already set, the helper short-circuits to explicit-gh-config-dir-set (no false-positive hint). With aligned HOME, the helper reports auth-discoverable and no hint. The doctor flow only invokes the helper when the github skill is enabled and gh is on PATH.

• What was not tested: A live macOS reproduction with a real systemd analogue (the issue is reported on Ubuntu); a live Windows reproduction (the helper covers Windows APPDATA paths but the issue scenario is Linux-only); end-to-end interaction with gh itself (we read documented gh behavior, not the binary).

Evidence

• Failing test/log before + passing after - 17 new test cases lock in the helper and doctor wiring contracts.
• Trace/log snippets - included above (live tsx capture of the operator hint).
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • The exact HOME from the issue produces a mismatch result whose suggestedEnvValue matches the operator's documented workaround.
  • The hint string matches what an operator would paste into ~/.openclaw/gateway.systemd.env.
  • GH_CONFIG_DIR already set short-circuits the discovery (no duplicate hint).
  • gh binary missing suppresses the hint (the existing install hint covers it).
  • github skill missing suppresses the hint (no spurious noise on agents that disabled github).
• Edge cases checked:
  • SUDO_USER and USER fallbacks resolve to /home/<user> (or /Users/<user> on darwin).
  • XDG_CONFIG_HOME wins over $HOME/.config/gh on Linux.
  • Windows APPDATA and USERPROFILE lookups produce backslash-joined paths.
  • HOME equal to a candidate operator home does not produce a false mismatch.
• What you did not verify: A live gh auth login cycle on a macOS or Windows host; the actual systemd service env file reload behavior; tab-complete or shell-eval edge cases.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No (the helper reads existing env; nothing new is required)
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: A false positive could appear if a candidate operator home happens to contain a stale hosts.yml for an unrelated user, and the operator follows the suggested GH_CONFIG_DIR blindly.
  • Mitigation: The hint only suggests pointing GH_CONFIG_DIR at the discovered alternate; it does not modify env or copy credentials. The hint includes the candidate HOME so operators can sanity-check before applying it. The discovery is gated on the github skill being enabled and gh being on PATH.
• Risk: The /root candidate could be misleading on hosts where the gateway intentionally runs under an unprivileged user that has its own hosts.yml.
  • Mitigation: SUDO_USER and USER fallbacks add the actual login user's home to the candidate set. auth-discoverable short-circuits before any candidate scan when the agent's own HOME already has hosts.yml.

🤖 Generated with Claude Code

Changed files

• skills/github/SKILL.md (modified, +19/-0)
• src/agents/skills/gh-config-discovery.test.ts (added, +223/-0)
• src/agents/skills/gh-config-discovery.ts (added, +187/-0)
• src/commands/doctor-skills.test.ts (modified, +63/-0)
• src/commands/doctor-skills.ts (modified, +43/-0)