AIClaw Adds Configurable Web Search Without Hiding Execution Details

Most AI agent products say they can "search the web," but they often collapse several very different behaviors into one checkbox.

In the current AIClaw repository, web search is modeled more explicitly:

• some models can use built-in provider-side search
• other agents can call an external web_search tool through a configured search engine
• both paths are visible in runtime behavior instead of being hidden behind vague magic

That separation matters if you run agents in production and want control over cost, provider choice, prompts, and auditability.

What changed in AIClaw

Recent AIClaw changes added a full search engine configuration surface and the agent-side wiring needed to use it:

• a new Search Engine page in the web console
• persisted search engine configs in the backend
• external search support for Tavily, SerpAPI, and Aliyun IQS
• agent settings for builtin versus external web search mode
• runtime handling that enables model-native search only when that mode is selected
• a follow-up UI fix that turns web search on automatically when an external engine is chosen

This is not just a README claim. The repository now includes:

• internal/handler/search_engine.go for CRUD and test endpoints
• internal/tools/websearch/search.go for provider-specific search execution
• web/src/views/search-engine/Index.vue for the console UI
• web/src/views/agent/Form.vue for per-agent mode and engine selection
• tests covering built-in and external search behavior

Why two search modes are better than one

AIClaw now documents two distinct modes in README.md:

• built-in mode: AIClaw sets extra_body: {"enable_search": true} for models that support provider-native search
• external mode: AIClaw exposes a web_search tool and routes calls through a saved search engine config

That design solves a real operational problem.

Built-in model search is convenient when the provider already supports it well. In AIClaw, the prompt layer explicitly tells the model that recent and time-sensitive questions can use built-in search. The runtime also records a web_search execution step that shows the request configuration used for that model call.

External search is different. Sometimes you do not want your search behavior tied to one model vendor. Sometimes you want to standardize on a search provider across multiple model backends. Sometimes you want to rotate providers, test them independently, or keep search visible as a normal tool call with structured input and output.

AIClaw supports that split instead of forcing one compromise.

How the flow works

The user workflow is straightforward:

1. Open the Search Engine page in the AIClaw admin console.
2. Create one or more search configs.
3. Pick the provider: Tavily, SerpAPI, or Aliyun IQS.
4. Save the API key and optional base URL.
5. Test the config before using it live.
6. Open an agent.
7. Enable web search.
8. Choose external mode if you want tool-based search.
9. Select one enabled search engine for that agent.

On the backend, AIClaw validates that external mode is only accepted when a real enabled search engine is selected. That check lives in validateExternalWebSearch inside internal/handler/agent.go.

The frontend follow-up fix is also important. In web/src/views/agent/Form.vue, selecting external mode now auto-selects the first enabled engine when possible, and selecting an engine automatically enables web search. That sounds small, but it removes a common configuration footgun: "I picked an engine, why is search still off?"

Provider behavior is implemented, not hand-waved

AIClaw does not treat external search as a generic proxy blob. The repository includes explicit provider logic:

• Tavily uses https://api.tavily.com/search
• SerpAPI uses https://serpapi.com/search.json
• Aliyun IQS uses https://cloud-iqs.aliyuncs.com/search/unified

The tool normalizes limits, validates config state, trims oversized snippets, and returns structured results with title, URL, and snippet fields.

That means the agent can use web results in a predictable format regardless of provider, while operators still choose the engine that fits their environment.

The observability part is the real strength

My favorite part is that AIClaw keeps search behavior observable.

For built-in search, the runtime records that model-native search was enabled and stores the request configuration in a web_search step.

For external search, the agent uses the regular web_search tool path, so tool input, output, duration, and errors stay visible in chat progress and execution logs.

This fits the broader AIClaw design direction: runtime plan state, generated files, execution steps, memory, and now search behavior are treated as first-class runtime objects instead of hidden implementation details.

If you are operating agents for real work, that is a better tradeoff than a black-box "browse the web" toggle.

A practical example

Imagine two agents:

• a news-monitoring agent using a model with strong built-in search support
• a research or compliance agent that must use a specific external search provider

In AIClaw, those do not need the same search path.

The first agent can stay in built-in mode for a tighter provider-integrated experience.

The second agent can switch to external mode, bind to a chosen engine, and keep the search action visible as a tool call with inspectable results.

That is a more production-friendly model than pretending every search use case is identical.

Why this feature stood out

I picked this topic because it is a concrete feature with recent implementation depth across backend, runtime, tests, and UI:

• feature commit: configurable search engines
• follow-up fix: external search becomes active as soon as an engine is selected
• documented behavior in the README
• explicit tests for built-in versus external execution

That combination makes it a good example of how AIClaw is evolving: not just adding another capability, but making the capability configurable and inspectable.

AIClaw is open source and self-hosted, so these details matter. When you control the stack, you also need to control how the agent reaches the outside world.