Troubleshooting

Preserve the error code, current state, and IDs before making the smallest possible correction. Never copy access tokens, Cookies, private keys, or complete credentials into a ticket, chat, or screenshot.

The offline handbook opens with a blank content area

If navigation and the header are visible but the main content area is blank, the generated assets/content.js is usually missing, failed to load, or contains an empty content array. A complete offline package must include at least:

index.html
assets/app.js
assets/styles.css
assets/content.js
assets/screenshots/...

Confirm that you did not copy only index.html.
Confirm that assets/content.js exists and is not a zero-byte file.
Extract the complete directory again, then open the index.html inside that directory.
If it is still blank, open browser developer tools and check for content.js or CSP loading errors.

CLI installation and environment checks

Symptom/error	Cause	Action
`CLI_DIGEST_MISMATCH`	The downloaded script does not match the SHA-256 supplied by the current trusted Skill	Stop. Download again from the bound URL and copy the digest exactly; never bypass verification
`doctor` returns `action_required`	At least one of SSH, ssh-keygen, the local loopback port, or a public key is unavailable	Install or enable each missing prerequisite according to the boolean fields; obtain approval before creating a key
`SSH_KEY_REQUIRED`	No usable public key exists	After explicit approval, run `oasn-sa-dev ssh-key ensure --create`
`SSH_KEY_EXISTS`	The target private-key or public-key path already exists	Do not overwrite it. Use a valid existing key or choose a new, explicit path
`SSH_KEYGEN_REQUIRED`	The system cannot find OpenSSH `ssh-keygen`	Install or enable the OpenSSH client, then rerun `doctor`

Symptom/error	Action
`LOGIN_TIMEOUT`	Complete browser authorization within the allowed time, confirm that security software is not blocking the local loopback port, and retry the original command
`auth status` is `login_required`	Run the intended authenticated CLI 0.7.3 command—such as `workspace sources/create/status/resume/connect`, `version webui-ports`, or an allow-listed `portal` operation—and follow the browser sign-in prompt
`credential_store=unavailable`	Enable Windows Credential Manager, macOS Keychain, or Linux Secret Service. The CLI will not fall back to a plaintext session file
`auth logout` reports `server_status=unconfirmed`	Evaluate local deletion and server revocation separately. Check whether `status` is `local_delete_failed`, together with `server_status` and `server_revoked`

The Workspace never becomes ready

`WORKSPACE_TIMEOUT`

A timeout does not prove creation failed. The error includes workspace_id and last_status. Preserve that ID and continue waiting with the status command; do not immediately create another Workspace:

oasn-sa-dev workspace status --workspace-id <WORKSPACE_ID>

To adjust the bounded wait, use --timeout-seconds 30..3600, --poll-interval-seconds 1..30, and --login-timeout-seconds 60..600.

`WORKSPACE_NOT_READY`

The Workspace has entered failed, closed, published, cleanup_pending, or close_pending. Record the status and failure_code from the error, and do not continue with SSH/SCP.

`WORKSPACE_RESPONSE_INVALID`

An active status response is still missing webchat_url or expires_at. Preserve the Workspace ID and missing field for platform investigation; do not construct an address yourself. A status response is not expected to prove SSH. For SSH/SCP, run workspace connect with an existing local key and proceed only after ssh_binding_status=bound and ssh_verified=true. Preserve exact SSH_COMMAND_INVALID, SSH_CONNECTION_FAILED, or SSH_AUTHENTICATION_FAILED evidence rather than editing the returned command.

WebChat or integration testing fails

First confirm that the Program, configuration, and dependencies really exist under /oasn, rather than only in a modified local copy.
If normal text works but attachments fail, verify actual attachment download/reading and output-file delivery; do not inspect only chat text.
If a Plugin fails, inspect its runtime state and make one real call.
If MCP/A2A fails, check transport-level isError, business status, and output fields together.
If webui_urls=[], run oasn-sa-dev version webui-ports get --version-id <agent_version_id>. not_configured means the Version has no declared ports; pending means query again without replaying set/refresh; unavailable means current proxy validity cannot be confirmed. Deliver links only when sync_status=ready and proxy_status=ready.
HTTP 410 means the business proxy session is invalid, expired, or revoked; it is not an Owner OAuth failure. Query port and Workspace state, then obtain authorization for workspace resume when the Workspace connection expired or webui-ports refresh when a new business-link generation is required. Do not clear ports automatically.
HTTP 502 means the proxy cannot reach the declared business port. Verify that the process is running and listening on 0.0.0.0:<declared-port>, then test the page and API locally; OAuth login or a mapping refresh does not start the service.
If an oasn-webui fence appears as text instead of a page, require exact lowercase fence info and a JSON object containing exactly type, title, url, and boolean defaultOpen. Invalid JSON, missing/extra fields, or wrong types remain text. A structurally valid but unsafe URL, undeclared internal port, private address, or sensitive query/fragment fails closed with OPENCLAW_FINAL_REPLY_INVALID; downstream validation may return RUN_RESULT_INVALID or MCP_INVOCATION_RESULT_INVALID.

Publishing stalls or fails

PRICING_MAPPING_INVALID: verify that Gross margin is an integer percentage from 0 to 100. Do not enter a decimal or assume automatic rounding.
queued/running: continue observing the current Job; do not click Publish again.
failed: record the failed stage and page error, correct and resave the draft, then start a new Job.
The Job is succeeded but publication is pending/syncing: publishing is not complete; continue waiting for visibility convergence.
Publication is failed: preserve the Job ID, version ID, and error. Do not claim the version was published.
The version is visible but cannot be invoked: check whether it remains Offline; click Go Online.
PORTAL_RESULT_UNKNOWN after an authorized CLI portal write means the result is uncertain, not necessarily failed. Query the target object first and preserve the original body and idempotency key; do not blindly submit a new publish intent.

Do not troubleshoot by guessing commands

Use the real CLI 0.7.3 command boundary

portal <operation>, workspace sources, workspace resume, version webui-ports, workspace create --version-id ID --fresh, and workspace create --version-id ID --source-version-id SOURCE_ID are implemented. Run oasn-sa-dev portal commands or the relevant --help instead of guessing parameters. Still absent are a public workspace close, a workspace publish command, and a generic file sync command; publishing is available through the website or the allow-listed portal publish operation. The portal is not raw URL/method passthrough, and the website form still has no WebUI-port field. Never bypass a missing public operation with an internal API.

The offline handbook opens with a blank content area

CLI installation and environment checks

Browser sign-in and credential storage