Summary

Describe the problem and fix in 2–5 bullets:

• Problem: When gateway fails to start in Docker containers, the error handler calls maybeExplainGatewayServiceStop() which attempts to run systemctl --user status. In containers where systemctl doesn't exist, this throws an unhandled error: spawn systemctl ENOENT.
• Why it matters: The Docker container crashes on startup in containerized environments (Kubernetes, Docker, Zeabur), preventing the application from running.
• What changed: Added isSystemctlPresent() function to check if systemctl binary exists before executing it. Modified isSystemdServiceEnabled(), assertSystemdAvailable(), readSystemdServiceRuntime(), installSystemdService(), and uninstallSystemdService() to handle missing systemctl gracefully.
• What did NOT change (scope boundary): Did not add container environment detection - simple binary check is sufficient. Did not modify service resolution logic in service.ts.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 [Bug]: [Bug]: systemctl --user unavailable in Docker container deployment #26089
• Related #

User-visible / Behavior Changes

• Gateway no longer crashes when systemd is unavailable (e.g., in containers)
• Clear error messages when attempting service operations in containers: "systemctl not found; cannot install systemd service. This operation is not supported in containerized environments."

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)

Repro + Verification

Environment

• OS: Linux (containerized)
• Runtime/container: Docker/Kubernetes
• Relevant config: gateway.mode=local, --allow-unconfigured

Steps

1. Deploy OpenClaw Docker image to Kubernetes/Docker
2. Set environment: OPENCLAW_GATEWAY_PORT=18789, OPENCLAW_GATEWAY_BIND=0.0.0.0, NODE_ENV=production
3. Start the container

Expected

Container starts successfully, application listens on port 18789

Actual (before fix)

Container crashes with error: systemctl --user unavailable: spawn systemctl ENOENT

Evidence

Attach at least one:

• Failing test/log before + passing after

Before fix: The existing tests would fail in CI environments where systemctl is not available, or the code would throw unhandled errors in containers.
After fix: All tests pass:
✓ src/daemon/systemd.test.ts (17 tests)

• returns true when systemctl --user succeeds
• returns false when systemd user bus is unavailable
• isSystemdServiceEnabled returns false when systemctl is not present ✓
• isSystemdServiceEnabled calls systemctl is-enabled when systemctl is present ✓
• stops the resolved user unit ✓
• restarts a profile-specific user unit ✓
• surfaces stop failures with systemctl detail ✓
  Test Files: 1 passed (1)
  Tests: 17 passed (17)

• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: Unit tests pass for systemd functions with mocked systemctl missing
• Edge cases checked: install/uninstall when systemctl is present vs absent
• What you did NOT verify: Actual Docker container deployment

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert commit ceb08fd
• Files/config to restore: src/daemon/systemd.ts, src/daemon/systemd.test.ts

Risks and Mitigations

• Risk: None identified - the change is defensive and only adds error handling where none existed
• Mitigation: Tests verify behavior with and without systemctl present

PR generated with OpenCode and MiniMax M2.5

Build plan prompt-

Implementation Plan: Fix systemctl unavailable in Docker container deployment

Issue: #26089

• Problem: When gateway fails to start in Docker containers, the error handler calls maybeExplainGatewayServiceStop() which attempts to check systemd status via systemctl --user status. In Docker containers where systemctl doesn't exist, this throws an unhandled error.
• Error: systemctl --user unavailable: spawn systemctl ENOENT
• Root Cause:
  1. Gateway fails to start (port binding issue, etc.)
  2. Error handler calls maybeExplainGatewayServiceStop() in src/cli/gateway-cli/shared.ts
  3. This calls service.isLoaded() → isSystemdServiceEnabled() → assertSystemdAvailable()
  4. assertSystemdAvailable() tries systemctl --user status → ENOENT in containers where systemctl doesn't exist

NOTE: This plan file should NOT be included in git commits. It is needed later when creating the PR description.

Branch Name

fix/issue-26089-systemctl-unavailable-docker

Implementation Steps

Step 1: Create branch and establish baseline

• 1.1 Create new branch: git checkout -b fix/issue-26089-systemctl-unavailable-docker
• 1.2 Install dependencies: pnpm install
• 1.3 Run baseline tests:
  • pnpm build
  • pnpm check
  • pnpm test

Step 2: Add isSystemctlPresent() function

• 2.1 In src/daemon/systemd.ts, add new function:

  async function isSystemctlPresent(): Promise<boolean> {
    try {
      await execFileUtf8("command", ["-v", "systemctl"]);
      return true;
    } catch {
      return false;
    }
  }

• 2.2 Add unit tests for isSystemctlPresent() in src/daemon/systemd.test.ts

Step 3: Modify isSystemdServiceEnabled()

• 3.1 Update to check if systemctl exists first
• 3.2 Return false gracefully if systemctl is not available (instead of throwing)
• 3.3 Add/update tests for this behavior

Step 4: Modify assertSystemdAvailable()

• 4.1 Update to check if systemctl binary exists first
• 4.2 Provide clear error messages:
  • "systemctl binary not found" when systemctl doesn't exist
  • "systemd user bus unavailable" when systemd isn't running

Step 5: Modify readSystemdServiceRuntime()

• 5.1 Handle case where systemctl is not available
• 5.2 Return { status: 'unknown', detail: '...' } instead of throwing

Step 6: Modify install/uninstall functions

• 6.1 Update installSystemdService() to check systemctl availability first
• 6.2 Update uninstallSystemdService() to handle missing systemctl
• 6.3 Provide clear error messages for container environments

Step 7: Verify maybeExplainGatewayServiceStop() handles errors

• 7.1 In src/cli/gateway-cli/shared.ts, ensure error handling around isLoaded() call
• 7.2 Make it gracefully handle the case when systemctl is unavailable

Step 8: Run tests and verify

• 8.1 Run unit tests: pnpm test
• 8.2 Run type check: pnpm tsgo
• 8.3 Run lint/format: pnpm check

Step 9: Commit changes

• 9.1 Build: pnpm build
• 9.2 Test: pnpm test
• 9.3 Format: pnpm format
• 9.4 Commit: scripts/committer "Daemon: handle missing systemctl in containers" <files>

Step 10: Push and create PR

• 10.1 Push: git push -u fork fix/issue-26089-systemctl-unavailable-docker
• 10.2 Create PR with reference to [Bug]: [Bug]: systemctl --user unavailable in Docker container deployment #26089

CI/CD Tests to Run Locally

Before pushing:

1. pnpm build
2. pnpm tsgo
3. pnpm check
4. pnpm format
5. pnpm test
6. pnpm protocol:check

Key Files to Modify

1. src/daemon/systemd.ts - Add isSystemctlPresent() and graceful error handling
2. src/daemon/systemd.test.ts - Add tests for new behavior
3. src/cli/gateway-cli/shared.ts - Handle errors in maybeExplainGatewayServiceStop()

NOT Doing (Decision)

• Container environment detection (not needed - simple binary check is sufficient)
• Complex local container simulation for testing
• Service.ts modifications

Expected Outcome

• Gateway starts successfully in Docker containers
• If systemd functions are called, they handle missing systemctl gracefully
• Clear error messages guide users when they try to use service management in containers

Greptile Summary

Added isSystemctlPresent() function to check for systemctl binary availability before attempting systemd operations, preventing crashes in containerized environments where systemctl doesn't exist.

• Modified isSystemdServiceEnabled() to return false gracefully when systemctl is absent
• Updated readSystemdServiceRuntime() to return status unknown with descriptive detail when systemctl is missing
• Enhanced installSystemdService() and uninstallSystemdService() to check for systemctl presence first
• Modified assertSystemdAvailable() to provide clearer error messages distinguishing between missing binary and unavailable systemd user bus
• Added comprehensive test coverage for the new behavior

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is defensive, well-tested, and follows established patterns. The changes only add error handling where none existed before, preventing crashes without altering core logic. Tests verify both paths (systemctl present and absent), and the error handling properly propagates through the service abstraction layer.
• No files require special attention

_{Last reviewed commit: ceb08fd}