OpenClaw guide

The Ai4Scholar plugin connects six academic platforms to OpenClaw: Semantic Scholar, PubMed, Google Scholar, arXiv, bioRxiv, and medRxiv. Once configured, describe a research task in the conversation and the agent can call the appropriate tools.

This guide covers Ai4Scholar 0.6.11, which includes 35 tools, optional Scholar Mode, and shortcuts for managing literature. View the plugin on ClawHub or npm.

Quick navigation

Preparation

1. Install and configure OpenClaw, and confirm that you can converse with the agent normally.
2. Sign in to Ai4Scholar and create or copy your key in API key management.
3. Check that your OpenClaw and Node.js versions meet the plugin's requirements.

Check the versions in a terminal:

openclaw --version
node --version
npm --version

For newer releases, follow the requirements in the npm plugin description and OpenClaw installation documentation. YOUR_API_KEY in these examples is a placeholder. Replace it in your local configuration; do not send your real key in a chat.

Installation and configuration

Install the plugin

Run this on the machine that runs OpenClaw:

openclaw plugins install clawhub:ai4scholar

You can explicitly choose npm as the installation source instead. Use either method:

openclaw plugins install npm:ai4scholar

If the installer asks you to confirm the source, check the package name and source before following the prompts. See the OpenClaw plugin installation documentation for installation sources, compatibility, and local packages.

Save your API key

Edit ~/.openclaw/.env in the home directory of the user running the Gateway, and add this line. If the file already exists, keep its existing contents:

AI4SCHOLAR_API_KEY=YOUR_API_KEY

On macOS / Linux, you can restrict the file to read and write access by the current user:

chmod 600 ~/.openclaw/.env

On Windows, the corresponding file is usually at %USERPROFILE%\.openclaw\.env. If the Gateway runs on a server, in a container, or under another system user, edit the configuration directory actually used by that runtime environment.

Configure the plugin

Edit ~/.openclaw/openclaw.json and merge the following ai4scholar entry into the existing plugins.entries object, keeping other plugin and model settings:

{
  "plugins": {
    "entries": {
      "ai4scholar": {
        "enabled": true,
        "config": {
          "apiKey": "${AI4SCHOLAR_API_KEY}"
        }
      }
    }
  }
}

${AI4SCHOLAR_API_KEY} is an environment-variable reference. Leave it unchanged; put the real key in the .env file from the previous step.

Reload the Gateway

After changing the environment file, restart the Gateway to load the new key:

openclaw gateway restart

If the Gateway has not started yet, use openclaw gateway start. For an instance running in the foreground, stop it in its original terminal and start it again.

Ask OpenClaw to help with setup

You can also save the key in the .env file above, then send this request to OpenClaw:

Help me install the Ai4Scholar plugin using openclaw plugins install clawhub:ai4scholar.
The API key is already saved in ~/.openclaw/.env for the Gateway user, under AI4SCHOLAR_API_KEY.
Enable the plugin in plugins.entries.ai4scholar in openclaw.json.
Set config.apiKey to the environment-variable reference ${AI4SCHOLAR_API_KEY}, preserving the existing configuration.
Do not read or display the key. After setup, restart the Gateway and check that the plugin loaded successfully.

What the agent can execute depends on its current tool permissions. You can also complete the earlier steps manually.

Verify the setup

First inspect the plugin list and runtime registrations:

openclaw plugins list
openclaw plugins inspect ai4scholar --runtime --json

Confirm that ai4scholar is enabled and has no registration errors. Version 0.6.11 should register 35 tools. This checks loading in the command-line process; you still need to test a call in an actual conversation.

Return to OpenClaw and send:

Use Ai4Scholar's search_semantic to find papers on protein structure prediction from the past three years.
Return the titles, years, short abstracts, and source links for 5 papers.

An actual tool call followed by paper results confirms that the plugin and API key work in the current conversation. Direct search tools for arXiv, bioRxiv, and medRxiv do not depend on an Ai4Scholar API key, so testing only those sources cannot verify that the key is configured correctly.

Scholar Mode

Scholar Mode adds academic tool-use guidance to the agent to help it choose paper search, reading, and citation tools. It is optional; ordinary tool calls do not require it.

To enable it, add hooks to the same plugin entry and enable config.scholarMode:

{
  "plugins": {
    "entries": {
      "ai4scholar": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "apiKey": "${AI4SCHOLAR_API_KEY}",
          "scholarMode": true
        }
      }
    }
  }
}

If hooks.allowPromptInjection: false is already set, Scholar Mode will not activate. After saving, follow OpenClaw's loading instructions and begin a new conversation turn.

Tool list

These are the 35 tools in version 0.6.11. For newer versions, inspect the list with openclaw plugins inspect ai4scholar --runtime --json.

Paper search

Paper details

Citations and references

Author information

Paper recommendations

PDF links and full-text reading

Version 0.6.11 removed the old download_by_doi tool. read_by_doi extracts full text and does not send PDF attachments. If you need a PDF, use the link tool for the corresponding source.

Automatic citation annotation

Scientific illustration

Shortcut commands

Use these commands in an OpenClaw chat to manage literature. Literature-management commands require the current sender to be authorized by OpenClaw.

Usage examples

Search papers

Find research on CRISPR in cancer immunotherapy from the past three years.
Search PubMed first and list the paper titles, publication years, main findings, and source links.

Explore a paper and its citation network

Look up the details of the paper with DOI 10.1038/s41586-021-03819-2.
Then find representative papers that cite it and explain their research directions.

Read the full text

Retrieve the full text for DOI 10.1038/s41586-021-03819-2.
Summarize the Methods section and distinguish the paper's conclusions from your own analysis.

Access to paywalled full text depends on whether the machine running OpenClaw has an institutional subscription or other authorized access. For open-access papers, try the reading tool for the corresponding source first.

Add citations automatically

Use auto_cite to add citations to the Introduction below in IEEE format.
Return the reference list and BibTeX as well:
 
(Paste the academic text to annotate here)

Create a scientific illustration

Draw a diagram of the CRISPR-Cas9 gene-editing mechanism.
Label Cas9, guide RNA, and target DNA, in a style suitable for a research paper.

To revise an existing image, send it in the conversation first, then describe the structure, labels, colors, or style you want to change.

Cloud MCP setup

If you only need cloud academic search, you can also use Ai4Scholar's SSE service. This and the plugin are separate integration methods. The available tools depend on the list actually returned by the cloud service; Scholar Mode and the shortcuts above are provided by the plugin.

In OpenClaw versions with a built-in MCP client:

1. Open Settings → MCP → Add server in the Control UI.
2. Enter ai4scholar as the name and select SSE as the transport.
3. Enter https://mcp.ai4scholar.net/sse as the service URL.
4. In the server's configuration editor, set the header name to Authorization and its value to Bearer YOUR_API_KEY. Replace the placeholder and retain the space after Bearer.
5. Save and enable the service, then check the connection:

openclaw mcp doctor ai4scholar --probe

Current OpenClaw versions store MCP services under mcp.servers. Do not copy a top-level mcpServers configuration from another client directly. See the OpenClaw MCP documentation for version differences and configuration fields. For other clients, see our Cloud MCP SSE setup guide.

FAQ

"plugin not found" after installation, or no tools appear

1. Run openclaw plugins list and confirm that the plugin is installed in the same runtime environment used by the Gateway.
2. Check that plugins.entries.ai4scholar.enabled is true and that the plugin configuration contains the correct apiKey reference.
3. If you use plugins.allow, make sure it includes ai4scholar, and check that plugins.deny does not disable it.
4. Run openclaw plugins inspect ai4scholar --runtime --json to view the specific loading error. If versions are incompatible, update OpenClaw and Node.js to meet the plugin's requirements first.

Search fails or returns no results

• Authentication error: Check the Gateway user's .env file and the config.apiKey reference. Restart the Gateway after changing environment variables.
• Network error: Check whether the machine running OpenClaw can reach Ai4Scholar and the selected literature source.
• Successful response with no results: Broaden the keywords, years, or filters; try English keywords or another source.
• Insufficient allowance: Check your balance and usage in Ai4Scholar.

Full-text reading fails or the text quality is poor

Paywalled papers require the appropriate access permissions. Without an institutional subscription, try open-access papers or sources such as arXiv, bioRxiv, and medRxiv first.

Scanned PDFs, text embedded in images, and complex layouts can affect full-text extraction. If content is missing, check the original PDF. Finding a paper's metadata does not guarantee access to its full text.

spawn EINVAL during installation on Windows

First run node --version and npm --version to confirm that the versions meet the requirements and that npm works in the current terminal. Update OpenClaw and retry installation.

If the npm call still fails during installation, download the npm package in PowerShell first, then install it through OpenClaw:

npm pack ai4scholar

Note the .tgz filename printed by the command, then install that file. For example, if you downloaded 0.6.11:

openclaw plugins install .\ai4scholar-0.6.11.tgz

Use the filename for the version you actually downloaded. After installation, continue with the API key configuration and verification steps in this guide. If the Node.js or OpenClaw version is incompatible, installing a local package does not bypass the version requirements.

Update the plugin

For a plugin installed through ClawHub or npm, run:

openclaw plugins update ai4scholar
openclaw plugins inspect ai4scholar --runtime --json

Updates reuse the recorded installation source. If OpenClaw asks for a restart, run openclaw gateway restart. For a plugin installed from a local archive, download the new package and follow the installer's update instructions.

When upgrading from an older version to 0.6.11, remove references to download_by_doi from custom prompts and tool lists. The plugin does not install updates automatically; the old autoUpdate configuration field no longer takes effect.

Billing and help

When the plugin calls Ai4Scholar services for search, citations, illustration, and other tasks, it consumes credits according to the corresponding service rules. Model usage in OpenClaw is billed separately. See the pricing page for current prices, and check your balance and call history on your account page after signing in.

If you encounter a problem, submit the plugin version, OpenClaw version, and error details through Feedback. Remove API keys before submitting. Plugin release information is available on ClawHub and npm.