Install or Login Stuck? The Most Common Problems
Searchable illustrated FAQ | For academic users with zero technical background | Find your problem by keyword
Stuck while installing the AI, logging in, or setting up an API key? The most common problems are grouped below. Use your browser's in-page find (⌘F) to search for a keyword and jump straight to your issue.
Installation problems
Q: I clicked "Install" and it's stuck / spinning forever / says it failed — what do I do?
That row will change to "Retry" (a circular-arrow icon). Click Retry to run the installation again.
If it keeps failing, it's almost always a network problem — the installer needs to reach claude.ai (for Claude Code) to download the official install script. Check:
- Can your network open claude.ai normally?
- Is a proxy / VPN interfering? Try switching it or turning it off, then retry.
- Corporate or campus networks may block the download — try a different network.
🖼 Screenshot: close-up of the "Retry" button on the Claude Code row, circled in red.
Q: I already installed Claude Code before — why is it asking me to install it again?
This usually means Scholardo couldn't find the claude command in the default locations (it isn't on the PATH Scholardo detects) — it doesn't mean it's missing from your computer. Try:
- Restart Scholardo and check the chooser again — very often it's detected after a restart.
- Advanced self-check (optional): open the Terminal app, type
which claude, and press Return.- If it prints a path → Claude Code is installed; Scholardo's environment just didn't inherit that path. Restart the app or click the row again to launch.
- If it prints nothing → it really isn't installed in the default location. Just click Install in the chooser and let Scholardo install it once.
Q: A wall of text I don't understand scrolled by during installation — is that normal?
Completely normal. That's the output of the download-and-install process — you don't need to read any of it. Wait for it to stop; the "Choose an agent" card will reappear automatically (this is by design in Scholardo). Then click the row to launch.
Login problems
Q: Authorization succeeded in the browser, but nothing happens back in the Scholardo terminal — what now?
- Return to the Scholardo window and wait a few seconds — the authorization handoff can be slow.
- Still nothing? Go back to the chooser and click that agent row again to relaunch it and redo the login.
- Make sure you authorized with the correct account (e.g. the account that actually has your Claude subscription, not another account without one).
Q: When choosing a login method, I think I picked the API option — was that wrong? Will I be charged extra?
For Claude Code / Codex, choose the "log in with your subscription" option (subscription / Claude account / ChatGPT account). Do not pick the option that mentions API / Console / usage billing — that path bills you separately per token, on top of any subscription.
If you picked the wrong one: exit the login wizard, go back to the chooser, and launch that agent again to redo the login flow — this time choose the "subscription" option.
Configuration problems (third-party models / DeepSeek)
Q: The terminal says "No DeepSeek config yet" — what do I do?
Full message: ⚠️ No DeepSeek config yet. Add it with your API key in Settings ▸ AI Agent, then relaunch.
This means your key isn't set up yet. Go to Settings ▸ AI Agent ▸ the "AI providers" section, make sure your DeepSeek API key is filled in, then start a new session. See P0-3 for the full walkthrough.
Q: The terminal says "Couldn't read the DeepSeek key from the Keychain" — what do I do?
Full message: ⚠️ Couldn't read the DeepSeek key from the Keychain. Re-save it in Settings ▸ AI Agent.
Go back to that same section in Settings ▸ AI Agent and paste the key in again and save it. That's all it takes.
Q: I forgot to copy my DeepSeek API key when I created it, and now the full key is gone after closing the dialog?
An API key is shown in full only once — once the dialog is closed, you can't view it again. Go back to the API keys page on the DeepSeek platform, delete the old key and create a new one, then paste the new key into Scholardo.
Q: I entered my API key — so why does picking DeepSeek (or Kimi / GLM) still say I need to install Claude Code?
Because these third-party models run on top of Claude Code — Claude Code acts as the "carrier" here. If the row shows "Needs Claude Code installed" + Install, then on an overseas network just click Install and Scholardo sets up the carrier automatically (it only installs the runtime shell — you do not need to buy a Claude subscription).
⚠️ In mainland China: this one-click Install runs from
claude.aiand is blocked. Install Claude Code via npm (domestic mirror) first — follow "Step 1" of Claude Code in Mainland China (you don't need its later env-var steps); the row turns ready once the carrier is in. See "Must-read for users in mainland China" in Full DeepSeek Setup.
Still stuck?
- Make sure you're on the right route: users in mainland China should follow the DeepSeek path instead of repeatedly retrying Claude / ChatGPT subscription sign-up (P0-2 explains why).
- Walk through P0-1 (Claude subscription edition) or P0-3 (DeepSeek edition) again from the top.
Shot list
All screenshots are from the current Scholardo release. Always redact API keys in screenshots.
| # | What to capture | Source | Key callout |
|---|---|---|---|
| Fig. 1 | Close-up of the "Retry" button on the Claude Code row | Scholardo | Circle Retry in red |
| Fig. 2 | Terminal warnings: DeepSeek not configured / Keychain read failure | Scholardo | Circle the "Settings ▸ AI Agent" instruction |
| Fig. 3 | Re-saving the key in Settings ▸ AI Agent ▸ the "AI providers" section | Scholardo (key redacted) | Circle the key field and the save action |
| Fig. 4 | DeepSeek row showing "Needs Claude Code installed" + Install | Scholardo | Side note: "this installs the carrier — no extra subscription needed" |
Data privacy disclosure
Troubleshooting these issues does not send any additional data anywhere. But keep in mind that during normal use, your manuscript content is sent to your chosen AI provider for processing (Anthropic / DeepSeek, etc.). Your API key is stored only in your local Keychain and is never uploaded. If your material involves unpublished data, participant privacy, or confidentiality agreements, first confirm that sending it to a third-party AI service complies with your institution's requirements.