Skip to content

Agent Zero AI framework

Preserve configured API-key pools when saving settings

Alessandro255ff63bff72
diff --git a/AGENTS.md b/AGENTS.md
index 0f10a19c0..747eaa2ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,7 +19,7 @@
- Prepared local Responses input may project intact native history through `helpers/responses_history.py`; retain original Chat/fallback messages, current protocol/extras, summaries and masking. Durable capability metadata stores only a stable-prefix digest for eligibility.
- Native function calls use canonical call content for history and repeat comparison, even when accompanied by commentary. The canonical content passes through the normal history template/masking hook; provider output metadata remains intact.
- `initialize.py` owns framework initialization.
-- `models.py` owns model-provider configuration and LiteLLM integration.
+- `models.py` owns model-provider configuration and LiteLLM integration. `get_api_key_raw()` reads the stored key or key list for settings/editing; `get_api_key()` selects a runtime key and runs provider extension hooks.
- `requirements.txt` includes HTTPX's SOCKS extra so framework clients support SOCKS proxy environment variables before plugin setup.
- Native agent-turn response callbacks may receive a display-only commentary preview as their full text; legacy callbacks, accumulated model output, usage and native dispatch retain the original text and result metadata.
- `run_ui.py` is the WebUI entry point.
diff --git a/helpers/settings.py b/helpers/settings.py
index 5539e39ae..9d104ef4d 100644
--- a/helpers/settings.py
+++ b/helpers/settings.py
@@ -323,7 +323,7 @@ def convert_out(settings: Settings) -> SettingsOutput:
providers = get_providers("chat") + get_providers("embedding")
for provider in providers:
provider_name = provider["value"]
- api_key = settings["api_keys"].get(provider_name, models.get_api_key(provider_name))
+ api_key = settings["api_keys"].get(provider_name, models.get_api_key_raw(provider_name))
settings["api_keys"][provider_name] = API_KEY_PLACEHOLDER if api_key and api_key != "None" else ""
# load auth from dotenv
@@ -359,7 +359,7 @@ def convert_out(settings: Settings) -> SettingsOutput:
return out
def _get_api_key_field(settings: Settings, provider: str, title: str) -> SettingsField:
- key = settings["api_keys"].get(provider, models.get_api_key(provider))
+ key = settings["api_keys"].get(provider, models.get_api_key_raw(provider))
# For API keys, use simple asterisk placeholder for existing keys
return {
"id": f"api_key_{provider}",
@@ -509,7 +509,7 @@ def _load_sensitive_settings(settings: Settings):
providers = get_providers("chat") + get_providers("embedding")
for provider in providers:
provider_name = provider["value"]
- api_key = settings["api_keys"].get(provider_name) or models.get_api_key(provider_name)
+ api_key = settings["api_keys"].get(provider_name) or models.get_api_key_raw(provider_name)
if api_key and api_key != "None":
settings["api_keys"][provider_name] = api_key
diff --git a/helpers/settings.py.dox.md b/helpers/settings.py.dox.md
index 0429f5748..13ef2c9fb 100644
--- a/helpers/settings.py.dox.md
+++ b/helpers/settings.py.dox.md
@@ -55,6 +55,7 @@
## Runtime Contracts
+- Settings reads use `models.get_api_key_raw()` to preserve complete key lists without advancing runtime rotation or persisting keys synthesized by runtime hooks. Masking, authentication reloads, and intentional clearing retain their existing behavior.
- `ui_control_visibility` accepts dynamic `canvas:<surface-id>` entries as well as built-in controls, normalizes device values to booleans (default shown), and preserves choices for temporarily unavailable plugins.
- `file_browser_max_text_size_mb` persists the instance-wide text-editing limit, default 10 MiB and normalized to 1–100. FileBrowser reads it directly so its scoped settings API can update it without restarting or reinitializing agents.
@@ -100,6 +101,7 @@
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_settings_cache.py`
+ - `tests/test_settings_api_keys.py`
- `tests/test_settings_mcp.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_document_query_plugin.py`
diff --git a/models.py b/models.py
index 2ed41dd5c..7fe095495 100644
--- a/models.py
+++ b/models.py
@@ -272,15 +272,19 @@ rate_limiters: dict[str, RateLimiter] = {}
api_keys_round_robin: dict[str, int] = {}
-@extensible
-def get_api_key(service: str) -> str:
- # get api key for the service
- key = (
+def get_api_key_raw(service: str) -> str:
+ """Read the stored value, including any comma-separated keys."""
+ return (
dotenv.get_dotenv_value(f"API_KEY_{service.upper()}")
or dotenv.get_dotenv_value(f"{service.upper()}_API_KEY")
or dotenv.get_dotenv_value(f"{service.upper()}_API_TOKEN")
or "None"
)
+
+
+@extensible
+def get_api_key(service: str) -> str:
+ key = get_api_key_raw(service)
# if the key contains a comma, use round-robin
if "," in key:
api_keys = [k.strip() for k in key.split(",") if k.strip()]
diff --git a/plugins/_model_config/AGENTS.md b/plugins/_model_config/AGENTS.md
index a85809cc6..02b695ce0 100644
--- a/plugins/_model_config/AGENTS.md
+++ b/plugins/_model_config/AGENTS.md
@@ -14,6 +14,7 @@
## Local Contracts
+- API-key reveal returns the complete stored key list without advancing rotation, so editing a provider preserves every configured key.
- `Default` is the first global preset and cannot be deleted or renamed. It owns the complete main, utility, and embedding baseline; its Vision Model slot is optional.
- Preset definitions are global. Global, project, agent-profile, and project/profile plugin configs persist only `model_preset`; chats may persist a preset reference as their explicit override.
- Preserve scoped plugin resolution order and fall back invalid or missing scope/chat references to `Default`.
diff --git a/plugins/_model_config/api/api_keys.py b/plugins/_model_config/api/api_keys.py
index 0fe7410bd..9d6582164 100644
--- a/plugins/_model_config/api/api_keys.py
+++ b/plugins/_model_config/api/api_keys.py
@@ -54,7 +54,7 @@ class ApiKeys(ApiHandler):
provider = input.get("provider", "")
if not provider:
return {"ok": False, "error": "Missing provider"}
- api_key = models.get_api_key(provider)
+ api_key = models.get_api_key_raw(provider)
if api_key and api_key.strip() and api_key != "None":
return {"ok": True, "value": api_key}
return {"ok": True, "value": ""}
diff --git a/tests/test_model_config_api_keys.py b/tests/test_model_config_api_keys.py
index 942702d21..b432ed445 100644
--- a/tests/test_model_config_api_keys.py
+++ b/tests/test_model_config_api_keys.py
@@ -70,6 +70,19 @@ def test_model_config_api_keys_can_be_cleared_via_backend(monkeypatch, tmp_path)
assert handler._reveal_key({"provider": "openrouter"}) == {"ok": True, "value": ""}
+def test_api_key_reveal_preserves_the_pool_and_rotation_position(monkeypatch):
+ monkeypatch.setenv("API_KEY_OPENROUTER", "first-key,second-key")
+ monkeypatch.setattr(models, "api_keys_round_robin", {})
+ handler = ApiKeys(Flask(__name__), threading.Lock())
+ assert handler._reveal_key({"provider": "openrouter"}) == {
+ "ok": True, "value": "first-key,second-key"
+ }
+ assert models.api_keys_round_robin == {}
+ assert models.get_api_key("openrouter") == "first-key"
+ assert handler._reveal_key({"provider": "openrouter"})["value"] == "first-key,second-key"
+ assert models.get_api_key("openrouter") == "second-key"
+
+
def test_chat_model_configured_requires_identity_and_key(monkeypatch):
from plugins._model_config.helpers import model_config
diff --git a/tests/test_settings_api_keys.py b/tests/test_settings_api_keys.py
new file mode 100644
index 000000000..86b84bc81
--- /dev/null
+++ b/tests/test_settings_api_keys.py
@@ -0,0 +1,60 @@
+import json
+
+import pytest
+
+import models
+from helpers import dotenv, settings
+from helpers.secrets import SecretsManager
+
+
[email protected]("env_key", ["API_KEY_TEST_PROVIDER", "TEST_PROVIDER_API_KEY", "TEST_PROVIDER_API_TOKEN"])
+def test_settings_delta_preserves_full_provider_key_list(tmp_path, monkeypatch, env_key):
+ env_path = tmp_path / ".env"
+ env_path.write_text(f"{env_key}=first-key,second-key\nAUTH_PASSWORD=test-password\n")
+ for key in ("API_KEY_TEST_PROVIDER", "TEST_PROVIDER_API_KEY", "TEST_PROVIDER_API_TOKEN"):
+ monkeypatch.delenv(key, raising=False)
+ monkeypatch.setenv(env_key, "first-key,second-key")
+ # Track the canonical key so dotenv reloads are undone after each test.
+ if env_key != "API_KEY_TEST_PROVIDER":
+ monkeypatch.setenv("API_KEY_TEST_PROVIDER", "")
+ for key in ("AUTH_LOGIN", "AUTH_PASSWORD", "RFC_PASSWORD", "ROOT_PASSWORD"):
+ monkeypatch.setenv(key, "test-password" if key == "AUTH_PASSWORD" else "")
+ monkeypatch.setattr(dotenv, "get_dotenv_file_path", lambda: str(env_path))
+ monkeypatch.setattr(settings, "SETTINGS_FILE", str(tmp_path / "settings.json"))
+ monkeypatch.setattr(settings, "_settings", None)
+ monkeypatch.setattr(settings.git, "get_version", lambda: "v1")
+ monkeypatch.setattr(settings.runtime, "get_persistent_id", lambda: "test-runtime")
+ monkeypatch.setattr(settings.runtime, "is_dockerized", lambda: False)
+ monkeypatch.setattr(settings, "get_providers", lambda _: [{"value": "test_provider"}])
+ monkeypatch.setattr(settings, "get_default_secrets_manager", lambda: SecretsManager.get_instance(str(tmp_path / "secrets.env")))
+ monkeypatch.setattr(SecretsManager, "_instances", {})
+ monkeypatch.setattr(models, "api_keys_round_robin", {})
+
+ assert settings.get_settings()["api_keys"]["test_provider"] == "first-key,second-key"
+ assert models.api_keys_round_robin == {}
+ settings.set_settings_delta({"workdir_show": False}, apply=False)
+ assert dotenv.get_dotenv_value("API_KEY_TEST_PROVIDER") == "first-key,second-key"
+ assert settings.get_settings()["auth_password"] == "test-password"
+ assert json.loads((tmp_path / "settings.json").read_text())["api_keys"] == {}
+ assert models.get_api_key("test_provider") == "first-key"
+ assert models.get_api_key("test_provider") == "second-key"
+
+
+def test_raw_keys_do_not_include_runtime_oauth_placeholders(monkeypatch):
+ from helpers import extension
+ from plugins._oauth.extensions.python._functions.models.get_api_key.end import (
+ _20_oauth_account_dummy_key as oauth_key,
+ )
+ from plugins._oauth.helpers.providers import CODEX_PROVIDER_ID, DUMMY_API_KEY
+
+ provider = CODEX_PROVIDER_ID
+ for key in (f"API_KEY_{provider.upper()}", f"{provider.upper()}_API_KEY", f"{provider.upper()}_API_TOKEN"):
+ monkeypatch.delenv(key, raising=False)
+ monkeypatch.setattr(oauth_key, "oauth_provider_is_connected", lambda _: True)
+ monkeypatch.setattr(
+ extension, "_get_extension_classes",
+ lambda point, **_: [oauth_key.OAuthAccountDummyKey] if point == "_functions/models/get_api_key/end" else [],
+ )
+
+ assert models.get_api_key_raw(provider) == "None"
+ assert models.get_api_key(provider) == DUMMY_API_KEY