Relevant source files

The following files were used as context for generating this wiki page: - [src/agents/system-prompt.ts](https://github.com/mrge-io/openclaw/blob/main/src/agents/system-prompt.ts) - [src/agents/system-prompt.test.ts](https://github.com/mrge-io/openclaw/blob/main/src/agents/system-prompt.test.ts) - [appcast.xml](https://github.com/mrge-io/openclaw/blob/main/appcast.xml) - [CLAUDE.md](https://github.com/mrge-io/openclaw/blob/main/CLAUDE.md) - [AGENTS.md](https://github.com/mrge-io/openclaw/blob/main/AGENTS.md) - [extensions/mattermost/src/mattermost/client.ts](https://github.com/mrge-io/openclaw/blob/main/extensions/mattermost/src/mattermost/client.ts)

# LLM Providers Integration The LLM Providers Integration in OpenClaw establishes a modular architecture for connecting autonomous agents with various Large Language Model (LLM) backends. This system manages the lifecycle of model requests, including authentication, configuration of model-specific parameters (such as reasoning levels), and the injection of context-aware system prompts that define agent behavior and safety guardrails. The integration supports a diverse catalog of providers, ranging from industry standards like OpenAI and Google to specialized or synthetic models like Kimi and MiniMax. It serves as the bridge between the high-level agent logic and the underlying inference APIs, ensuring that agents operate within a consistent execution environment regardless of the specific provider used. ## Architecture and Provider Management OpenClaw employs a provider-agnostic core that interacts with external LLMs through a structured configuration and messaging pipeline. The system tracks provider capabilities—such as inline button support or image analysis—and adjusts the agent's available toolset accordingly. ### Synthetic Model Catalog and Multi-Model Support The project maintains a synthetic model catalog that aggregates various providers into a unified interface. Recent updates have integrated models such as Kimi K2.5 and MiniMax, often utilizing OAuth for secure authentication. ```mermaid graph TD subgraph Core_Agent_Logic SA[System Prompt Builder] --> RT[Runtime Configuration] end subgraph Provider_Interface RT --> PM[Provider Manager] PM --> OA[OpenAI/Compatible] PM --> GO[Google] PM --> KM[Kimi K2.5] PM --> MX[MiniMax] end OA --> API[External Inference APIs] GO --> API KM --> API MX --> API ``` *The diagram shows the flow from high-level system prompt construction to the specific provider implementations that call external APIs.* Sources: [appcast.xml:13-17](), [src/agents/system-prompt.ts:400-420]() ### Provider Configuration and Failover Configuration is handled through environment variables (e.g., `OPENAI_TTS_BASE_URL`) and local configuration files. The system includes failover mechanisms to skip "cooldowned" providers during model execution to ensure high availability. | Component | Description | | :--- | :--- | | **Model Aliases** | Allows the use of short names (e.g., "Opus") to refer to specific provider strings (e.g., "anthropic/claude-opus-4-5"). | | **Reasoning Levels** | Configurable settings (off, stream, on) that control how the model's internal chain-of-thought is processed and displayed. | | **Failover Logic** | Mechanism to automatically attempt alternative models or providers if the primary target fails or is cooldowned. | Sources: [src/agents/system-prompt.ts:445-448](), [appcast.xml:175-177](), [CLAUDE.md:144-146]() ## System Prompt Construction The integration relies heavily on dynamic system prompts to orient the LLM. These prompts are built based on the current "Runtime" environment, which includes details about the host OS, node version, and specific model capabilities. ### Prompt Sections and Logic The prompt builder conditionally includes sections based on the `PromptMode` (full, minimal, or none). This ensures that sub-agents receive only the context necessary for their specific tasks, optimizing the context window. ```mermaid flowchart TD Start[Build System Prompt] --> Mode{Prompt Mode?} Mode -- Full --> Sections[Safety + Skills + Memory + Identity + Tools] Mode -- Minimal --> SectionsMin[Safety + Tools + Workspace] Mode -- None --> IdentityOnly[Basic Assistant Identity] Sections --> Context[Inject Project Context Files] SectionsMin --> Context Context --> Runtime[Append Runtime Line] Runtime --> End[Final Prompt] ``` *Logic flow for constructing environment-aware system prompts.* Key logic components in prompt construction: * **Tool Filtering**: Tools are listed in the prompt only if they are permitted by the current security policy and available in the runtime. * **Runtime Line**: A single line summarizing the environment (e.g., `Runtime: agent=work | host=macOS | model=anthropic/claude`). * **Safety Guardrails**: Hardcoded sections inspired by constitutional AI to prevent manipulation and ensure human oversight. Sources: [src/agents/system-prompt.ts:13-25](), [src/agents/system-prompt.ts:182-205](), [src/agents/system-prompt.ts:454-470]() ## Provider Capabilities and Specialized Tools LLM integration is not limited to text; it encompasses specialized tools for media, reasoning, and voice. ### Reasoning and Formatting Certain models support explicit reasoning tags. The integration forces internal reasoning into `` blocks and final output into `` blocks when `reasoningTagHint` is enabled. ```typescript // Example of forced reasoning format for specific models const reasoningHint = [ "ALL internal reasoning MUST be inside ....", "Format every reply as ... then ..., with no other text.", "Only text inside is shown to the user." ].join(" "); ``` Sources: [src/agents/system-prompt.ts:223-231]() ### Tool-Provider Synergy The availability of certain tools depends on the provider's capabilities. For instance, the `image` tool for analyzing visual data is only active if the underlying model supports vision. | Tool | Provider Requirement | Functionality | | :--- | :--- | :--- | | `image` | Vision-capable model | Analyzes images with the configured image model. | | `message` | Channel Integration | Sends proactive messages and channel actions (polls, reactions). | | `web_search` | Search API Key | Performs web searches via Brave API. | | `cron` | Scheduler Support | Manages wake events and reminders. | Sources: [src/agents/system-prompt.ts:153-176](), [appcast.xml:80-84]() ## Authentication and External API Clients OpenClaw implements custom clients for providers and messaging platforms that follow the LLM-driven flow. For example, the Mattermost and Discord integrations use specialized request handlers to bridge the gap between LLM actions and API execution. ### Mattermost Client Implementation The Mattermost client demonstrates how the system handles base URL normalization and token-based authentication for provider-adjacent services. ```mermaid sequenceDiagram participant LLM as Agent/LLM participant Client as MattermostClient participant API as Mattermost API LLM->>Client: createMattermostPost(params) Client->>Client: buildMattermostApiUrl() Client->>API: POST /api/v4/posts (Auth: Bearer token) API-->>Client: MattermostPost JSON Client-->>LLM: Normalized Response ``` *Sequence of an agent interacting with a messaging provider API.* Sources: [extensions/mattermost/src/mattermost/client.ts:60-84](), [extensions/mattermost/src/mattermost/client.ts:133-150]() ## Summary The LLM Providers Integration in OpenClaw provides a robust framework for multi-model orchestration. By decoupling the agent's core identity from specific inference backends, the system allows for dynamic switching and failover between providers like OpenAI, Google, and Kimi. The use of structured system prompts and runtime-aware capability filtering ensures that agents remain safe, functional, and efficient across diverse execution environments.