diff --git a/setup/register-claude-token.sh b/setup/register-claude-token.sh
index e0adfc6..324b1be 100755
--- a/setup/register-claude-token.sh
+++ b/setup/register-claude-token.sh
@@ -51,13 +51,34 @@ command -v script >/dev/null \
 tmpfile=$(mktemp -t claude-setup-token.XXXXXX)
 trap 'rm -f "$tmpfile"' EXIT
 
-cat <<'EOF'
+# Detect headless. Mirrors `isHeadless()` in setup/platform.ts: on Linux
+# with neither DISPLAY nor WAYLAND_DISPLAY set, no graphical session
+# exists, so `claude setup-token` won't be able to auto-open a browser
+# and the user will need to copy the printed sign-in URL by hand. The
+# pre-message copy below is swapped accordingly so we don't promise a
+# browser pop that will never happen.
+is_headless=0
+if [ "$(uname -s)" = "Linux" ] && [ -z "${DISPLAY:-}" ] && [ -z "${WAYLAND_DISPLAY:-}" ]; then
+  is_headless=1
+fi
+
+if [ "$is_headless" = "1" ]; then
+  cat <<'EOF'
+A sign-in link will appear for you to sign in with your Claude account.
+When you finish, we'll save the token to your OneCLI vault automatically.
+
+Press Enter to continue, or edit the command first.
+
+EOF
+else
+  cat <<'EOF'
 A browser window will open for you to sign in with your Claude account.
 When you finish, we'll save the token to your OneCLI vault automatically.
 
 Press Enter to continue, or edit the command first.
 
 EOF
+fi
 
 cmd="claude setup-token"
 if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then