Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Feature]: add a machine-readable configure session protocol for installers / GUI setup flows [5 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#55557•Fetched 2026-04-08 01:38:03
View on GitHub
Comments
5
Participants
2
Timeline
9
Reactions
0
Author
cgf120cgf120
Participants
balthazar-botbalthazar-botcgf120cgf120
Timeline (top)
commented ×5mentioned ×2subscribed ×2

I’d like to propose a machine-readable configure session protocol for OpenClaw so installers and GUI setup flows can drive provider/channel configuration reliably.

The main motivation is not “another CLI.” It is:

  • helping users who are not comfortable with command-line setup
  • letting installers / GUI apps safely reuse OpenClaw’s existing setup capabilities
  • avoiding brittle approaches like parsing interactive CLI output or depending on internal runtime details

I understand this is not a small bug fix. It is more of a feature / architecture proposal, so I’m opening an issue first to validate the direction before opening a large PR.

Root Cause

I’d like to propose a machine-readable configure session protocol for OpenClaw so installers and GUI setup flows can drive provider/channel configuration reliably.

The main motivation is not “another CLI.” It is:

  • helping users who are not comfortable with command-line setup
  • letting installers / GUI apps safely reuse OpenClaw’s existing setup capabilities
  • avoiding brittle approaches like parsing interactive CLI output or depending on internal runtime details

I understand this is not a small bug fix. It is more of a feature / architecture proposal, so I’m opening an issue first to validate the direction before opening a large PR.

RAW_BUFFERClick to expand / collapse

[Feature]: add a machine-readable configure session protocol for installers / GUI setup flows

Summary

I’d like to propose a machine-readable configure session protocol for OpenClaw so installers and GUI setup flows can drive provider/channel configuration reliably.

The main motivation is not “another CLI.” It is:

  • helping users who are not comfortable with command-line setup
  • letting installers / GUI apps safely reuse OpenClaw’s existing setup capabilities
  • avoiding brittle approaches like parsing interactive CLI output or depending on internal runtime details

I understand this is not a small bug fix. It is more of a feature / architecture proposal, so I’m opening an issue first to validate the direction before opening a large PR.

Problem to solve

OpenClaw’s setup capabilities currently live mostly in interactive CLI flows. That works well for CLI users, but it is not a stable integration surface for installers or GUI apps.

Today, a graphical installer generally has only weak options:

  • parse interactive terminal output
  • import internal runtime / dist chunks
  • hardcode provider/channel-specific setup logic in the GUI

All of those are brittle across upgrades.

And many setup flows are more than “paste one API key”, for example:

  • auth method selection
  • OAuth / browser login
  • QR / device code
  • setup-token / manual token flows
  • multi-step channel setup
  • self-hosted provider flows such as vllm / sglang / ollama that ask multiple questions in sequence

For installers / GUIs, what is missing is a stable execution protocol, not just discovery.

Proposed solution

Add a machine-readable session command group, conceptually like:

  • openclaw configure session start --kind provider|channel --id <id>
  • openclaw configure session input --session-id <id> --stdin-json
  • openclaw configure session poll --session-id <id>
  • openclaw configure session cancel --session-id <id>

The important part is not stdout JSON.

Instead, each session would have a stable state file, for example:

  • ~/.openclaw/configure-sessions/<sessionId>/session.json

An installer / GUI would:

  1. start a session
  2. read the snapshot
  3. render the current step
  4. submit user input via --stdin-json
  5. poll when needed

The main use case is enabling installers / GUI apps to serve users who do not want to work directly with complex CLI setup flows.

Key principles

1. The GUI should not know provider- or channel-specific logic

It should only know:

  • current session state
  • current step
  • available actions

Changes in providers/channels should be reflected through the runtime session surface, not through GUI-specific hardcoded branches.

2. The session protocol should ideally reuse existing CLI flows

If a setup flow already exists in the CLI, the session protocol should ideally reuse that flow rather than introducing a second hand-maintained GUI schema.

For example:

  • vllm currently asks for base URL -> API key -> model
  • ollama currently asks for base URL -> reachability check -> mode selection ...

The session protocol should ideally expose those real steps instead of inventing a parallel static form that might drift from CLI behavior.

Relation to existing work

I see this as complementary to configure surface:

  • surface answers “what can be configured”
  • session answers “how to configure it”

So:

  • surface is discovery
  • session is execution

Related threads:

  • configure surface proposal: #55085
  • machine-readable CLI output being polluted by logs: #37323
  • Windows Quick Installer GUI proposal: #44038

Alternatives considered

1. Keep parsing interactive CLI output

Too brittle. Prompt wording, order, and logging can change.

2. Import internal runtime / dist chunks directly

Too fragile across upgrades and not a supported contract.

3. Hardcode provider/channel flows in the GUI

Providers/channels can be added or changed over time; the GUI should not own that logic.

Impact

  • Affected users: users who are not comfortable with CLI-based installation and setup
  • Affected systems: installers, GUI setup flows, desktop onboarding
  • Severity: medium to high
  • Frequency: every fresh install / setup flow
  • Consequences:
    • GUI apps must automate CLI setup through brittle means
    • setup flows can break across upgrades
    • provider/channel setup remains difficult to expose safely in a graphical flow

Evidence/examples

Relevant context:

  • #44038 shows there is already community demand for a GUI installer to lower the barrier for non-technical users
  • #37323 shows that even existing --json CLI paths can still be polluted by logs in some cases, which is a problem for machine consumers
  • #55085 addresses the discovery layer, but not the execution layer

Additional information

I am not trying to replace openclaw configure.

What I want to validate first is:

  1. Is the overall configure session direction acceptable?
  2. Is the CLI the right place for a setup protocol used by installers / GUIs?
  3. Is bridging existing interactive setup flows into typed session steps the right direction?
  4. If this is worth pursuing, would maintainers prefer:
    • further design discussion on this issue first
    • or a very small first-step PR?

extent analysis

Fix Plan

To implement the proposed configure session protocol, follow these steps:

  • Introduce a new command group openclaw configure session with subcommands:
    • start: starts a new configuration session
    • input: submits user input for the current session
    • poll: checks the status of the current session
    • cancel: cancels the current session
  • Create a stable state file for each session, e.g., ~/.openclaw/configure-sessions/<sessionId>/session.json
  • Update the existing CLI setup flows to reuse the new session protocol

Example code for the new command group:

import json
import os

class ConfigureSession:
    def __init__(self, session_id):
        self.session_id = session_id
        self.state_file = f"~/.openclaw/configure-sessions/{session_id}/session.json"

    def start(self, kind, id):
        # Initialize the session state
        session_state = {"kind": kind, "id": id, "steps": []}
        with open(self.state_file, "w") as f:
            json.dump(session_state, f)

    def input(self, stdin_json):
        # Update the session state with user input
        with open(self.state_file, "r") as f:
            session_state = json.load(f)
        session_state["steps"].append(stdin_json)
        with open(self.state_file, "w") as f:
            json.dump(session_state, f)

    def poll(self):
        # Check the status of the session
        with open(self.state_file, "r") as f:
            session_state = json.load(f)
        return session_state

    def cancel(self):
        # Cancel the session
        os.remove(self.state_file)

# Example usage:
session = ConfigureSession("example-session")
session.start("provider", "example-id")
session.input({"key": "value"})
print(session.poll())
session.cancel()

Verification

To verify the fix, test the new configure session protocol with different scenarios, such as:

  • Starting a new session and submitting user input
  • Polling the session status and verifying the correct output
  • Canceling a session and checking that the state file is removed

Extra Tips

  • Ensure that the session protocol is well-documented and follows the existing CLI conventions.
  • Consider adding error handling and logging mechanisms to the new command group.
  • Review the existing setup flows and update them to reuse the new session protocol, ensuring a smooth transition for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#runtime error#dependency conflict

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix [Feature]: add a machine-readable configure session protocol for installers / GUI setup flows [5 comments, 2 participants]