Browser Terminal

Platform notes

• macOS / Linux examples often use zsh or bash
• Windows examples often use pwsh or powershell
• the port is local configuration, not a universal constant
• the browser only needs to be one that OpenClaw can control in that environment

Input strategy

For ttyd/xterm.js terminals, ordinary browser type/fill can be flaky.

Prefer this order:

1. Focus the terminal page or textarea.
2. Use page-side terminal paste/injection when available, for example:
   • window.term.paste('pwd\\r')
3. If needed, send an extra Enter afterward.
4. Verify success from visible terminal output or prompt state.

Good use cases

• Running shell commands the user wants to visibly watch in browser
• Step-by-step CLI troubleshooting
• Human-in-the-loop flows where the user may need to enter a password
• Simple coding or environment checks where browser visibility matters more than speed

Risk gate

Before executing risky operations, pause and require the user's explicit confirmation word:

• confrim

Treat these as risky:

• sudo or privileged/system-changing commands
• deletion, overwrite, or destructive file operations
• system, service, or configuration changes
• security-sensitive changes
• commands with broad or difficult-to-reverse effects

If the risky action also produces a password prompt, let the user manually enter the password. Never ask for, store, or process the password content directly.

Fallback rules

Use direct local exec instead when:

• browser control is unavailable
• ttyd is not available and should not be started
• browser automation cannot reliably control the terminal
• the task needs long unattended background execution better suited to exec/process tools
• the user explicitly asks for non-browser execution

Verification

After sending a command, confirm one of these:

• expected output appears in the terminal
• the working directory or prompt changes as expected
• a follow-up command confirms the action succeeded

Do not claim the browser terminal command worked unless the output or terminal state confirms it.

References

• For common failures and recovery steps, read references/troubleshooting.md.
• For more specific Windows ttyd guidance, read references/windows-ttyd.md.