Inputs, Files, and WebUI

Yes: production user input has structured JSON, but it is not the WebUI output JSON.

These two contracts flow in opposite directions: the platform writes the current invocation to /oasn/in/invocation.json for the Program to read; the Program writes a strict oasn-webui JSON block in its final reply for the platform to parse into a business page. Do not combine them, and do not let the browser read the former.

Distinguish the two JSON documents first

DirectionCarrierWriter and readerPurpose
User → Program/oasn/in/invocation.jsonThe platform writes it; the Program reads it only on the serverObtain the current user text, arguments, and attachment paths.
Program → userThe oasn-webui fenced block in the final Assistant replyAgent main writes it; the platform parses itProject a running page as a WebUI view/canvas.

1. Read structured user input

The following example shows business fields that are safe to display. It illustrates the file structure; it is not a request body for users to write. The real file is generated by the platform and also contains platform fields for the runtime contract.

{
  "schema_version": "oasn.invocation.v1",
  "invocation_id": "inv-example",
  "run_id": "run-example",
  "input": {
    "user_prompt": "Read the attachment and generate an interactive sales dashboard",
    "args": [],
    "attachments": [
      "/oasn/in/files/file-sales-csv"
    ]
  }
}
FieldTypeHow the Program uses it
input.user_promptstringThe current user's text. If it is blank, ask for the missing information instead of inventing a task.
input.argsarrayThe current production projection is normally an empty array. Do not depend on it unless the business contract explicitly requires it.
input.attachmentsstring[]Read-only server paths for the current Run. Read only the listed entries.

Read the file only when the business logic truly needs the raw structure; ordinary OpenClaw Skills and Plugins normally receive the message directly. When parsing is required, keep the server-side read minimal:

from json import loads
from pathlib import Path

payload = loads(Path("/oasn/in/invocation.json").read_text(encoding="utf-8"))
business_input = payload.get("input", {})
user_prompt = business_input.get("user_prompt", "")
attachments = business_input.get("attachments", [])

if not isinstance(user_prompt, str) or not isinstance(attachments, list):
    raise ValueError("INVALID_INVOCATION_INPUT")

Do not output, log, or screenshot the complete invocation.json

In addition to the business fields, the real file may contain short-lived runtime material. Do not use cat to write the full file to logs, return it through a WebUI API, or scan /oasn/in, an attachment's parent directory, or historical directories. Do not expose attachment paths to the browser or turn them directly into attachments for another OpenAgent.

2. Query the confirmed business ports

Use the Skill-verified CLI 0.11.0 or later to read the current developer Sandbox ports and connections. Ports come from the confirmed configuration and the platform's platform configuration; the CLI does not replace, clear, or refresh that list. The website has no arbitrary-port editor.

openagent-dev --version
openagent-dev version webui-ports get --version-id <agent_version_id>
  • Use the returned ports for the business listeners. Do not infer ports from an old runtime or choose additional ports through a retired write command.
  • Check sandbox_id, sync_status, proxy_status, failure_code, and webui_urls. The port revision is not the website draft ETag.
  • Deliver current URLs only when both sync_status=ready and proxy_status=ready. CLI 0.11.0 validates each developer URL against /sandbox-proxy/{sandbox_id}/{port}/; use the complete returned URL instead of constructing one.
  • Missing or expired connections are registered or renewed through the platform's existing readback flow for the same confirmed configuration. This does not rerun configuration, restart the application, clear ports, or recreate the Sandbox.
  • Proxy readiness does not prove business health. Open the real page and API; for WebSocket applications, verify message round trips and reconnection.

How to interpret port status

StatusMeaningAction
pendingConfiguration or connection readiness is not yet confirmedQuery again within a bounded wait; do not submit old port writes.
readyConfiguration or proxy checks passedRequire both status fields to be ready, then test the actual HTTP service.
expiredA short-lived connection has expiredQuery the same confirmed configuration; the platform restores missing or expired connections. Do not clear ports.
revokedThe previous connection was revokedReport the state and use the current authorized lifecycle flow; do not revive it through a port write.
unavailableThe current connection cannot be verifiedReport the service or Version problem; do not claim readiness or rebuild by default.
not_configuredThe confirmed configuration has no business portsCheck the confirmed configuration and existing fixed-port rules; the CLI does not add arbitrary ports.
sync_status=failedConfiguration failed or an old write intent was retiredPreserve failure_code; do not label it ready or keep waiting as if it were pending.

DEVELOPER_WORKSPACE_WEBUI_WRITE_RETIRED identifies a retired port-write intent. A later valid configuration must complete before current connections can be reported as ready; the old failure remains available for diagnosis.

3. Implement a service that works under the proxy subpath

  1. Listen on all container interfaces

    The business process must listen on 0.0.0.0:<declared-port>, not only on localhost. The CLI reads the confirmed mapping; it does not start or stop the process or prove that it is healthy.
  2. Provide a business page and a minimal health endpoint

    At minimum, make the target page and business API return verifiable content. The Program determines how it starts the process; the current contract does not require a fixed start-webui.sh or a fixed health path.
  3. Preserve the proxy prefix

    The WebUI is mounted under a /webui/proxy/<id>/ subpath. fetch('/api/health') and src="/vendor/app.js" discard that prefix. The page, SPA routes, static assets, and WebSocket should all resolve their base from the current URL.
const prefix = window.location.pathname.match(/^.*\/webui\/proxy\/[^/]+\//)?.[0]
const base = prefix
  ? new URL(prefix, window.location.origin)
  : new URL('./', window.location.href)

fetch(new URL('api/health', base))
const scriptUrl = new URL('vendor/app.js', base)

Do not hard-code a Sandbox IP, 127.0.0.1, a development Workspace's public URL, or an external domain in page code. Note that the internal WebUI declaration in the next section must use a loopback URL; that does not conflict with the relative-address rule inside browser pages.

Website Version workspace without a WebUI-port form; business ports come from the confirmed configuration
Current website boundary. The Program area still provides model, Resource, and development entry controls. Business WebUI ports are not in the form; use the query on this page to inspect the confirmed ports.

4. The final reply must contain strict oasn-webui JSON

After the page is running and reachable, make the final Assistant reply from main include ordinary explanatory text and one lowercase fenced block per page:

The dashboard is ready. Open it to view the results.

```oasn-webui
{"type":"webui","title":"Sales dashboard","url":"http://127.0.0.1:7860/results?range=q3#summary","defaultOpen":true}
```
FieldStrict rule
typeMust be the string "webui".
titleMust be a non-empty string. Use a page name that users can understand.
urlFor a page in the same Sandbox, use http://127.0.0.1:<declared-port>/<business-path> or localhost. The field is named url, not uri.
defaultOpenMust be a real JSON boolean, true or false, not the string "true".
  • The JSON must be an object containing exactly these four fields. Do not add token, description, or custom fields.
  • The fence info must be exactly lowercase oasn-webui. Do not use an ordinary json block or append parameters to the fence info.
  • The port must be declared on the Version. Do not copy a public webui_urls value returned by the CLI into the block.
  • Internal HTTP allows only 127.0.0.1 or localhost. An external page must use safe public HTTPS; public HTTP and private-network addresses are not allowed.
  • The URL must not contain a username or password, and its query or fragment must not carry sensitive state such as token, secret, signature, credential, password, authorization, or api_key.
  • You may provide multiple blocks for multiple pages. The current parser preserves multiple defaultOpen=true values, but the interaction contract allows at most one page to be true so that clients do not open several pages in succession. This is a developer rule; do not mistake it for server-side rejection.

Three common mistakes

# Wrong: defaultOpen is a string
{"type":"webui","title":"Dashboard","url":"http://127.0.0.1:7860/","defaultOpen":"true"}

# Wrong: the URL is relative and there is an extra custom field
{"type":"webui","title":"Dashboard","url":"/results","defaultOpen":true,"token":"..."}

# Wrong: the platform output field uri is used as a developer input field
{"type":"webui","title":"Dashboard","uri":"https://example.invalid/","defaultOpen":true}

A block with invalid JSON syntax, missing fields, or incorrect types does not become a WebUI view and normally remains verbatim in the text. If the structure is valid but the URL uses an undeclared port, a private-network address, or sensitive state, production projection closes with OPENCLAW_FINAL_REPLY_INVALID. If later result-layer validation fails again, it returns RUN_RESULT_INVALID or MCP_INVOCATION_RESULT_INVALID; it does not hide the error behind partial success.

5. url becomes uri in platform output

The developer is responsible only for the final reply in the previous section and does not construct the following object directly. After the platform validates and proxies the page, the client reads trusted structuredContent.views[], where the field is named uri:

{
  "content": [
    {"type": "text", "text": "The dashboard is ready. Open it to view the results."}
  ],
  "structuredContent": {
    "view": "invocation_result",
    "status": "completed",
    "invocation_id": "inv-example",
    "views": [
      {
        "type": "webui",
        "uri": "https://platform-controlled-host/webui/proxy/.../results?range=q3#summary",
        "title": "Sales dashboard",
        "defaultOpen": true
      }
    ]
  },
  "isError": false
}

Integration clients should trust structuredContent.views[] instead of reparsing the fence in the text. A view with defaultOpen=false should remain a visible entry point; it simply does not open automatically. Failure to open a browser page also must not rewrite the Agent's completed terminal state or automatically invoke the Agent again.

6. Accept at four layers, not just by seeing HTTP 200

  1. Local Sandbox service

    Confirm that the process listens on 0.0.0.0, access the target page and API through loopback, and verify the business response content.
  2. Port and proxy status

    Run version webui-ports get and confirm ports, sync_status=ready, proxy_status=ready, and the current webui_urls together.
  3. Development proxy page

    Open every new URL and verify the page, nested routes, static assets, and API. If WebSocket is used, verify round trips and reconnection. If the developer URL is unavailable, query current connection status instead of inferring an OAuth failure from the HTTP code. For a 502, check the business listener first.
  4. Final result and production invocation

    Have the Agent return a real block, confirm that it is projected as a view/canvas, and verify that the path, query, and fragment are preserved without sensitive state. After publishing, run one more production invocation; development WebChat is not a substitute.

Reopening after completion: implemented in code, still awaiting formal product acceptance

The current implementation is designed to recover a production WebUI from the committed process snapshot for the same session. The number of ports does not determine recovery eligibility, and developers are not required to provide an additional fixed restart script. Do not promise that a page can always be reopened until real single-port and multi-port tasks have completed and their original result links have been reopened successfully in acceptance testing. A development Workspace link cannot substitute for this production acceptance.

Pre-publish I/O gates

  • A normal request returns non-empty, useful final text consistent with the input.
  • Structured input reads only input.user_prompt and the current input.attachments; it does not expose the complete file.
  • A file output can be downloaded and its contents verified; a local path alone is not sufficient.
  • The port declaration is frozen, both sync_status and proxy_status are ready, and every page has been tested for real.
  • Every WebUI block has exactly four fields, uses the matching port, and contains no sensitive URL state; the client receives a trusted views[].uri.
  • Missing input, unsupported formats, an invalid proxy, or capability failure returns a stable, actionable error.