Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

Add support for custom HTTP headers in VLM models (OpenAI-compatible) (#723)

KorenKritacd87c0aaa6d0
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 1a60fa894..52a55a91a 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -303,6 +303,7 @@ Vision Language Model for semantic extraction (L0/L1 generation).
| `api_base` | str | API endpoint (optional) |
| `thinking` | bool | Enable thinking mode for VolcEngine models (default: `false`) |
| `max_concurrent` | int | Maximum concurrent semantic LLM calls (default: `100`) |
+| `extra_headers` | object | Custom HTTP headers (for OpenAI-compatible providers, optional) |
**Available Models**
@@ -318,6 +319,30 @@ When resources are added, VLM generates:
If VLM is not configured, L0/L1 will be generated from content directly (less semantic), and multimodal resources may have limited descriptions.
+**Custom HTTP Headers**
+
+For OpenAI-compatible providers (e.g., OpenRouter), you can add custom HTTP headers via `extra_headers`:
+
+```json
+{
+ "vlm": {
+ "provider": "openai",
+ "api_key": "your-api-key",
+ "model": "gpt-4o",
+ "api_base": "https://openrouter.ai/api/v1",
+ "extra_headers": {
+ "HTTP-Referer": "https://your-site.com",
+ "X-Title": "Your App Name"
+ }
+ }
+}
+```
+
+Common use cases:
+- **OpenRouter**: Requires `HTTP-Referer` and `X-Title` to identify your application
+- **Custom proxies**: Add authentication or tracing headers
+- **API gateways**: Add version or routing identifiers
+
### code
Controls how code files are summarized via `code_summary_mode`. Both config formats are equivalent:
@@ -680,7 +705,8 @@ For details on the lock mechanism, see [Path Locks and Crash Recovery](../concep
"model": "string",
"api_base": "string",
"thinking": false,
- "max_concurrent": 100
+ "max_concurrent": 100,
+ "extra_headers": {}
},
"rerank": {
"provider": "volcengine",
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index b0954bbfe..1c83eb85c 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -276,6 +276,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
| `api_base` | str | API 端点(可选) |
| `thinking` | bool | 启用思考模式(仅对部分火山模型生效,默认:`false`) |
| `max_concurrent` | int | 语义处理阶段 LLM 最大并发调用数(默认:`100`) |
+| `extra_headers` | object | 自定义 HTTP 请求头(OpenAI 兼容 provider 可用,可选) |
**可用模型**
@@ -291,6 +292,30 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
如果未配置 VLM,L0/L1 将直接从内容生成(语义性较弱),多模态资源的描述可能有限。
+**自定义 HTTP Headers**
+
+对于 OpenAI 兼容的 provider(如 OpenRouter),可以通过 `extra_headers` 添加自定义 HTTP 请求头:
+
+```json
+{
+ "vlm": {
+ "provider": "openai",
+ "api_key": "your-api-key",
+ "model": "gpt-4o",
+ "api_base": "https://openrouter.ai/api/v1",
+ "extra_headers": {
+ "HTTP-Referer": "https://your-site.com",
+ "X-Title": "Your App Name"
+ }
+ }
+}
+```
+
+常见使用场景:
+- **OpenRouter**: 需要 `HTTP-Referer` 和 `X-Title` 来标识应用
+- **自定义代理**: 添加认证头或追踪头
+- **API 网关**: 添加版本或路由标识
+
### code
通过 `code_summary_mode` 控制代码文件的摘要生成方式。以下两种写法等价:
@@ -655,7 +680,8 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
"model": "string",
"api_base": "string",
"thinking": false,
- "max_concurrent": 100
+ "max_concurrent": 100,
+ "extra_headers": {}
},
"rerank": {
"provider": "volcengine",
diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.py
index 862342b2e..d1f6d05d3 100644
--- a/openviking/models/vlm/backends/openai_vlm.py
+++ b/openviking/models/vlm/backends/openai_vlm.py
@@ -29,7 +29,10 @@ class OpenAIVLM(VLMBase):
import openai
except ImportError:
raise ImportError("Please install openai: pip install openai")
- self._sync_client = openai.OpenAI(api_key=self.api_key, base_url=self.api_base)
+ client_kwargs = {"api_key": self.api_key, "base_url": self.api_base}
+ if self.extra_headers:
+ client_kwargs["default_headers"] = self.extra_headers
+ self._sync_client = openai.OpenAI(**client_kwargs)
return self._sync_client
def get_async_client(self):
@@ -39,7 +42,10 @@ class OpenAIVLM(VLMBase):
import openai
except ImportError:
raise ImportError("Please install openai: pip install openai")
- self._async_client = openai.AsyncOpenAI(api_key=self.api_key, base_url=self.api_base)
+ client_kwargs = {"api_key": self.api_key, "base_url": self.api_base}
+ if self.extra_headers:
+ client_kwargs["default_headers"] = self.extra_headers
+ self._async_client = openai.AsyncOpenAI(**client_kwargs)
return self._async_client
def _update_token_usage_from_response(self, response):
diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.py
index d8641bf84..64c3d5cf8 100644
--- a/openviking/models/vlm/base.py
+++ b/openviking/models/vlm/base.py
@@ -26,6 +26,7 @@ class VLMBase(ABC):
self.temperature = config.get("temperature", 0.0)
self.max_retries = config.get("max_retries", 2)
self.max_tokens = config.get("max_tokens")
+ self.extra_headers = config.get("extra_headers")
# Token usage tracking
self._token_tracker = TokenUsageTracker()
diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.py
index 6c42d6436..0b999ca8b 100644
--- a/openviking_cli/utils/config/vlm_config.py
+++ b/openviking_cli/utils/config/vlm_config.py
@@ -36,6 +36,10 @@ class VLMConfig(BaseModel):
default=100, description="Maximum number of concurrent LLM calls for semantic processing"
)
+ extra_headers: Optional[Dict[str, str]] = Field(
+ default=None, description="Extra HTTP headers for OpenAI-compatible providers"
+ )
+
_vlm_instance: Optional[Any] = None
model_config = {"arbitrary_types_allowed": True, "extra": "forbid"}
@@ -72,6 +76,8 @@ class VLMConfig(BaseModel):
self.providers[self.provider]["api_key"] = self.api_key
if self.api_base and "api_base" not in self.providers[self.provider]:
self.providers[self.provider]["api_base"] = self.api_base
+ if self.extra_headers and "extra_headers" not in self.providers[self.provider]:
+ self.providers[self.provider]["extra_headers"] = self.extra_headers
def _has_any_config(self) -> bool:
"""Check if any config is provided."""
diff --git a/tests/unit/test_extra_headers_vlm.py b/tests/unit/test_extra_headers_vlm.py
new file mode 100644
index 000000000..87b3e8037
--- /dev/null
+++ b/tests/unit/test_extra_headers_vlm.py
@@ -0,0 +1,221 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for VLM extra_headers support."""
+
+from unittest.mock import MagicMock, patch
+
+from openviking.models.vlm.backends.openai_vlm import OpenAIVLM
+
+
+class TestVLMExtraHeaders:
+ """Test extra_headers is passed to OpenAI client."""
+
+ @patch("openviking.models.vlm.backends.openai_vlm.openai.OpenAI")
+ def test_extra_headers_passed_to_sync_client(self, mock_openai_class):
+ """extra_headers should be passed as default_headers to sync OpenAI client."""
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ headers = {"HTTP-Referer": "https://example.com", "X-Title": "My App"}
+ vlm = OpenAIVLM(
+ {
+ "api_key": "sk-test",
+ "api_base": "https://api.openai.com/v1",
+ "extra_headers": headers,
+ }
+ )
+
+ # Trigger client creation
+ _ = vlm.get_client()
+
+ mock_openai_class.assert_called_once()
+ call_kwargs = mock_openai_class.call_args[1]
+ assert call_kwargs.get("default_headers") == headers
+
+ @patch("openviking.models.vlm.backends.openai_vlm.openai.AsyncOpenAI")
+ def test_extra_headers_passed_to_async_client(self, mock_async_openai_class):
+ """extra_headers should be passed as default_headers to async OpenAI client."""
+ mock_client = MagicMock()
+ mock_async_openai_class.return_value = mock_client
+
+ headers = {"HTTP-Referer": "https://example.com", "X-Title": "My App"}
+ vlm = OpenAIVLM(
+ {
+ "api_key": "sk-test",
+ "api_base": "https://api.openai.com/v1",
+ "extra_headers": headers,
+ }
+ )
+
+ # Trigger async client creation
+ _ = vlm.get_async_client()
+
+ mock_async_openai_class.assert_called_once()
+ call_kwargs = mock_async_openai_class.call_args[1]
+ assert call_kwargs.get("default_headers") == headers
+
+ @patch("openviking.models.vlm.backends.openai_vlm.openai.OpenAI")
+ def test_no_extra_headers_omits_default_headers(self, mock_openai_class):
+ """When extra_headers is not provided, default_headers should NOT be set."""
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ vlm = OpenAIVLM(
+ {
+ "api_key": "sk-test",
+ "api_base": "https://api.openai.com/v1",
+ }
+ )
+
+ # Trigger client creation
+ _ = vlm.get_client()
+
+ mock_openai_class.assert_called_once()
+ call_kwargs = mock_openai_class.call_args[1]
+ assert "default_headers" not in call_kwargs
+
+ @patch("openviking.models.vlm.backends.openai_vlm.openai.OpenAI")
+ def test_extra_headers_empty_dict_omits_default_headers(self, mock_openai_class):
+ """When extra_headers is empty dict, default_headers should NOT be set."""
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ vlm = OpenAIVLM(
+ {
+ "api_key": "sk-test",
+ "api_base": "https://api.openai.com/v1",
+ "extra_headers": {},
+ }
+ )
+
+ # Trigger client creation
+ _ = vlm.get_client()
+
+ mock_openai_class.assert_called_once()
+ call_kwargs = mock_openai_class.call_args[1]
+ # Empty dict is falsy, so default_headers should not be set
+ assert "default_headers" not in call_kwargs
+
+
+class TestVLMBaseExtraHeaders:
+ """Test VLMBase extracts extra_headers from config."""
+
+ def test_extra_headers_extracted_from_config(self):
+ """VLMBase should extract extra_headers from config."""
+
+ class StubVLM(OpenAIVLM):
+ def get_completion(self, prompt, thinking=False):
+ return ""
+
+ async def get_completion_async(self, prompt, thinking=False, max_retries=0):
+ return ""
+
+ def get_vision_completion(self, prompt, images, thinking=False):
+ return ""
+
+ async def get_vision_completion_async(self, prompt, images, thinking=False):
+ return ""
+
+ headers = {"X-Custom-Header": "custom-value"}
+ vlm = StubVLM(
+ {
+ "api_key": "sk-test",
+ "extra_headers": headers,
+ }
+ )
+
+ assert vlm.extra_headers == headers
+
+ def test_extra_headers_none_when_not_in_config(self):
+ """VLMBase should set extra_headers to None when not in config."""
+
+ class StubVLM(OpenAIVLM):
+ def get_completion(self, prompt, thinking=False):
+ return ""
+
+ async def get_completion_async(self, prompt, thinking=False, max_retries=0):
+ return ""
+
+ def get_vision_completion(self, prompt, images, thinking=False):
+ return ""
+
+ async def get_vision_completion_async(self, prompt, images, thinking=False):
+ return ""
+
+ vlm = StubVLM(
+ {
+ "api_key": "sk-test",
+ }
+ )
+
+ assert vlm.extra_headers is None
+
+
+class TestVLMConfigExtraHeaders:
+ """Test VLMConfig passes extra_headers to VLM instance."""
+
+ def test_vlm_config_accepts_extra_headers_in_providers(self):
+ """VLMConfig should accept extra_headers in providers config."""
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+
+ config = VLMConfig(
+ model="gpt-4o",
+ provider="openai",
+ providers={
+ "openai": {
+ "api_key": "sk-test",
+ "api_base": "https://api.openai.com/v1",
+ "extra_headers": {"HTTP-Referer": "https://example.com"},
+ }
+ },
+ )
+
+ result = config._build_vlm_config_dict()
+ assert result["extra_headers"] == {"HTTP-Referer": "https://example.com"}
+
+ def test_vlm_config_extra_headers_none_when_not_set(self):
+ """VLMConfig should not include extra_headers when not set."""
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+
+ config = VLMConfig(
+ model="gpt-4o",
+ provider="openai",
+ providers={
+ "openai": {
+ "api_key": "sk-test",
+ "api_base": "https://api.openai.com/v1",
+ }
+ },
+ )
+
+ result = config._build_vlm_config_dict()
+ assert result.get("extra_headers") is None
+
+ def test_vlm_config_accepts_flat_extra_headers(self):
+ """VLMConfig should accept extra_headers as flat config field (legacy style)."""
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+
+ config = VLMConfig(
+ model="gpt-4o",
+ provider="openai",
+ api_key="sk-test",
+ api_base="https://openrouter.ai/api/v1",
+ extra_headers={"HTTP-Referer": "https://example.com", "X-Title": "My App"},
+ )
+
+ # Verify flat extra_headers is stored
+ assert config.extra_headers == {"HTTP-Referer": "https://example.com", "X-Title": "My App"}
+
+ # Verify it's migrated to providers structure
+ config._migrate_legacy_config()
+ assert config.providers["openai"]["extra_headers"] == {
+ "HTTP-Referer": "https://example.com",
+ "X-Title": "My App",
+ }
+
+ # Verify _build_vlm_config_dict includes it
+ result = config._build_vlm_config_dict()
+ assert result["extra_headers"] == {
+ "HTTP-Referer": "https://example.com",
+ "X-Title": "My App",
+ }