{"id":6140,"date":"2026-09-03T22:20:51","date_gmt":"2026-09-03T13:20:51","guid":{"rendered":"https:\/\/eternalsphere.net\/echoes\/?p=6140"},"modified":"2026-09-12T17:17:13","modified_gmt":"2026-09-12T08:17:13","slug":"f5b3wbx1yqnk651","status":"publish","type":"post","link":"https:\/\/blog.eternalsphere.net\/index.php\/2026\/09\/03\/f5b3wbx1yqnk651\/","title":{"rendered":"Upgrading OpenClaw Safely: Capability Consent, systemd User Services, Loopback Binding, and FRP Reverse Proxying"},"content":{"rendered":"\n
\n

Privacy note:<\/strong> All hostnames, usernames, IP addresses, ports, domain names, paths, plugin deployment details, and other potentially identifying information in this article have been replaced with fictional examples. Values such as Orion<\/code>, Proxy-A<\/code>, 192.168.50.25<\/code>, example.net<\/code>, and port 28473<\/code> do not correspond to any real environment.<\/p>\n<\/blockquote>\n\n\n\n

Introduction<\/h2>\n\n\n\n

An OpenClaw upgrade can look deceptively simple:<\/p>\n\n\n\n

openclaw update\n<\/code><\/pre>\n\n\n\n
In practice, however, a major or feature-heavy release may touch far more than the npm package itself. Depending on the installation, an upgrade can involve:<\/p>\n\n\n\n
    \n
  • package replacement;<\/li>\n\n\n\n
  • configuration migration;<\/li>\n\n\n\n
  • state database migration;<\/li>\n\n\n\n
  • plugin updates;<\/li>\n\n\n\n
  • plugin capability approval;<\/li>\n\n\n\n
  • systemd service management;<\/li>\n\n\n\n
  • Gateway restart and validation;<\/li>\n\n\n\n
  • security diagnostics;<\/li>\n\n\n\n
  • automation compatibility checks;<\/li>\n\n\n\n
  • network exposure warnings.<\/li>\n<\/ul>\n\n\n\n
    A real upgrade from an older stable release to a newer 2026.8.x release provides a useful example of how these pieces interact.<\/p>\n\n\n\n
    The deployment discussed here uses an ARM64 Ubuntu server running OpenClaw Gateway, with public access provided through FRP and a separate Nginx reverse proxy.<\/p>\n\n\n\n
    The final architecture is intentionally designed so that OpenClaw itself listens only on localhost.<\/p>\n\n\n\n
    Internet\n   \u2502\n   \u2502 HTTPS\n   \u25bc\nNginx reverse proxy\n   \u2502\n   \u25bc\nFRPS\n   \u2502\n   \u2502 FRP tunnel\n   \u25bc\nFRPC\n   \u2502\n   \u25bc\n127.0.0.1:28473\n   \u2502\n   \u25bc\nOpenClaw Gateway\n<\/code><\/pre>\n\n\n\n
    This setup becomes particularly relevant when interpreting OpenClaw Doctor warnings after the upgrade.<\/p>\n\n\n\n
    \n\n\n\n
    1. Checking the Update Before Installing It<\/h2>\n\n\n\n
    The existing installation was managed through npm rather than a Git checkout.<\/p>\n\n\n\n
    The update status can be checked with:<\/p>\n\n\n\n
    openclaw update status\n<\/code><\/pre>\n\n\n\n
    A typical result may resemble:<\/p>\n\n\n\n
    Install  npm\nChannel  stable\nUpdate   available \u00b7 npm \u00b7 npm update 2026.8.2\n<\/code><\/pre>\n\n\n\n
    The existing version in this example was an earlier 2026.7.x build, while the stable channel offered 2026.8.2.<\/p>\n\n\n\n
    For an npm-managed OpenClaw installation, the preferred upgrade command is:<\/p>\n\n\n\n
    openclaw update\n<\/code><\/pre>\n\n\n\n
    This is preferable to manually replacing the global npm package because the OpenClaw updater performs application-specific work around the package update.<\/p>\n\n\n\n
    Conceptually, the upgrade workflow is closer to:<\/p>\n\n\n\n
    Stop Gateway\n      \u2502\n      \u25bc\nUpdate package\n      \u2502\n      \u25bc\nMigrate configuration\n      \u2502\n      \u25bc\nMigrate state\n      \u2502\n      \u25bc\nUpdate plugins\n      \u2502\n      \u25bc\nRun Doctor checks\n      \u2502\n      \u25bc\nRestart Gateway\n      \u2502\n      \u25bc\nVerify Gateway health\n<\/code><\/pre>\n\n\n\n
    The updater therefore acts as an application migration mechanism, not merely a wrapper around npm.<\/p>\n\n\n\n
    \n\n\n\n
    2. Confirming That the Core Upgrade Succeeded<\/h2>\n\n\n\n
    A successful upgrade should explicitly report a successful result.<\/p>\n\n\n\n
    Typical output includes:<\/p>\n\n\n\n
    Updating OpenClaw...\n\nStopping managed gateway service before package update...\n\n\u2713 Updating via package manager\n\u2713 Running doctor checks\n\nUpdate Result: OK\nBefore: 2026.7.x\nAfter:  2026.8.2\n<\/code><\/pre>\n\n\n\n
    At the end of the process, the updater should also restore the Gateway:<\/p>\n\n\n\n
    Restarting service...\nGateway: restarted and verified.\nDaemon restart completed.\n<\/code><\/pre>\n\n\n\n
    These lines are much more important than incidental Doctor warnings.<\/p>\n\n\n\n
    They establish that:<\/p>\n\n\n\n
      \n
    1. the target package was installed;<\/li>\n\n\n\n
    2. the application migration phase completed;<\/li>\n\n\n\n
    3. the managed Gateway restarted;<\/li>\n\n\n\n
    4. OpenClaw verified that the Gateway came back online.<\/li>\n<\/ol>\n\n\n\n
      An upgrade can therefore be successful even if Doctor subsequently reports configuration recommendations.<\/p>\n\n\n\n
      \n\n\n\n
      3. The Unexpected Part: Plugin Capability Consent<\/h2>\n\n\n\n
      The most interesting issue during this upgrade involved plugins.<\/p>\n\n\n\n
      Some plugins produced prompts similar to:<\/p>\n\n\n\n
      Plugin capabilities require approval\n<\/code><\/pre>\n\n\n\n
      OpenClaw then displayed information such as:<\/p>\n\n\n\n
      Tools:\n  tool_a\n  tool_b\n\nContracts:\n  tools\n  webSearchProviders\n  migrationProviders\n\nPrompt injection: allowed\nConversation access: denied\n<\/code><\/pre>\n\n\n\n
      followed by:<\/p>\n\n\n\n
      Accept these capabilities and update \"plugin-name\"? [y\/N]\n<\/code><\/pre>\n\n\n\n
      This is the Capability Consent<\/strong> system.<\/p>\n\n\n\n
      It is important to understand what this means, because it can initially look as though OpenClaw has unexpectedly disabled an existing plugin.<\/p>\n\n\n\n
      \n\n\n\n
      4. What Capability Consent Actually Means<\/h2>\n\n\n\n
      Capability Consent is an OpenClaw-level plugin security mechanism.<\/p>\n\n\n\n
      It is not the same thing as Linux permissions such as:<\/p>\n\n\n\n
      chmod\nsudo\nsudoers\nsetcap\nPOSIX capabilities\n<\/code><\/pre>\n\n\n\n
      Instead, it concerns what an OpenClaw plugin declares that it can provide or interact with.<\/p>\n\n\n\n
      Depending on the plugin, capabilities may include:<\/p>\n\n\n\n
        \n
      • registering tools;<\/li>\n\n\n\n
      • providing model backends;<\/li>\n\n\n\n
      • implementing web search;<\/li>\n\n\n\n
      • integrating with messaging systems;<\/li>\n\n\n\n
      • participating in migration workflows;<\/li>\n\n\n\n
      • handling media;<\/li>\n\n\n\n
      • exposing plugin-specific commands.<\/li>\n<\/ul>\n\n\n\n
        Conceptually:<\/p>\n\n\n\n
        Plugin package\n     \u2502\n     \u25bc\nPlugin manifest\n     \u2502\n     \u25bc\nDeclared capability surface\n     \u2502\n     \u25bc\nAdministrator approval\n     \u2502\n     \u25bc\nConsent record\n     \u2502\n     \u25bc\nPlugin can operate with those capabilities\n<\/code><\/pre>\n\n\n\n
        The important distinction is that plugin activation and capability approval are separate concepts<\/strong>.<\/p>\n\n\n\n
        \n\n\n\n
        5. Why an Existing Enabled Plugin May Suddenly Require Consent<\/h2>\n\n\n\n
        Suppose a plugin was already enabled in the older release.<\/p>\n\n\n\n
        Its historical state might have looked roughly like this:<\/p>\n\n\n\n
        plugin.enabled = true\n<\/code><\/pre>\n\n\n\n
        but the older OpenClaw version may not have stored the newer form of capability-consent metadata.<\/p>\n\n\n\n
        After upgrading, the state can effectively become:<\/p>\n\n\n\n
        plugin.enabled = true\ncapability consent = missing or outdated\n<\/code><\/pre>\n\n\n\n
        Doctor may then report:<\/p>\n\n\n\n
        WARN plugin-name:\nPlugin requires capability consent\n<\/code><\/pre>\n\n\n\n
        This does not automatically mean the plugin had previously been disabled<\/strong>.<\/p>\n\n\n\n
        It can simply mean that the plugin is configured and installed, but the newer OpenClaw release expects an explicit approval record that the older installation did not contain.<\/p>\n\n\n\n
        This distinction is important:<\/p>\n\n\n\n
        Enabled state\n     \u2260\nCapability approval state\n<\/code><\/pre>\n\n\n\n
        \n\n\n\n
        6. Why the Repair Command Still Says plugins enable<\/code><\/h2>\n\n\n\n
        Doctor may recommend:<\/p>\n\n\n\n
        openclaw plugins enable model-provider-plugin --accept-capabilities\n<\/code><\/pre>\n\n\n\n
        or:<\/p>\n\n\n\n
        openclaw plugins enable messaging-plugin --accept-capabilities\n<\/code><\/pre>\n\n\n\n
        The command name can be misleading when the plugin was already enabled.<\/p>\n\n\n\n
        For an existing plugin, the effective operation may be:<\/p>\n\n\n\n
        Keep plugin enabled\n        +\nRecord capability consent\n<\/code><\/pre>\n\n\n\n
        rather than:<\/p>\n\n\n\n
        Disabled\n   \u2193\nEnabled\n<\/code><\/pre>\n\n\n\n
        The CLI may still print:<\/p>\n\n\n\n
        Enabled plugin \"plugin-name\".\nRestart the gateway to apply.\n<\/code><\/pre>\n\n\n\n
        That output reflects the command being executed; it does not prove the plugin was disabled before the command ran.<\/p>\n\n\n\n
        \n\n\n\n
        7. Why Capability Consent Should Not Be Blindly Permanent<\/h2>\n\n\n\n
        This mechanism exists for a good security reason.<\/p>\n\n\n\n
        Consider a plugin that originally requested:<\/p>\n\n\n\n
        Capability A\nCapability B\n<\/code><\/pre>\n\n\n\n
        An administrator approves those capabilities.<\/p>\n\n\n\n
        A later version could request:<\/p>\n\n\n\n
        Capability A\nCapability B\nCapability C\nCapability D\n<\/code><\/pre>\n\n\n\n
        If OpenClaw treated historical trust in the plugin name as permanent approval for every future version, the plugin could silently expand its access after an update.<\/p>\n\n\n\n
        A safer model is:<\/p>\n\n\n\n
        Previously approved capabilities\n            \u2502\n            \u25bc\n        Plugin update\n            \u2502\n            \u25bc\nCompare declared capabilities\n            \u2502\n        \u250c\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2510\n        \u2502        \u2502\n   unchanged   expanded\n        \u2502        \u2502\n        \u25bc        \u25bc\n reuse old    request\n consent      approval\n<\/code><\/pre>\n\n\n\n
        Capability Consent therefore represents approval of the plugin’s current declared capability surface<\/strong>, not unconditional trust in all future versions.<\/p>\n\n\n\n
        This is also why capability prompts during an upgrade should be read rather than accepted mechanically.<\/p>\n\n\n\n
        \n\n\n\n
        8. Restarting the Gateway After Plugin Approval<\/h2>\n\n\n\n
        After accepting capabilities, OpenClaw may say:<\/p>\n\n\n\n
        Enabled plugin \"model-provider-plugin\".\nRestart the gateway to apply.\n<\/code><\/pre>\n\n\n\n
        The approval has been stored, but the running Gateway process still has the previous plugin state loaded.<\/p>\n\n\n\n
        The expected sequence is:<\/p>\n\n\n\n
        Write plugin consent\n       \u2502\n       \u25bc\nRestart Gateway\n       \u2502\n       \u25bc\nReload OpenClaw configuration\n       \u2502\n       \u25bc\nReload plugin registry\n       \u2502\n       \u25bc\nPlugin becomes active under approved capabilities\n<\/code><\/pre>\n\n\n\n
        At this stage, a common systemd-related mistake can occur.<\/p>\n\n\n\n
        \n\n\n\n
        9. systemctl<\/code> Reports That the Gateway Service Does Not Exist<\/h2>\n\n\n\n
        A natural command is:<\/p>\n\n\n\n
        systemctl restart openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
        but the result may be:<\/p>\n\n\n\n
        Failed to restart openclaw-gateway.service:\nUnit openclaw-gateway.service not found.\n<\/code><\/pre>\n\n\n\n
        The immediate assumption might be that the upgrade deleted the service.<\/p>\n\n\n\n
        That assumption can be wrong.<\/p>\n\n\n\n
        The real issue may be that OpenClaw Gateway is installed as a systemd user service<\/strong>, not a system-wide service.<\/p>\n\n\n\n
        \n\n\n\n
        10. systemd System Services and User Services Are Different<\/h2>\n\n\n\n
        A standard system service is commonly managed with:<\/p>\n\n\n\n
        systemctl status service-name\n<\/code><\/pre>\n\n\n\n
        and is often defined under locations such as:<\/p>\n\n\n\n
        \/etc\/systemd\/system\/\n<\/code><\/pre>\n\n\n\n
        A user service is commonly defined under:<\/p>\n\n\n\n
        ~\/.config\/systemd\/user\/\n<\/code><\/pre>\n\n\n\n
        and managed with:<\/p>\n\n\n\n
        systemctl --user status service-name\n<\/code><\/pre>\n\n\n\n
        For this OpenClaw installation, the correct commands are:<\/p>\n\n\n\n
        systemctl --user restart openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
        and:<\/p>\n\n\n\n
        systemctl --user status openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
        A healthy status should contain something similar to:<\/p>\n\n\n\n
        Loaded: loaded\nActive: active (running)\n<\/code><\/pre>\n\n\n\n
        This explains why plain systemctl<\/code> can report that the service does not exist while OpenClaw itself successfully stops and restarts the Gateway during an upgrade.<\/p>\n\n\n\n
        The commands are querying different systemd namespaces.<\/p>\n\n\n\n
        systemctl\n    \u2502\n    \u2514\u2500\u2500 system services\n\nsystemctl --user\n    \u2502\n    \u2514\u2500\u2500 per-user services\n<\/code><\/pre>\n\n\n\n
        \n\n\n\n
        11. Do Not Create a Second Gateway Service<\/h2>\n\n\n\n
        One particularly dangerous response to:<\/p>\n\n\n\n
        Unit openclaw-gateway.service not found\n<\/code><\/pre>\n\n\n\n
        would be to manually create a new system-wide unit under:<\/p>\n\n\n\n
        \/etc\/systemd\/system\/openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
        without first checking whether a user service already exists.<\/p>\n\n\n\n
        That could result in:<\/p>\n\n\n\n
        system-level Gateway\n        +\nuser-level Gateway\n<\/code><\/pre>\n\n\n\n
        Both processes might attempt to use the same listening port.<\/p>\n\n\n\n
        Possible results include:<\/p>\n\n\n\n
        Address already in use\n<\/code><\/pre>\n\n\n\n
        or a much more confusing situation where:<\/p>\n\n\n\n
        systemctl restart openclaw-gateway\n<\/code><\/pre>\n\n\n\n
        controls one process while:<\/p>\n\n\n\n
        systemctl --user restart openclaw-gateway\n<\/code><\/pre>\n\n\n\n
        controls another.<\/p>\n\n\n\n
        The safer diagnostic order is:<\/p>\n\n\n\n
        systemctl --user status openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
        before creating any replacement service.<\/p>\n\n\n\n
        \n\n\n\n
        12. Re-running Doctor After the Restart<\/h2>\n\n\n\n
        Once capability consent has been accepted and the correct Gateway service has restarted, Doctor should be run again:<\/p>\n\n\n\n
        openclaw doctor\n<\/code><\/pre>\n\n\n\n
        This second run is important because several migrations may only complete during or after a successful Gateway startup.<\/p>\n\n\n\n
        In this case, warnings related to plugin capability approval disappeared after restart.<\/p>\n\n\n\n
        Some legacy state warnings also disappeared automatically.<\/p>\n\n\n\n
        That is exactly the behavior expected from a migration-aware upgrade process.<\/p>\n\n\n\n
        \n\n\n\n
        13. Legacy State Migration Should Be Allowed to Finish Automatically<\/h2>\n\n\n\n
        During the first Doctor run after a major upgrade, messages such as these may appear:<\/p>\n\n\n\n
        Auto-migrated legacy state\n<\/code><\/pre>\n\n\n\n
        or:<\/p>\n\n\n\n
        Legacy device pairing store has not been imported yet\n<\/code><\/pre>\n\n\n\n
        The temptation may be to manually move, delete, or rewrite the old files.<\/p>\n\n\n\n
        That should generally be avoided initially.<\/p>\n\n\n\n
        If OpenClaw explicitly says the Gateway will import the state at startup, the preferred process is:<\/p>\n\n\n\n
        Leave legacy state untouched\n         \u2502\n         \u25bc\nRestart Gateway normally\n         \u2502\n         \u25bc\nAllow migration code to run\n         \u2502\n         \u25bc\nRun Doctor again\n<\/code><\/pre>\n\n\n\n
        If the warning disappears, the migration succeeded.<\/p>\n\n\n\n
        A useful rule is:<\/p>\n\n\n\n
        \n
        When an application provides an official state-migration path, allow that mechanism to run before manually editing legacy state.<\/p>\n<\/blockquote>\n\n\n\n
        Manual SQLite modification, file deletion, or forced cleanup should be a later troubleshooting step, not the first response.<\/p>\n\n\n\n
        \n\n\n\n
        14. The Loopback Warning<\/h2>\n\n\n\n
        After the upgrade, Doctor may still report:<\/p>\n\n\n\n
        Gateway is only bound to loopback.\n<\/code><\/pre>\n\n\n\n
        and recommend something such as:<\/p>\n\n\n\n
        Set gateway.bind=lan\n<\/code><\/pre>\n\n\n\n
        In isolation, that warning can suggest that external access will not work.<\/p>\n\n\n\n
        However, the deployment architecture matters.<\/p>\n\n\n\n
        OpenClaw in this example is intentionally listening only on:<\/p>\n\n\n\n
        127.0.0.1:28473\n<\/code><\/pre>\n\n\n\n
        Yet the public HTTPS domain remains fully accessible.<\/p>\n\n\n\n
        There is no contradiction because FRPC runs locally on the same machine.<\/p>\n\n\n\n
        \n\n\n\n
        15. How a Loopback-Only Gateway Can Still Be Publicly Accessible<\/h2>\n\n\n\n
        A process listening on:<\/p>\n\n\n\n
        127.0.0.1:28473\n<\/code><\/pre>\n\n\n\n
        cannot normally be reached directly from another LAN machine using:<\/p>\n\n\n\n
        192.168.50.25:28473\n<\/code><\/pre>\n\n\n\n
        But a local FRPC process can connect to:<\/p>\n\n\n\n
        127.0.0.1:28473\n<\/code><\/pre>\n\n\n\n
        because FRPC is running on the same host.<\/p>\n\n\n\n
        FRPC then carries that connection through its outbound FRP tunnel.<\/p>\n\n\n\n
        The effective request path is:<\/p>\n\n\n\n
        Internet\n   \u2502\n   \u2502 HTTPS\n   \u25bc\nNginx\n   \u2502\n   \u25bc\nFRPS\n   \u2502\n   \u2502 FRP tunnel\n   \u25bc\nFRPC\n   \u2502\n   \u2502 localhost connection\n   \u25bc\nOpenClaw Gateway\n127.0.0.1:28473\n<\/code><\/pre>\n\n\n\n
        The remote reverse-proxy machine therefore does not directly connect to the private server’s LAN address.<\/p>\n\n\n\n
        Instead, traffic reaches OpenClaw through the tunnel established by FRPC.<\/p>\n\n\n\n
        \n\n\n\n
        16. Why Loopback Binding Can Be Preferable<\/h2>\n\n\n\n
        In this architecture, changing OpenClaw from:<\/p>\n\n\n\n
        127.0.0.1\n<\/code><\/pre>\n\n\n\n
        to:<\/p>\n\n\n\n
        0.0.0.0\n<\/code><\/pre>\n\n\n\n
        merely to silence Doctor would provide little benefit and could increase exposure.<\/p>\n\n\n\n
        The existing arrangement limits direct access:<\/p>\n\n\n\n
        OpenClaw Gateway\n      \u2502\n      \u2502 localhost only\n      \u25bc\n     FRPC\n      \u2502\n      \u25bc\n  FRP tunnel\n      \u2502\n      \u25bc\n     FRPS\n      \u2502\n      \u25bc\n    Nginx\n      \u2502\n      \u25bc\n   Internet\n<\/code><\/pre>\n\n\n\n
        Other LAN hosts do not need direct access to the Gateway port.<\/p>\n\n\n\n
        This creates a useful isolation boundary.<\/p>\n\n\n\n
        The Doctor warning is therefore better interpreted as:<\/p>\n\n\n\n
        \n
        OpenClaw observes that the Gateway is not listening on a LAN-facing interface.<\/p>\n<\/blockquote>\n\n\n\n
        It does not<\/strong> necessarily mean:<\/p>\n\n\n\n
        \n
        External access is broken.<\/p>\n<\/blockquote>\n\n\n\n
        OpenClaw’s diagnostic tool cannot automatically know every external tunneling architecture surrounding the process.<\/p>\n\n\n\n
        \n\n\n\n
        17. The Role of FRP and Nginx<\/h2>\n\n\n\n
        FRP and Nginx perform different functions.<\/p>\n\n\n\n
        FRP<\/h3>\n\n\n\n
        FRP provides transport between an internal service and a remote reachable endpoint.<\/p>\n\n\n\n
        Private service\n     \u2502\n     \u25bc\nFRPC\n     \u2502\n     \u25bc\nFRP tunnel\n     \u2502\n     \u25bc\nFRPS\n<\/code><\/pre>\n\n\n\n
        Nginx<\/h3>\n\n\n\n
        Nginx handles the public HTTP layer:<\/p>\n\n\n\n
          \n
        • TLS termination;<\/li>\n\n\n\n
        • HTTPS;<\/li>\n\n\n\n
        • domain names;<\/li>\n\n\n\n
        • HTTP proxying;<\/li>\n\n\n\n
        • WebSocket forwarding;<\/li>\n\n\n\n
        • request headers;<\/li>\n\n\n\n
        • certificate management.<\/li>\n<\/ul>\n\n\n\n
          The complete architecture therefore becomes:<\/p>\n\n\n\n
          Browser\n   \u2502\n   \u2502 HTTPS\n   \u25bc\nNginx\n   \u2502\n   \u2502 HTTP \/ WebSocket\n   \u25bc\nFRPS\n   \u2502\n   \u2502 FRP\n   \u25bc\nFRPC\n   \u2502\n   \u2502 localhost\n   \u25bc\nOpenClaw Gateway\n<\/code><\/pre>\n\n\n\n
          This separates responsibilities cleanly:<\/p>\n\n\n\n
            \n
          • OpenClaw runs the application;<\/li>\n\n\n\n
          • FRP provides transport;<\/li>\n\n\n\n
          • Nginx provides the public HTTPS endpoint.<\/li>\n<\/ul>\n\n\n\n
            \n\n\n\n
            18. Not Every Doctor Warning Is a Fault<\/h2>\n\n\n\n
            One of the most important lessons from this upgrade is that Doctor should not be treated as a list in which every warning must be eliminated.<\/p>\n\n\n\n
            OpenClaw Doctor acts more like a combination of:<\/p>\n\n\n\n
            Health checker\nConfiguration auditor\nMigration advisor\nSecurity advisor\nPerformance advisor\n<\/code><\/pre>\n\n\n\n
            Some findings are real errors.<\/p>\n\n\n\n
            Others merely describe the current architecture.<\/p>\n\n\n\n
            \n\n\n\n
            19. Startup Optimization Recommendations<\/h2>\n\n\n\n
            On a small ARM server, Doctor may report:<\/p>\n\n\n\n
            NODE_COMPILE_CACHE is not set\n<\/code><\/pre>\n\n\n\n
            or:<\/p>\n\n\n\n
            OPENCLAW_NO_RESPAWN is not set to 1\n<\/code><\/pre>\n\n\n\n
            These are performance recommendations.<\/p>\n\n\n\n
            They may be useful on:<\/p>\n\n\n\n
              \n
            • Raspberry Pi-class devices;<\/li>\n\n\n\n
            • ARM SBCs;<\/li>\n\n\n\n
            • small VMs;<\/li>\n\n\n\n
            • systems with relatively slow storage.<\/li>\n<\/ul>\n\n\n\n
              However, they are not indications that the OpenClaw upgrade failed.<\/p>\n\n\n\n
              If the Gateway remains responsive and the machine has healthy CPU, memory, storage, and thermal conditions, these settings can be reviewed separately rather than changed during the upgrade itself.<\/p>\n\n\n\n
              \n\n\n\n
              20. State Stored on SD or eMMC<\/h2>\n\n\n\n
              Doctor may also detect that OpenClaw state resides on SD or eMMC storage.<\/p>\n\n\n\n
              OpenClaw state may contain:<\/p>\n\n\n\n
              SQLite databases\nSession data\nAgent state\nPlugin state\nAutomation state\nLogs\n<\/code><\/pre>\n\n\n\n
              These workloads may involve frequent small writes and random I\/O.<\/p>\n\n\n\n
              For long-term deployments, storage such as:<\/p>\n\n\n\n
              SSD\nNVMe\nUSB SSD\n<\/code><\/pre>\n\n\n\n
              may provide better performance and durability.<\/p>\n\n\n\n
              Still, this is a storage recommendation rather than an update failure.<\/p>\n\n\n\n
              The distinction matters:<\/p>\n\n\n\n
              Durability recommendation\n          \u2260\nApplication malfunction\n<\/code><\/pre>\n\n\n\n
              \n\n\n\n
              21. OpenClaw Backup Warnings<\/h2>\n\n\n\n
              Doctor may report:<\/p>\n\n\n\n
              No successful backup is recorded.\n<\/code><\/pre>\n\n\n\n
              This specifically refers to OpenClaw’s own backup subsystem.<\/p>\n\n\n\n
              It should not automatically be interpreted as:<\/p>\n\n\n\n
              \n
              This server has no backup.<\/p>\n<\/blockquote>\n\n\n\n
              The system may already be protected through:<\/p>\n\n\n\n
                \n
              • full disk images;<\/li>\n\n\n\n
              • filesystem snapshots;<\/li>\n\n\n\n
              • ZFS or Btrfs snapshots;<\/li>\n\n\n\n
              • rsync;<\/li>\n\n\n\n
              • external backup software;<\/li>\n\n\n\n
              • VM or hypervisor backups.<\/li>\n<\/ul>\n\n\n\n
                Application-level backup status and infrastructure-level backup status are separate concepts.<\/p>\n\n\n\n
                \n\n\n\n
                22. Command Owner Configuration<\/h2>\n\n\n\n
                Another possible Doctor message is:<\/p>\n\n\n\n
                No command owner is configured.\n<\/code><\/pre>\n\n\n\n
                A command owner is the account allowed to perform privileged OpenClaw actions through supported messaging channels.<\/p>\n\n\n\n
                Examples may include:<\/p>\n\n\n\n
                \/diagnostics\n\/export-session\n\/export-trajectory\n\/config\nexec approvals\n<\/code><\/pre>\n\n\n\n
                This does not mean ordinary conversations are broken.<\/p>\n\n\n\n
                It means OpenClaw has not been explicitly told which external messaging identity should be considered the privileged operator.<\/p>\n\n\n\n
                If administrative commands are not being issued through chat integrations, this warning may not require immediate action.<\/p>\n\n\n\n
                \n\n\n\n
                23. Messaging Pairing Is Separate From Plugin Capability Consent<\/h2>\n\n\n\n
                A messaging integration may separately report:<\/p>\n\n\n\n
                DM policy = pairing\nNo admitted senders\n<\/code><\/pre>\n\n\n\n
                This is unrelated to plugin Capability Consent.<\/p>\n\n\n\n
                The two security relationships are different.<\/p>\n\n\n\n
                Plugin Capability Consent:<\/p>\n\n\n\n
                Administrator\n      \u2502\n      \u25bc\nPlugin capabilities\n<\/code><\/pre>\n\n\n\n
                Messaging pairing:<\/p>\n\n\n\n
                External sender\n      \u2502\n      \u25bc\nBot access\n<\/code><\/pre>\n\n\n\n
                The first controls what the plugin may do inside OpenClaw.<\/p>\n\n\n\n
                The second controls which users may communicate with the messaging integration.<\/p>\n\n\n\n
                Confusing these two layers can lead to unnecessary configuration changes.<\/p>\n\n\n\n
                \n\n\n\n
                24. Browser Relay Legacy Authentication<\/h2>\n\n\n\n
                Doctor may also report that legacy Browser Relay authentication remains enabled.<\/p>\n\n\n\n
                A configuration may contain something conceptually similar to:<\/p>\n\n\n\n
                allowLegacyAuth=true\n<\/code><\/pre>\n\n\n\n
                while the newer release recommends Authentication v2.<\/p>\n\n\n\n
                The safe migration order is:<\/p>\n\n\n\n
                Upgrade browser extension \/ CDP clients\n              \u2502\n              \u25bc\nConfirm Authentication v2 support\n              \u2502\n              \u25bc\nTest all existing clients\n              \u2502\n              \u25bc\nDisable legacy authentication\n<\/code><\/pre>\n\n\n\n
                Disabling compatibility mode before clients have migrated can break otherwise working integrations.<\/p>\n\n\n\n
                Again, the correct objective is not simply to remove the warning.<\/p>\n\n\n\n
                The objective is to migrate without causing a service interruption.<\/p>\n\n\n\n
                \n\n\n\n
                25. Legacy Automation Warnings<\/h2>\n\n\n\n
                Existing automation jobs may retain older authorization semantics after an upgrade.<\/p>\n\n\n\n
                Doctor may describe them as using:<\/p>\n\n\n\n
                legacy sender-policy resolution\n<\/code><\/pre>\n\n\n\n
                while also saying that they:<\/p>\n\n\n\n
                keep running as-is\n<\/code><\/pre>\n\n\n\n
                or that the finding is:<\/p>\n\n\n\n
                informational only\n<\/code><\/pre>\n\n\n\n
                This means the automation is not necessarily broken.<\/p>\n\n\n\n
                It simply has not yet been migrated to a newer authorization model.<\/p>\n\n\n\n
                A safer maintenance strategy is:<\/p>\n\n\n\n
                Upgrade OpenClaw\n      \u2502\n      \u25bc\nVerify Gateway stability\n      \u2502\n      \u25bc\nObserve existing automations\n      \u2502\n      \u25bc\nMigrate legacy automation policies separately\n<\/code><\/pre>\n\n\n\n
                Combining an application upgrade, plugin migration, security-policy redesign, automation rewrite, storage migration, and network redesign into one maintenance window makes troubleshooting unnecessarily difficult.<\/p>\n\n\n\n
                \n\n\n\n
                26. Final Upgrade Verification<\/h2>\n\n\n\n
                The upgrade should not be considered complete based solely on the absence of an error during openclaw update<\/code>.<\/p>\n\n\n\n
                A useful final verification sequence is:<\/p>\n\n\n\n
                openclaw --version\nopenclaw update status\nsystemctl --user is-active openclaw-gateway.service\nsystemctl --user is-enabled openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
                A healthy result should conceptually show:<\/p>\n\n\n\n
                OpenClaw 2026.8.2\n\nUpdate:\nnpm \u00b7 up to date \u00b7 npm latest 2026.8.2\n\nactive\n\nenabled\n<\/code><\/pre>\n\n\n\n
                Then run:<\/p>\n\n\n\n
                openclaw doctor\n<\/code><\/pre>\n\n\n\n
                The important question is not whether Doctor contains zero warnings.<\/p>\n\n\n\n
                The important questions are:<\/p>\n\n\n\n
                  \n
                • Did Doctor complete?<\/li>\n\n\n\n
                • Are there any fatal errors?<\/li>\n\n\n\n
                • Is Gateway running?<\/li>\n\n\n\n
                • Are required plugins loading?<\/li>\n\n\n\n
                • Did migration warnings disappear after restart?<\/li>\n\n\n\n
                • Is the public application still reachable?<\/li>\n\n\n\n
                • Are existing automations still operational?<\/li>\n<\/ul>\n\n\n\n
                  If those checks succeed, the upgrade can reasonably be considered complete.<\/p>\n\n\n\n
                  \n\n\n\n
                  27. A Recommended OpenClaw Upgrade Workflow<\/h2>\n\n\n\n
                  A disciplined upgrade process can be summarized as follows.<\/p>\n\n\n\n
                  Step 1: Record the current version<\/h3>\n\n\n\n
                  openclaw --version\n<\/code><\/pre>\n\n\n\n
                  Step 2: Check the stable channel<\/h3>\n\n\n\n
                  openclaw update status\n<\/code><\/pre>\n\n\n\n
                  Step 3: Perform the managed update<\/h3>\n\n\n\n
                  openclaw update\n<\/code><\/pre>\n\n\n\n
                  Step 4: Review plugin capability prompts<\/h3>\n\n\n\n
                  Before answering y<\/code>, examine:<\/p>\n\n\n\n
                  Tools\nContracts\nConversation access\nPrompt injection\nNew capabilities\n<\/code><\/pre>\n\n\n\n
                  Step 5: Run Doctor<\/h3>\n\n\n\n
                  openclaw doctor\n<\/code><\/pre>\n\n\n\n
                  Step 6: Resolve missing capability consent only where appropriate<\/h3>\n\n\n\n
                  For example:<\/p>\n\n\n\n
                  openclaw plugins enable example-plugin --accept-capabilities\n<\/code><\/pre>\n\n\n\n
                  Step 7: Restart the correct systemd service<\/h3>\n\n\n\n
                  For a user-level OpenClaw installation:<\/p>\n\n\n\n
                  systemctl --user restart openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
                  Step 8: Run Doctor again<\/h3>\n\n\n\n
                  openclaw doctor\n<\/code><\/pre>\n\n\n\n
                  This allows startup-time migrations to complete.<\/p>\n\n\n\n
                  Step 9: Perform final verification<\/h3>\n\n\n\n
                  openclaw --version\nopenclaw update status\nsystemctl --user is-active openclaw-gateway.service\nsystemctl --user is-enabled openclaw-gateway.service\n<\/code><\/pre>\n\n\n\n
                  \n\n\n\n
                  28. What Should Not Be Done Merely to Silence Doctor<\/h2>\n\n\n\n
                  Several changes should not be made solely because Doctor displays a warning.<\/p>\n\n\n\n
                  For example:<\/p>\n\n\n\n
                  Do not expose Gateway to the LAN without a reason<\/h3>\n\n\n\n
                  If the architecture intentionally uses:<\/p>\n\n\n\n
                  OpenClaw\n   \u2502\nlocalhost\n   \u2502\nFRPC\n   \u2502\nFRPS\n   \u2502\nNginx\n<\/code><\/pre>\n\n\n\n
                  then loopback binding may be preferable.<\/p>\n\n\n\n
                  Do not enable unused features<\/h3>\n\n\n\n
                  If Host Desktop is disabled because the server is headless, there is no reason to enable it merely to make diagnostics quieter.<\/p>\n\n\n\n
                  Do not enable Memory Search unless it is actually wanted<\/h3>\n\n\n\n
                  An explicit:<\/p>\n\n\n\n
                  enabled: false\n<\/code><\/pre>\n\n\n\n
                  is a configuration choice, not a malfunction.<\/p>\n\n\n\n
                  Do not create a system-level Gateway service before checking user services<\/h3>\n\n\n\n
                  A duplicate service can cause port conflicts and difficult-to-debug process management.<\/p>\n\n\n\n
                  Do not delete legacy state before allowing automatic migration<\/h3>\n\n\n\n
                  The first post-upgrade warning may disappear naturally after the next Gateway startup.<\/p>\n\n\n\n
                  Do not disable legacy authentication until every client supports the replacement<\/h3>\n\n\n\n
                  Compatibility warnings often describe a migration path, not an emergency.<\/p>\n\n\n\n
                  \n\n\n\n
                  29. Key Lessons<\/h2>\n\n\n\n
                  This upgrade provides several reusable operational lessons.<\/p>\n\n\n\n
                  Plugin activation and plugin consent are different<\/h3>\n\n\n\n
                  Enabled\n   \u2260\nApproved capability surface\n<\/code><\/pre>\n\n\n\n
                  plugins enable --accept-capabilities<\/code> does not prove a plugin was previously disabled<\/h3>\n\n\n\n
                  For an existing plugin it may simply:<\/p>\n\n\n\n
                  retain enabled state\n+\nrecord required consent\n<\/code><\/pre>\n\n\n\n
                  systemd scope matters<\/h3>\n\n\n\n
                  systemctl\n<\/code><\/pre>\n\n\n\n
                  and:<\/p>\n\n\n\n
                  systemctl --user\n<\/code><\/pre>\n\n\n\n
                  do not manage the same units.<\/p>\n\n\n\n
                  Loopback does not mean inaccessible from the Internet<\/h3>\n\n\n\n
                  Local tunnel clients such as FRPC can expose a loopback-bound application without requiring the application itself to listen on the LAN.<\/p>\n\n\n\n
                  Diagnostic warnings require architectural context<\/h3>\n\n\n\n
                  A diagnostic tool can observe application configuration, but it cannot always infer the complete external topology.<\/p>\n\n\n\n
                  Automatic migration should generally be given the first opportunity to work<\/h3>\n\n\n\n
                  Restart\n   \u2193\nDoctor\n   \u2193\nObserve\n<\/code><\/pre>\n\n\n\n
                  is often safer than:<\/p>\n\n\n\n
                  Delete\nMove\nRewrite database\n<\/code><\/pre>\n\n\n\n
                  Maintenance changes should be separated where practical<\/h3>\n\n\n\n
                  A successful platform upgrade should not automatically become a simultaneous network redesign, storage migration, permission redesign, and automation rewrite.<\/p>\n\n\n\n
                  \n\n\n\n
                  30. Final Architecture<\/h2>\n\n\n\n
                  After the upgrade, the deployment can remain structured like this:<\/p>\n\n\n\n
                                      Internet\n                       \u2502\n                       \u2502 HTTPS\n                       \u25bc\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n              \u2502     Nginx      \u2502\n              \u2502 Reverse Proxy  \u2502\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                      \u2502\n                      \u25bc\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n              \u2502      FRPS      \u2502\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                      \u2502\n                      \u2502 FRP Tunnel\n                      \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n              \u2502      FRPC      \u2502\n              \u2502 ARM Linux Host \u2502\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                      \u2502\n                      \u2502 localhost\n                      \u25bc\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n              \u2502    OpenClaw    \u2502\n              \u2502    Gateway     \u2502\n              \u2502 Loopback Only  \u2502\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n<\/code><\/pre>\n\n\n\n
                  The Gateway remains managed as a systemd user service.<\/p>\n\n\n\n
                  Public TLS termination remains on the reverse-proxy machine.<\/p>\n\n\n\n
                  OpenClaw itself remains isolated from direct LAN and Internet exposure.<\/p>\n\n\n\n
                  \n\n\n\n
                  Conclusion<\/h2>\n\n\n\n
                  An OpenClaw upgrade is not simply an npm package replacement.<\/p>\n\n\n\n
                  A modern upgrade can involve:<\/p>\n\n\n\n
                  Package update\n      \u2502\n      \u251c\u2500\u2500 Configuration migration\n      \u251c\u2500\u2500 State migration\n      \u251c\u2500\u2500 Plugin updates\n      \u251c\u2500\u2500 Capability Consent\n      \u251c\u2500\u2500 systemd service management\n      \u251c\u2500\u2500 Gateway restart\n      \u251c\u2500\u2500 Security checks\n      \u251c\u2500\u2500 Automation compatibility\n      \u2514\u2500\u2500 Network architecture diagnostics\n<\/code><\/pre>\n\n\n\n
                  The central maintenance principle is not to eliminate every warning.<\/p>\n\n\n\n
                  Each message must first be classified:<\/p>\n\n\n\n
                  Fatal error\nMigration notice\nSecurity policy\nCompatibility warning\nPerformance recommendation\nArchitecture difference\nInformational notice\n<\/code><\/pre>\n\n\n\n
                  A system may be completely healthy while Doctor still reports several recommendations.<\/p>\n\n\n\n
                  For a deployment built around Loopback + FRP + Nginx HTTPS<\/strong>, a loopback-only Gateway can be an intentional security property rather than a configuration defect.<\/p>\n\n\n\n
                  Similarly, an existing plugin requesting Capability Consent after an upgrade does not necessarily mean that the plugin was previously disabled. It may simply indicate that the newer OpenClaw release requires explicit approval metadata for a capability model that did not exist, or was not stored in the same form, under the older release.<\/p>\n\n\n\n
                  The safest overall strategy is therefore:<\/p>\n\n\n\n
                  \n
                  Let the updater perform the application migration, let Doctor identify the resulting state, and interpret each warning according to the actual deployment architecture before changing anything.<\/strong><\/p>\n<\/blockquote>\n","protected":false},"excerpt":{"rendered":"
                  Privacy note: All hostnames, usernames, IP addresses, ports, domain names, paths, plugin deployment details, and other potentially identifying information in this article have been replaced with fictional examples. Values such as Orion, Proxy-A, 192.168.50.25, example.net, and port 28473 do not correspond to any real environment. Introduction An OpenClaw upgrade can …<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[88],"tags":[337,267,335],"class_list":["post-6140","post","type-post","status-publish","format-standard","hentry","category-4brz75t44cdxjqe","tag-openclaw","tag-systemd","tag-tunneling"],"_links":{"self":[{"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/posts\/6140","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/comments?post=6140"}],"version-history":[{"count":1,"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/posts\/6140\/revisions"}],"predecessor-version":[{"id":6141,"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/posts\/6140\/revisions\/6141"}],"wp:attachment":[{"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/media?parent=6140"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/categories?post=6140"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.eternalsphere.net\/index.php\/wp-json\/wp\/v2\/tags?post=6140"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}