THE SHORT ANSWER
Check the Mac relay first, the device connection second, and voice transcription third. An online relay does not prove that Whisper is installed, and an empty project list does not necessarily mean pairing failed.
The portal says the Mac relay is offline
Confirm that the Mac is powered on and connected to the internet. Look at the Terminal window where the relay was started. If you closed it, start the installed relay again with ~/rokid-relay/start and read any error message before retrying.
The starter checks Node.js and the Claude Code executable. It needs Node.js 20 or later; having an older version installed is different from having no Node installation. Claude Code also needs a working authenticated setup on that same Mac.
If the relay key was replaced, the saved old key may no longer work. Use a fresh one-time command from the portal on the intended Mac. Do not run copies on different Macs with the same relay key and expect the portal to treat them as independent hosts.
Keep the Terminal open once connected. Do not expose a local relay port to the internet or disable security tools as a shortcut.
The relay is online, but the glasses do not connect
Check the glasses’ Wi-Fi connection or the phone hotspot they use. A Wi-Fi icon alone does not prove internet access, particularly on a network that requires a browser sign-in. Try a known working connection.
Open Rokid Claude on the glasses. When disconnected, a tap opens the scanner. In the portal, create a pairing code with the device type set to Rokid Glasses, not Phone companion. Give the scanner camera permission when requested.
If the paired device has been revoked, it needs a new credential. If several host profiles are saved, verify the chosen host. A valid profile for another Mac does not identify the one currently shown in your portal.
A QR code is missing or will not scan
Pairing codes are shown once. If you dismissed the result before scanning, generate a new pairing entry rather than expecting the portal to reveal the same secret again. Revoke abandoned entries you will not use.
Display the code at a readable size, keep it unobstructed and avoid reflections. Check that you are using the app’s scanner for the glasses code and the phone camera for a phone-companion code.
Do not paste the full QR payload into a support message. It carries a device token. Describe the symptom and device type, or share a redacted screenshot with the entire code and credentials removed.
Recording works, but no transcript appears
This usually calls for a speech-input check rather than another pairing attempt. The relay can run without working voice transcription. Read its startup messages: it reports missing whisper-cli, an incomplete model download or insufficient free disk space.
- Confirm microphone permission on the glasses.
- Tap once to start and once to stop; transcription follows the finished recording.
- Confirm Whisper is installed on the Mac and the speech model download completed.
- Check that the selected language matches what you are speaking.
- Try a short sentence in a quiet place before a technical instruction.
If the transcript appears but the agent has not started, check whether you are at Heard waiting to choose Send. With confirmation enabled, that pause is expected. Discard a wrong transcript and record again.
Projects or sessions are missing
The project picker uses local Claude Code transcript history and working-directory information. It is not a file browser for every folder on your Mac and it does not list your online repositories automatically.
Open Claude Code on the Mac in the intended repository, create a normal conversation, and make sure the working folder still exists. The current project list shows up to 20 discovered projects, ordered by recent transcript activity.
For a missing session, confirm the selected project and host first. A session on your work Mac is not automatically copied to your home Mac. Deleted or unavailable Claude transcripts cannot be resumed just because the glasses remember a name.
A task is busy, a queue disappears, or a connection drops
Only one turn can run at a time in one session. If that session is busy, use the running-task menu to queue a follow-up or interrupt it. Switching to another session is possible, but queued instructions tied to the previous context are dropped after a session change.
A disconnected display and a stopped agent are not the same event. The Mac may still be working while the glasses lose connectivity. Reconnect and inspect the session state before resubmitting the instruction, especially if it could make duplicate file changes or external actions.
The relay persists session events and supports replay after reconnection. A Mac shutdown or relay restart is different: a previously running turn may be reported as interrupted, not silently continued. Inspect its outcome before deciding to resume.
Phone attachment problems and useful diagnostic notes
The phone companion supports up to four images per message and converts supported image inputs to JPEG. If an image fails to decode, try JPEG or PNG. Paste exact logs as text rather than sending a tiny screenshot.
When reporting a persistent issue, record the glasses model, app version, selected language, whether the relay shows online, the approximate time and the exact visible error. Include which step failed and which checks above succeeded.
Remove relay keys, device tokens, pairing URLs, QR codes and confidential repository content from anything you share. A short reproducible description is more useful than a full unredacted log.
Based on the current Rokid Claude application and setup flow. Early-access behavior and compatibility may change.