Start on the computer:
ophio doctorRead each failed check and its remedy. ophio setup can revisit skipped setup and offer a standard-approval helper. Do not disable certificate checks or broaden permissions to silence a warning.
The command does not start
If ophio is not found, check ~/.local/bin in your shell’s PATH. If a shared library is missing, install the distribution’s PipeWire and libxkbcommon packages. Linux requires glibc 2.39 or later. See Install on your computer.
Codex requires version 0.153.2 or later. A missing codex-code-mode-host means its bundled helper is missing; fix the native CLI installation. An installed agent may still need sign-in. Settings → Agents and accounts reports integration, account and Models and capabilities. An unsupported or terminal-only agent does not gain native task controls from being installed.
Cannot reach the computer
Check that the computer is awake and Ophio is running. The default loopback listener cannot be reached from a phone. Use the same Tailscale tailnet, or explicitly configure trusted LAN listening and allow_lan, then restart Ophio. Never expose its port to the internet.
Check firewall scope and the addresses offered during pairing. A Windows public-network firewall warning is not a reason to allow all networks. See Pair your devices.
Unfamiliar certificate
The phone only accepts the certificate it paired with. Another computer may have the same address on a different network. Verify the actual computer and why its identity changed before pairing again.
Connected, but a control is unavailable
A missing feature, missing OS consent and missing device permission are different problems. Updating can add a feature; it cannot grant access. Check ophio doctor, the capability message and the device’s grants.
If this device has Manage access, a missing-permission notice can offer a matching switch, such as Allow Read Library. Enable only the permission you need. Otherwise the notice shows an ophio devices allow command to run at the computer. Account access always requires the computer, even for a device with management access. A change to this device’s grants reconnects it automatically.
Enable desktop sharing from the graphical session with ophio desktop enable. A user service installed outside that session may lack its environment. Linux input also needs action-capable desktop notifications. On GNOME 46, a display-scaling change can end capture; use Reopen sharing and review consent again.
A private preview still showing old code may have a server without reload support. Restart that server on the computer. Refreshing the phone view alone may not update it.
The agent does not ask before changing things
New coding Work defaults to Skip permissions. Choose Ask for approval under Launch flags before starting if you want native prompts. Changing phone defaults does not alter an existing task. Ask and Plan stay read-only. See Agents & task permissions.
Alerts do not arrive
Check Settings → Notifications, Android notification permission, both task-alert categories and Unrestricted battery use. Without Unrestricted battery use, alerts arrive only while the app is open. Enable Alerts when the app is closed for the independent watcher. Android stopped alerts offers Start again.
Force-stopping Ophio in Android prevents watcher recovery until you reopen it. A sleeping or unreachable computer cannot send. Unresolved alerts can catch up after reconnecting; an alert already answered should not reappear. See Notifications.
Unknown delivery or stop outcome
Computer acceptance is not agent delivery or successful execution. Inspect the same request and task receipt before sending again. Recovered pending commands require review; they are not automatically sent again.
Stop requested is not a confirmed stop. Check Stop receipt and Still running / unknown. Written files and externally delegated jobs may remain. Use Force stop only where Ophio offers it for an owned process. Check outside processes at the computer before starting dependent work.
Version mismatch
Open Settings → Versions. Update the side named by the error from its trusted original source. Compatibility depends on the negotiated protocol, not identical version numbers. Some new features require a newer companion even when the basic connection works. Drafts and downloaded files remain on the phone.
Controls moved after updating
There are four tabs: Talk, Control, Work and Library. Settings opens from a header button. The former Agents tab is now Library → Agents and Skills. Files are under Library → Files. Desktop targets, Apps and windows, System and Start computer use are under Control → Screens.
Talk opens full-screen. Tap the task title for task history, media and instructions; use Message tools beside the composer for markup and task options. In full-screen desktop control, Show controls restores hidden buttons and Keys opens typing. See Getting around.
Auto routing or Jev commands are missing
Automatic agent selection was removed. Choose an agent explicitly. Jev is now only for voice control: use ophio jev connect, status and disconnect, and Settings → Agents and accounts → Voice control. Typed commands do not need a speech model; spoken commands do. Check the separate browser/desktop switch and target accessibility before widening any device grants.
An updated agent cannot start
Check the version and problem under Keep Claude Code and Codex up to date. A failed managed-copy health check causes fallback to the system binary; that binary must still be installed and signed in. Running tasks keep their version. Turning managed updates off affects future tasks, not a running one. See Updating & rollback.
A preview disappeared
Loopback previews track the computer’s listening server, including manually added entries. A previously seen server that stops loses its entry after 30 seconds; a server never seen listening gets ten minutes. Restart the server and reopen or register the preview if needed. Closing a preview on the phone does not stop its server. See Project previews.
Getting help
Include version and download SHA-256, OS and desktop, permission state and a small sample reproduction. Remove personal paths, real device names, screenshots, tokens and pairing codes. See Platform qualification. Report security issues privately through the security page.