Upgrading
This page explains version rules, important protocol-evolution notes, and compatibility boundaries when upgrading from an older release to the current version.
Version coverage
This page covers important compatibility boundaries for @nb-corp/nb-search as it evolves from 0.3.x / 0.4.x to 0.5.2. Before upgrading or investigating compatibility, check the locally installed version and read the CHANGELOG.
Update the CLI or project SDK from the official npm registry:
# Global CLI
npm install -g @nb-corp/nb-search
# Project SDK
npm install @nb-corp/nb-searchUpgrade notes
0.5.1–0.5.2: Explicit Zhihu opt-in, multi-key rotation, and keyUsage()
- Opt-in Zhihu adapter (
zhihu): Addszhihu.search,zhihu.global, andzhihu.synthesis, but does not inject any instance, credential slot, or Lane into the built-in default configuration. Upgrading does not affect existing default configuration. See Web search sources: Explicitly enable Zhihu for the enablement method and free-quota gate. - Up to 32-key pool and
keyUsage(): ExistingNB_SEARCH_*_API_KEYenvironment variables remain compatible with both a single key and a comma-separated multi-key list. The local SDK addsruntime.keyUsage()(LocalNbSearchRuntime); the remote client and MCP tool list remain unchanged.
0.5.0: Keyless default search, Defuddle direct fetch, and ordered URL routing
- Default search source (
duckduckgo.search): Whendefaults.search_laneis not explicitly configured, general search uses keylessduckduckgo.searchby default. If an upstream host depends on the old behavior of returningDEFAULT_NOT_CONFIGUREDwhen no default source exists, explicitly set"defaults": { "search_lane": null }inconfig.json. - Defuddle direct fetch and URL routing (
kiki-common-direct@1):direct.fetchnow uses Defuddle 0.19.3 + linkedom for static extraction and supports asynchronous jobs. Built-in URL routing sends known GitHub Raw/API, npm, and PyPI JSON targets strictly todirect.fetch(you can override or disable this throughfetch.routing). - In-progress job fingerprint changes: The
duckduckgo(v2),direct-http, and the newcrawl/researchoperations in thetavilyadapter update operation fingerprints. Before upgrading, wait for in-progress jobs from the old version to finish; persisted old snapshots are not silently rebuilt.
0.4.0: Script provider/Lane
0.4.0 added the script provider/Lane. It can reuse the existing CLI, SDK, and detached asynchronous job entry points without changing the existing API. Historical notes for the 0.2→0.3 upgrade still apply as written.
1. GMA protocol evolution and mode matching
In early development snapshots, the GMA (Grok Multi-Agent) adapter had a different structure from the current version:
- After the GMA adapter upgraded from Version 1 to Version 2, the new adapter could not deserialize old in-progress job snapshots. Before upgrading, make sure long-running old tasks have finished.
- The new version supports an explicit
options.api_mode:chat_completions: The endpoint appends/chat/completions.messages: The endpoint appends/messagesand uses the structured relay contract.
- Endpoint-conflict protection: If the configured Base URL already contains a suffix that does not match the mode (for example, putting Grok's
/responsesin a GMA endpoint), the system reports an error and disables the instance. It does not silently fall back.
2. Grok Responses independence
grok.synthesis and grok.x-synthesis are built on the independent Grok Responses API and call the /v1/responses endpoint directly. They are not interchangeable with the traditional Chat Completions interface. If you migrate an old configuration, credentials that supported only Chat Completions cannot be used automatically for the new Responses operations.
3. Configuration Schema evolution and search-layer migration
The current runtime uses Configuration Schema Version 4 (schema_version: "4").
- If you maintain credentials from an early search layer (such as
SEARCH_LAYER_CREDENTIALSor~/.openclaw/credentials/search.json), use the CLI's explicit import feature (nb-search --import-search-layer --dry-run) to preview a mapping report. After confirming that there are no conflicts, apply it with--apply. This tool is not a general-purpose upgrader for arbitrary old versions; see the CLI migration guide for the exact rules. - Some private environment variables from early versions (such as
NB_SEARCH_GROK_MULTI_AGENT_API_KEY) have been normalized in standard Schema v4. The default GMA slot environment variable is now unified with Grok asNB_SEARCH_GROK_API_KEY.
4. Concurrency control and state recovery
In the execution configuration, max_concurrency (default 8) and max_provider_calls (default 64) control concurrency and call budgets inside one query execution. They are not a global queue shared by multiple independent CLI processes.
- When multiple tasks or processes run and encounter a configuration-write conflict, wait for the preceding write or migration to finish.
- If an abnormal process termination reports unreleased state, do not blindly delete the
jobsartifact directory, backup files, or unknown locks. Follow the CLI diagnostics to confirm configuration and credential consistency before recovering.