feat(settings): add configurable app identity headers (#132)

* Add configurable app identity headers

* Apply suggestion from @frostming

* Apply suggestion from @frostming

---------

Co-authored-by: Frost Ming <mianghong@gmail.com>

Author: hanxuanliang

README.md

@@ -103,15 +103,16 @@ Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-sk
 
 ## Configuration
 
-| Variable                    | Default                            | Description                                     |
-| --------------------------- | ---------------------------------- | ----------------------------------------------- |
-| `BUB_MODEL`                 | `openrouter:qwen/qwen3-coder-next` | Model identifier                                |
-| `BUB_API_KEY`               | —                                  | Provider key (optional with `bub login openai`) |
-| `BUB_API_BASE`              | —                                  | Custom provider endpoint                        |
-| `BUB_API_FORMAT`            | `completion`                       | `completion`, `responses`, or `messages`        |
-| `BUB_MAX_STEPS`             | `50`                               | Max tool-use loop iterations                    |
-| `BUB_MAX_TOKENS`            | `1024`                             | Max tokens per model call                       |
-| `BUB_MODEL_TIMEOUT_SECONDS` | —                                  | Model call timeout (seconds)                    |
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BUB_MODEL` | `openrouter:qwen/qwen3-coder-next` | Model identifier |
+| `BUB_API_KEY` | — | Provider key (optional with `bub login openai`) |
+| `BUB_API_BASE` | — | Custom provider endpoint |
+| `BUB_API_FORMAT` | `completion` | `completion`, `responses`, or `messages` |
+| `BUB_CLIENT_ARGS` | `{"extra_headers":{"HTTP-Referer":"https://bub.build/","X-Title":"Bub"}}` | JSON object forwarded to the underlying model client |
+| `BUB_MAX_STEPS` | `50` | Max tool-use loop iterations |
+| `BUB_MAX_TOKENS` | `1024` | Max tokens per model call |
+| `BUB_MODEL_TIMEOUT_SECONDS` | — | Model call timeout (seconds) |
 
 ## Background
 

env.example

@@ -31,6 +31,11 @@
 # - messages: chat-completions-style messages API
 # BUB_API_FORMAT=completion
 
+# Optional JSON object forwarded to the underlying model client.
+# Default in code includes Bub attribution headers for compatible providers.
+# Set to `null` to disable, or provide your own JSON object.
+# BUB_CLIENT_ARGS={"extra_headers":{"HTTP-Referer":"https://bub.build/","X-Title":"Bub"}}
+
 # ---------------------------------------------------------------------------
 # Channel manager
 # ---------------------------------------------------------------------------
@@ -55,3 +60,4 @@
 # ---------------------------------------------------------------------------
 # BUB_MODEL=openrouter:qwen/qwen3-coder-next
 # BUB_API_KEY=sk-or-...
+# BUB_CLIENT_ARGS={"extra_headers":{"HTTP-Referer":"https://openclaw.ai","X-Title":"OpenClaw"}}

src/bub/builtin/agent.py

@@ -28,7 +28,6 @@
 from bub.utils import workspace_from_state
 
 CONTINUE_PROMPT = "Continue the task."
-DEFAULT_BUB_HEADERS = {"HTTP-Referer": "https://bub.build/", "X-Title": "Bub"}
 HINT_RE = re.compile(r"\$([A-Za-z0-9_.-]+)")
 
 
@@ -222,7 +221,6 @@ async def _run_tools_once(
         allowed_tools: Collection[str] | None = None,
         allowed_skills: Collection[str] | None = None,
     ) -> ToolAutoResult:
-        extra_options = {"extra_headers": DEFAULT_BUB_HEADERS} if self.settings.model.startswith("openrouter:") else {}
         prompt_text = prompt if isinstance(prompt, str) else _extract_text_from_parts(prompt)
         if allowed_tools is not None:
             allowed_tools = {name.casefold() for name in allowed_tools}
@@ -240,7 +238,6 @@ async def _run_tools_once(
                 max_tokens=self.settings.max_tokens,
                 tools=model_tools(tools),
                 model=model,
-                **extra_options,
             )
 
     def _system_prompt(self, prompt: str, state: State, allowed_skills: set[str] | None = None) -> str:
@@ -284,6 +281,7 @@ def _build_llm(settings: AgentSettings, tape_store: AsyncTapeStore, tape_context
         fallback_models=settings.fallback_models,
         api_key_resolver=openai_codex_oauth_resolver(),
         tape_store=tape_store,
+        client_args=settings.client_args,
         api_format=settings.api_format,
         context=tape_context,
         verbose=settings.verbose,

src/bub/builtin/settings.py

@@ -5,7 +5,7 @@
 import re
 from collections.abc import Callable
 from functools import lru_cache
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import Field
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, YamlConfigSettingsSource
@@ -32,6 +32,10 @@ def default_factory() -> dict[str, str] | None:
     return default_factory
 
 
+def default_client_args() -> dict[str, Any]:
+    return {"extra_headers": {"HTTP-Referer": "https://bub.build/", "X-Title": "Bub"}}
+
+
 class AgentSettings(BaseSettings):
     """Configuration settings for the Agent."""
 
@@ -45,6 +49,7 @@ class AgentSettings(BaseSettings):
     max_steps: int = 50
     max_tokens: int = DEFAULT_MAX_TOKENS
     model_timeout_seconds: int | None = None
+    client_args: dict[str, Any] | None = Field(default_factory=default_client_args)
     verbose: int = Field(default=0, description="Verbosity level for logging. Higher means more verbose.", ge=0, le=2)
 
     @classmethod

tests/test_builtin_agent.py

@@ -26,14 +26,22 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     monkeypatch.setattr(agent_module, "LLM", FakeLLM)
     monkeypatch.setattr(openai_codex, "openai_codex_oauth_resolver", lambda: resolver)
 
-    settings = AgentSettings(model="openai:gpt-5-codex", api_key=None, api_base=None)
+    settings = AgentSettings(
+        model="openai:gpt-5-codex",
+        api_key=None,
+        api_base=None,
+        client_args={"extra_headers": {"HTTP-Referer": "https://openclaw.ai", "X-Title": "OpenClaw"}},
+    )
     tape_store = object()
 
     agent_module._build_llm(settings, tape_store, "ctx")
 
     assert captured["args"] == ("openai:gpt-5-codex",)
     assert captured["kwargs"]["api_key"] is None
     assert captured["kwargs"]["api_base"] is None
+    assert captured["kwargs"]["client_args"] == {
+        "extra_headers": {"HTTP-Referer": "https://openclaw.ai", "X-Title": "OpenClaw"},
+    }
     assert captured["kwargs"]["api_key_resolver"] is resolver
     assert captured["kwargs"]["tape_store"] is tape_store
     assert captured["kwargs"]["context"] == "ctx"

tests/test_settings.py

@@ -42,6 +42,7 @@ def test_settings_no_keys_returns_none() -> None:
 
     assert settings.api_key is None
     assert settings.api_base is None
+    assert settings.client_args == {"extra_headers": {"HTTP-Referer": "https://bub.build/", "X-Title": "Bub"}}
 
 
 def test_settings_provider_names_are_lowercased() -> None:
@@ -74,6 +75,10 @@ def test_settings_load_values_from_yaml(tmp_path: Path) -> None:
   openai: sk-yaml
 api_base:
   openai: https://api.openai.com
+client_args:
+  extra_headers:
+    HTTP-Referer: https://openclaw.ai
+    X-Title: OpenClaw
 """.strip(),
     )
 
@@ -85,6 +90,9 @@ def test_settings_load_values_from_yaml(tmp_path: Path) -> None:
     assert settings.max_steps == 77
     assert settings.api_key == {"openai": "sk-yaml"}
     assert settings.api_base == {"openai": "https://api.openai.com"}
+    assert settings.client_args == {
+        "extra_headers": {"HTTP-Referer": "https://openclaw.ai", "X-Title": "OpenClaw"},
+    }
 
 
 def test_env_settings_override_yaml(tmp_path: Path) -> None:
@@ -94,6 +102,10 @@ def test_env_settings_override_yaml(tmp_path: Path) -> None:
 model: openai:gpt-5
 api_key: sk-yaml
 max_steps: 77
+client_args:
+  extra_headers:
+    HTTP-Referer: https://yaml.example
+    X-Title: YAML App
 """.strip(),
     )
 
@@ -103,6 +115,7 @@ def test_env_settings_override_yaml(tmp_path: Path) -> None:
             "BUB_HOME": str(tmp_path),
             "BUB_MODEL": "anthropic:claude-3-7-sonnet",
             "BUB_API_KEY": "sk-env",
+            "BUB_CLIENT_ARGS": '{"extra_headers":{"HTTP-Referer":"https://env.example","X-Title":"Env App"}}',
             "BUB_MAX_STEPS": "12",
         },
         clear=True,
@@ -112,6 +125,15 @@ def test_env_settings_override_yaml(tmp_path: Path) -> None:
     assert settings.model == "anthropic:claude-3-7-sonnet"
     assert settings.api_key == "sk-env"
     assert settings.max_steps == 12
+    assert settings.client_args == {
+        "extra_headers": {"HTTP-Referer": "https://env.example", "X-Title": "Env App"},
+    }
+
+
+def test_settings_client_args_can_be_disabled() -> None:
+    settings = _settings_with_env({"BUB_CLIENT_ARGS": "null"})
+
+    assert settings.client_args is None
 
 
 def test_load_settings_reads_yaml_from_bub_home(tmp_path: Path) -> None: