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
| Direction | Carrier | Writer and reader | Purpose |
|---|---|---|---|
| User → Program | /oasn/in/invocation.json | The platform writes it; the Program reads it only on the server | Obtain the current user text, arguments, and attachment paths. |
| Program → user | The oasn-webui fenced block in the final Assistant reply | Agent main writes it; the platform parses it | Project 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"
]
}
}
| Field | Type | How the Program uses it |
|---|---|---|
input.user_prompt | string | The current user's text. If it is blank, ask for the missing information instead of inventing a task. |
input.args | array | The current production projection is normally an empty array. Do not depend on it unless the business contract explicitly requires it. |
input.attachments | string[] | 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
portsfor 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, andwebui_urls. The portrevisionis not the website draft ETag. - Deliver current URLs only when both
sync_status=readyandproxy_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
| Status | Meaning | Action |
|---|---|---|
pending | Configuration or connection readiness is not yet confirmed | Query again within a bounded wait; do not submit old port writes. |
ready | Configuration or proxy checks passed | Require both status fields to be ready, then test the actual HTTP service. |
expired | A short-lived connection has expired | Query the same confirmed configuration; the platform restores missing or expired connections. Do not clear ports. |
revoked | The previous connection was revoked | Report the state and use the current authorized lifecycle flow; do not revive it through a port write. |
unavailable | The current connection cannot be verified | Report the service or Version problem; do not claim readiness or rebuild by default. |
not_configured | The confirmed configuration has no business ports | Check the confirmed configuration and existing fixed-port rules; the CLI does not add arbitrary ports. |
sync_status=failed | Configuration failed or an old write intent was retired | Preserve 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
Listen on all container interfaces
The business process must listen on0.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.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 fixedstart-webui.shor a fixed health path.Preserve the proxy prefix
The WebUI is mounted under a/webui/proxy/<id>/subpath.fetch('/api/health')andsrc="/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.

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}
```
| Field | Strict rule |
|---|---|
type | Must be the string "webui". |
title | Must be a non-empty string. Use a page name that users can understand. |
url | For 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. |
defaultOpen | Must 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 ordinaryjsonblock or append parameters to the fence info. - The port must be declared on the Version. Do not copy a public
webui_urlsvalue returned by the CLI into the block. - Internal HTTP allows only
127.0.0.1or 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=truevalues, 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
Local Sandbox service
Confirm that the process listens on0.0.0.0, access the target page and API through loopback, and verify the business response content.Port and proxy status
Runversion webui-ports getand confirmports,sync_status=ready,proxy_status=ready, and the currentwebui_urlstogether.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.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_promptand the currentinput.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_statusandproxy_statusare 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.