feat(install): auto-detect agents, route MCP auth to QR mode for remote installs

[Nowhitestar]

Summary

Two end-to-end improvements to install.sh / install.ps1, mirrored across both:

1. Agent auto-detection

Probe well-known config dirs and binaries for ~18 of vercel-labs/skills' 45 supported agents (claude-code, cursor, codex, gemini-cli, opencode, openclaw, qwen-code, iflow-cli, windsurf, warp, amp, crush, goose, droid, kode, kilo, kimi-cli, kiro-cli).

When detection finds anything, the skills add step gets -a id1,id2,… instead of dumping the user into the multi-select. New flags:

• --list-agents — preview what we'd auto-select (and exit)
• --all-agents — skip our detection, let skills CLI scan everything
• --only — manual override (unchanged)

2. Local-vs-remote MCP auth routing

The current --auth-login always auto-opens a browser. On SSH sessions, Docker containers, and OpenClaw remote channels (where the user is on a phone), that silently launches a browser they can't see — leaving them stuck on "Waiting for authorization…".

Detection (any signal fires ⇒ remote):

Signal	Notes
$HOME/.openclaw exists	OpenClaw runtime — most reliable single signal
$SSH_CONNECTION / $SSH_TTY	Generic SSH session
Linux without $DISPLAY / $WAYLAND_DISPLAY	Headless

When remote, pass --no-browser to the MCP CLI, which prints URL + ANSI QR for the user to scan with a phone.

New flags:

• --remote / --local — force either mode
• --force-mcp — re-auth even if AgentKey is already configured

Also adds an idempotency short-circuit: if any known MCP config already has an agentkey block with a valid-looking API key, skip the auth step entirely (--force-mcp to override).

3. Docs

README.md + docs/README_zh.md updated to document the new flags and add a dedicated "Installing over SSH / Docker / OpenClaw" section.

Companion PRs (server side)

The MCP-server changes that this installer routes to ship in a chain of three PRs against chainbase-labs/AgentKey-Server:

PR	Status	What it adds
#2	merged	--no-browser / --qr / --no-qr flags + qrcode-terminal dep (v0.3.5 source bump)
#3	merged	Bump to 0.3.6 — npm 0.3.5 had been published from a pre-merge commit and shipped stale dist/
#4	open	Fix QR not rendering in --no-browser (CJS interop bug — qrcode-terminal's generate lives on .default under NodeNext); bump to 0.3.7

This installer needs @agentkey/mcp@0.3.7 to be on npm for the QR flow to actually work. Sequence:

1. Merge docs: refresh README onboarding and FAQ framing #4 ✅
2. Maintainer runs cd mcp-server && npm publish (no npm-publish CI workflow) ✅
3. Merge this PR — npx -y @agentkey/mcp will then pull 0.3.7+ and the --remote path renders the QR

This installer change is forward-compatible: it can land anytime — older @agentkey/mcp versions silently ignore the unknown --no-browser flag, so worst case a remote user gets the old browser-opens-on-the-wrong-host UX until the new mcp publishes.

Test plan

Verified end-to-end on macOS against a local build of @agentkey/mcp@0.3.7 (server PR #4):

• Bash syntax check passes (bash -n install.sh)
• install.sh --help renders all 5 new flag rows
• install.sh --list-agents correctly prints detected agents on test host (10 agents incl. openclaw)
• install.sh --remote --local exits with code 1 (mutex)
• install.sh --skip-skill short-circuits with "AgentKey is already configured…" when configs have agentkey
• install.sh --remote --skip-skill --force-mcp end-to-end: prints Detected remote install context — printing QR + URL instead of opening a browser here, then reason: $HOME/.openclaw exists (OpenClaw runtime), launches mcp CLI, renders 16-row ANSI QR, polls — no open process spawned
• All 4 mcp 0.3.7 flag combinations behave correctly (--no-browser / --no-browser --no-qr / --qr / no-flags back-compat)
• install.ps1 not lint-checked locally (no pwsh on test host); logic is a strict mirror of bash — needs Windows smoke before merge
• Inside a real OpenClaw container — confirm ~/.openclaw triggers as expected

Why now

Users running the installer via OpenClaw / Claude Code remote channels (on a phone) currently see a black-hole UX: the browser opens on the wrong machine and the install process appears to hang. The detection here removes the manual --remote flag for the common case.

🤖 Generated with Claude Code

[lxcong]

@claude review

[github-actions]

🤖 Claude security review requested by @lxcong. Running against HEAD f53a8488cfb1fe6829119a689ceb5ce4d747f228...

[claude]

🤖 Claude security review — HEAD: f53a848

Scope: New agent-detection helpers + remote/QR auth routing in install.sh and install.ps1; matching doc updates in README + zh README.

✅ No security or convention issues found.

What was checked:

• Credentials / secrets: No credential patterns in added lines. The already_authed / Test-AlreadyAuthed regexes match against user-owned local config files (not leaked values).
• Shell injection (install.sh): _expand_path uses case with no eval; _probe_marker passes ${m#cmd:} / ${m#path:} only to command -v / [ -e ]; all marker sources are hardcoded. TARGETS flows into "${AGENT_LIST[@]}" with proper array quoting before npx "${SKILLS_ARGS[@]}". ui_info uses printf … %s so user-supplied --only values are never in the format string.
• Shell injection (install.ps1): Test-AgentMarker uses Get-Command / Test-Path -LiteralPath on hardcoded markers; $targets is passed as a proper array to & npx @skillsArgs. -match in Test-AlreadyAuthed has $content as the target (not the pattern), so no regex injection.
• New curl | bash URLs: Only agentkey.app — same origin as the existing installer. deb.nodesource.com / rpm.nodesource.com are unchanged pre-existing lines.
• CI/Workflows: No .github/workflows files touched.
• Repo invariants: SKILL_REPO="chainbase-labs/agentkey" (sh:L20) and $SkillRepo = 'chainbase-labs/agentkey' (ps1:L35) unchanged. No managed files (version.txt, CHANGELOG.md, plugin.json version) directly edited.
• PR title: feat(install): auto-detect agents, route MCP auth to QR mode for remote installs — valid Conventional Commit. ✓

💡 Suggestions (nice-to-have)

• scripts/install.sh:L394 — --only values are split on , and passed as separate -a <id> arguments with no format validation. A value like -x would be forwarded to the skills CLI as an option flag rather than an agent ID. Consider rejecting entries that don't match [a-z][a-z0-9-]* before building SKILLS_ARGS.
• scripts/install.sh:L203-L204 / scripts/install.ps1:L132 — The already_authed check uses [^"]* between the key name and value (bash) and \s*:\s* (PS1), creating a small false-positive risk from hand-edited configs. This is only a convenience skip, not a security gate, but tightening bash to \s*:\s* would match the PS1 regex and reduce drift.

---

Review triggered by @lxcong
via @claude review.