Search Setup

Contents

Overview

flowchart TD
  START["runSearchSetupFlow()"]
  DISCOVER["resolveSearchProviderOptions()"]
  CONTRIBS["resolveSearchProviderSetupContributions()"]
  BUNDLED["Bundled providers"]
  RUNTIME["Runtime plugin providers"]
  MERGE["Merge & sort by label"]
  PROMPT["Show provider selection prompt"]
  HASKEY{"hasExistingKey()?"}
  ENVKEY{"hasKeyInEnv()?"}
  ASKKEY["Prompt for API key"]
  USEENV["Use environment key"]
  USEEXIST["Use existing key"]
  APPLY["applySearchKey()"]
  SELECT["applySearchProviderSelection()"]
  CONFIG["Updated OpenClawConfig"]

  START --> DISCOVER
  DISCOVER --> CONTRIBS
  CONTRIBS --> BUNDLED
  CONTRIBS --> RUNTIME
  BUNDLED --> MERGE
  RUNTIME --> MERGE
  MERGE --> PROMPT
  PROMPT --> HASKEY
  HASKEY -->|Yes| USEEXIST
  HASKEY -->|No| ENVKEY
  ENVKEY -->|Yes| USEENV
  ENVKEY -->|No| ASKKEY
  USEEXIST --> APPLY
  USEENV --> APPLY
  ASKKEY --> APPLY
  APPLY --> SELECT
  SELECT --> CONFIG

The diagram shows the complete search setup pipeline. Provider discovery merges bundled and runtime contributions, the wizard prompts for selection, credential resolution checks existing keys and environment variables before falling back to manual input, and the final step applies both the provider selection and key to produce an updated config.

Core Types

The search setup module defines several types that bridge the generic flow system with search-specific configuration. SearchProvider is a deeply-nested type extraction from the config schema, while SearchProviderSetupContribution extends the generic FlowContribution with search-specific metadata.

// src/flows/search-setup.ts — Core type definitions
export type SearchProvider = NonNullable<
  NonNullable<
    NonNullable<
      NonNullable<OpenClawConfig["tools"]>["web"]
    >["search"]
  >["provider"]
>;

type SearchConfig = NonNullable<
  NonNullable<
    NonNullable<OpenClawConfig["tools"]>["web"]
  >["search"]
>;

type MutableSearchConfig = SearchConfig & Record<string, unknown>;

The SearchProvider type uses a chain of NonNullable unwrapping to drill through the optional config nesting and extract the literal union of valid provider names. MutableSearchConfig extends the readonly config with an index signature so that provider-specific credential setters can write arbitrary keys.

// src/flows/search-setup.ts — Contribution types
export type SearchProviderSetupOption = FlowOption & {
  value: SearchProvider;
};

export type SearchProviderSetupContribution = FlowContribution & {
  kind: "search";
  surface: "setup";
  provider: PluginWebSearchProviderEntry;
  option: SearchProviderSetupOption;
  source: "bundled" | "runtime";
};

Decision Points

How It Works

Search setup operates in four distinct phases: provider discovery, selection flow, credential application, and docs search integration. Each phase is intentionally decoupled so that provider discovery can be reused by other setup flows.

Phase 1 — Provider Discovery

The resolveSearchProviderOptions function is the public entry point for discovering available providers. It delegates to resolveSearchProviderSetupContributions, which merges bundled providers shipped with OpenClaw and runtime providers registered by plugins, then sorts the merged list alphabetically by label.

// src/flows/search-setup.ts — Provider discovery
export function resolveSearchProviderOptions(
  config?: OpenClawConfig,
): readonly PluginWebSearchProviderEntry[] {
  return resolveSearchProviderSetupContributions(config)
    .map((contribution) => contribution.provider);
}

export function resolveSearchProviderSetupContributions(
  config?: OpenClawConfig,
): SearchProviderSetupContribution[] {
  // 1. Collect bundled providers (source: "bundled")
  // 2. Collect runtime plugin providers (source: "runtime")
  // 3. Merge into a single array
  // 4. Sort by contribution.option.label for stable UI ordering
  // Returns: SearchProviderSetupContribution[]
}

Phase 2 — Selection Flow

The runSearchSetupFlow orchestrates the full interactive wizard. It resolves available providers, renders a selection prompt via WizardPrompter, checks for existing credentials, and applies the result.

sequenceDiagram
    participant User
    participant Wizard as runSearchSetupFlow
    participant Resolver as resolveSearchProviderOptions
    participant Prompter as WizardPrompter
    participant KeyCheck as hasExistingKey / hasKeyInEnv
    participant Apply as applySearchKey
    participant Config as OpenClawConfig

    User->>Wizard: Initiate search setup
    Wizard->>Resolver: resolveSearchProviderOptions(config)
    Resolver-->>Wizard: PluginWebSearchProviderEntry[]
    Wizard->>Prompter: Show provider selection list
    Prompter-->>Wizard: Selected SearchProvider
    Wizard->>KeyCheck: hasExistingKey(config, provider)?
    KeyCheck-->>Wizard: false
    Wizard->>KeyCheck: hasKeyInEnv(runtime, provider)?
    KeyCheck-->>Wizard: false
    Wizard->>Prompter: Prompt for API key
    Prompter-->>Wizard: SecretInput (API key)
    Wizard->>Apply: applySearchKey(config, provider, key)
    Apply->>Config: Spread new search config
    Apply->>Config: Set provider + enabled: true
    Apply->>Config: Write credential value
    Config-->>Wizard: Updated OpenClawConfig
    Wizard-->>User: Setup complete

// src/flows/search-setup.ts — Main setup flow
export async function runSearchSetupFlow(
  config: OpenClawConfig,
  runtime: RuntimeEnv,
  prompter: WizardPrompter,
  opts?: SetupSearchOptions,
): Promise<OpenClawConfig> {
  // 1. Resolve available providers
  const providers = resolveSearchProviderOptions(config);

  // 2. Show provider selection prompt
  const selected = await prompter.select({
    message: "Choose a search provider",
    options: providers.map(p => ({ label: p.label, value: p.id })),
  });

  // 3. Handle credential input
  //    - Check hasExistingKey() first
  //    - Then hasKeyInEnv() for env-injected keys
  //    - Fall back to interactive prompt

  // 4. Apply selection + key to config
  return applySearchKey(config, selected, key);
}

Phase 3 — Credential Application

The applySearchKey function is the core of credential persistence. It performs an immutable config update using object spreads, handles the two-phase credential write pattern, and applies provider-specific selection config.

// src/flows/search-setup.ts — applySearchKey
export function applySearchKey(
  config: OpenClawConfig,
  provider: SearchProvider,
  key: SecretInput,
): OpenClawConfig {
  const providerEntry = resolveSearchProviderEntry(config, provider);
  if (!providerEntry) return config;

  const search: MutableSearchConfig = {
    ...config.tools?.web?.search,
    provider,
    enabled: true,
  };

  if (!providerEntry.setConfiguredCredentialValue) {
    providerEntry.setCredentialValue(search, key);
  }

  const nextBase: OpenClawConfig = {
    ...config,
    tools: {
      ...config.tools,
      web: { ...config.tools?.web, search },
    },
  };
  const next = applySearchProviderSelectionConfig(
    nextBase, providerEntry,
  );

  providerEntry.setConfiguredCredentialValue?.(next, key);
  return next;
}

Provider Selection Without Credentials

The applySearchProviderSelection function handles the case where only the provider choice changes but no new credential is provided. This is used when switching between providers that share a credential or when re-selecting the current provider.

// src/flows/search-setup.ts
export function applySearchProviderSelection(
  config: OpenClawConfig,
  provider: SearchProvider,
): OpenClawConfig
// Applies provider selection + provider-specific config
// without touching credentials. Used by the /model command
// when changing search providers via a shortcut.

Phase 4 — Docs Search Integration

The docsSearchCommand in src/commands/docs.ts uses the configured search provider to perform documentation searches via the MCP tool interface. It joins query parts, invokes the mcporter tool with the configured search tool, and applies a timeout.

// src/commands/docs.ts — docsSearchCommand
export async function docsSearchCommand(
  queryParts: string[],
  runtime: RuntimeEnv,
) {
  const query = queryParts.join(" ").trim();
  const res = await runTool(
    "mcporter",
    ["call", SEARCH_TOOL, "--args", payload, "--output", "text"],
    { timeoutMs: SEARCH_TIMEOUT_MS },
  );
}

// src/commands/onboard-search.ts — re-exports
export {
  SEARCH_PROVIDER_OPTIONS,
  applySearchKey,
  applySearchProviderSelection,
  hasExistingKey,
  hasKeyInEnv,
  resolveExistingKey,
  resolveSearchProviderOptions,
  runSearchSetupFlow as setupSearch,
} from "../flows/search-setup.js";

Edge Cases

Configuration

Related Topics

Source Files

src/
├── flows/
│   └── search-setup.ts          ← Core types, discovery, applySearchKey, runSearchSetupFlow
├── commands/
│   ├── docs.ts                  ← docsSearchCommand() MCP tool invocation
│   └── onboard-search.ts        ← Re-exports for onboarding wizard
└── plugins/
    └── web-search-providers/    ← Bundled provider entries (Tavily, Brave, etc.)