Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

runner: keep custom Codex Responses tools function-only by default (#270)

Oscar163e2ccbc0f3
diff --git a/docs/self-hosting-guide.md b/docs/self-hosting-guide.md
index fff6c4ab..f1199b6c 100644
--- a/docs/self-hosting-guide.md
+++ b/docs/self-hosting-guide.md
@@ -276,6 +276,12 @@ Name those tools on the connection, comma-separated, and every turn through it r
for Codex's `web_search` that is a hard switch in its configuration, not a request. The same field
exists on each harness, for tools you want off regardless of the endpoint.
+Custom OpenAI Responses connections start with Codex's function tools only. The Codex namespace
+(`multi_agent_v1`) and built-in `web_search` are disabled by default because compatible endpoints
+often reject those tool types. Set `namespace_tools` or `web_search` to `"1"` in the connection
+configuration (or turn the corresponding console switch on) when the endpoint supports them;
+`disabled_tools` still takes precedence for `web_search`.
+
</details>
<details>
diff --git a/gateway/app.py b/gateway/app.py
index 814a07c3..de8b0fa3 100644
--- a/gateway/app.py
+++ b/gateway/app.py
@@ -856,7 +856,8 @@ def _policy_chain(raw: str) -> list[str]:
_AUTH_FIELDS = ("api_key", "base_url", "aws_region", "aws_access_key_id", "aws_secret_access_key",
"aws_session_token", "aws_bearer_token", "gcp_project", "gcp_region",
- "gcp_sa_json", "wire_api", "api_format", "full_url")
+ "gcp_sa_json", "wire_api", "api_format", "full_url", "namespace_tools",
+ "web_search")
# ── LLM egress broker ────────────────────────────────────────────────────────────────────────
@@ -4818,6 +4819,8 @@ _PROVIDER_CATALOG: dict[str, dict] = {
{"key": "base_url", "label": "Endpoint URL",
"placeholder": "https://your-api.example.com"},
{"key": "full_url", "label": "Use Full URL"},
+ {"key": "namespace_tools", "label": "Enable Codex namespace tools"},
+ {"key": "web_search", "label": "Enable Codex web search"},
],
"secret": "api_key",
"secret_label": "API Key",
diff --git a/gateway/tests/test_custom_model_map.py b/gateway/tests/test_custom_model_map.py
index 49b4eeb5..e4bd7efe 100644
--- a/gateway/tests/test_custom_model_map.py
+++ b/gateway/tests/test_custom_model_map.py
@@ -27,7 +27,8 @@ def test_a_custom_integration_saved_with_one_model_id_still_reads_as_that_one_ro
def test_the_mapped_connection_sends_the_wire_id_verbatim(monkeypatch):
integ = {"name": "proxy", "provider": "custom",
- "config": {"api_format": "responses", "base_url": "https://proxy.internal/openai/v1", "api_key": "k"},
+ "config": {"api_format": "responses", "base_url": "https://proxy.internal/openai/v1", "api_key": "k",
+ "namespace_tools": "1", "web_search": "1"},
"models": [{"canonical": "gpt-5.5", "provider_id": "prod-gpt-v2"}]}
async def mm(): return {"gpt-5.5": "proxy"}
async def docs(): return [integ]
@@ -35,6 +36,10 @@ def test_the_mapped_connection_sends_the_wire_id_verbatim(monkeypatch):
monkeypatch.setattr(gw, "_integrations_doc", docs)
conn = asyncio.run(gw._mapped_integration_conn("codex", "gpt-5.5"))
assert conn and conn["provider"] == "tokenrouter" and conn["model"] == "prod-gpt-v2" and conn["_model_resolved"]
+ assert conn["namespace_tools"] == "1" and conn["web_search"] == "1"
+ monkeypatch.setattr(gw, "PUBLIC_BASE_URL", "https://public.example")
+ forwarded = gw._auth_from_conn(conn, sid="sid")
+ assert forwarded and forwarded["namespace_tools"] == "1" and forwarded["web_search"] == "1"
# a Responses endpoint drives codex and nothing else; a chat one never drives codex
assert gw._integration_serves_backend(integ, "codex") and not gw._integration_serves_backend(integ, "hermes")
integ["config"]["api_format"] = "openai"
@@ -46,6 +51,7 @@ def test_the_catalog_offers_the_canonicals_to_the_custom_form_and_disabled_tools
custom = cat["custom"]
assert "gpt-5.5" in custom["canonicals"] and "claude-opus-4.8" in custom["canonicals"]
assert not any(f["key"] == "model_id" for f in custom["fields"])
+ assert {"namespace_tools", "web_search"} <= {f["key"] for f in custom["fields"]}
for pid, c in cat.items():
has = any(f["key"] == "disabled_tools" for f in c["fields"])
assert has == ("codex" in c["backends"]), pid
diff --git a/runner/server.py b/runner/server.py
index a2992ef9..9b4dfeea 100644
--- a/runner/server.py
+++ b/runner/server.py
@@ -1401,8 +1401,10 @@ class Auth(BaseModel):
# Codex provider tuning
wire_api: str | None = None # responses | chat (default responses)
# Custom provider
- api_format: str | None = None # "openai" | "anthropic" (custom integration)
+ api_format: str | None = None # "openai" | "responses" | "anthropic" (custom integration)
full_url: str | None = None # "1" when the URL is a complete request URL
+ namespace_tools: bool | str | None = None # "1"/true to opt into namespace tools
+ web_search: bool | str | None = None # "1"/true to opt into built-in web search
# ── canonical-event normalizers ──────────────────────────────────────────────────
@@ -1946,6 +1948,37 @@ def _codex_web_search_off(tools_disabled: list[str] | None) -> bool:
for x in (tools_disabled or []) if x and x.strip())
+def _codex_flag(value: str | bool | None) -> bool | None:
+ """Parse a connection's optional on/off flag, preserving an unset value."""
+ if value is None or (isinstance(value, str) and not value.strip()):
+ return None
+ if isinstance(value, bool):
+ return value
+ return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _codex_custom_responses(auth: Auth) -> bool:
+ """Whether this Codex turn targets a custom OpenAI Responses integration."""
+ return str(auth.api_format or "").strip().lower() == "responses"
+
+
+def _codex_namespace_tools_off(auth: Auth) -> bool:
+ """Keep Codex's multi-agent namespace out of custom endpoints unless opted in."""
+ return _codex_custom_responses(auth) and _codex_flag(auth.namespace_tools) is not True
+
+
+def _codex_web_search_off_for_auth(auth: Auth, tools_disabled: list[str] | None) -> bool:
+ """Apply the connection opt-in without weakening the existing disabled-tools switch."""
+ return _codex_web_search_off(tools_disabled) or (
+ _codex_custom_responses(auth) and _codex_flag(auth.web_search) is not True)
+
+
+def _codex_insert_top_level(cfg: str, value: str) -> str:
+ """Insert a setting before the first TOML table so it stays at the document's top level."""
+ head, sep, tail = cfg.partition("\n[")
+ return head + "\n" + value + sep + tail if sep else cfg + "\n" + value + "\n"
+
+
def _codex_prepare_env(provider: str, auth: Auth, model: str, cwd: str,
env: dict, mcp_toml: str = "", resume: bool = False,
tools_disabled: list[str] | None = None) -> "pathlib.Path":
@@ -1987,15 +2020,19 @@ def _codex_prepare_env(provider: str, auth: Auth, model: str, cwd: str,
model=model, provider=f"hr-{p}", effort=CODEX_REASONING_EFFORT, ctx=CODEX_CONTEXT_WINDOW,
name=spec["name"], base_url=base_url, env_key=spec["env_key"],
wire_api=auth.wire_api or "responses")
- if _codex_web_search_off(tools_disabled):
+ if _codex_namespace_tools_off(auth):
+ # Codex enables its multi-agent namespace by default. Most custom Responses endpoints
+ # only accept function tools, so custom integrations opt in explicitly when they support
+ # this Codex-specific tool family.
+ cfg = _codex_insert_top_level(cfg, "[agents]\nenabled = false")
+ if _codex_web_search_off_for_auth(auth, tools_disabled):
# The one built-in codex tool with a hard switch. Codex offers web_search by default on
# the Responses wire and an endpoint that gates it per model answers 400 "The following
# tool is not allowed" on every turn (issue #150); the TOP-LEVEL key is the only knob
# (verified on codex 0.147 and 0.154: `[tools] web_search = false` parses and does
# nothing). It goes before the first table header: appended at the end it would belong
# to the last table and switch nothing (measured on rc.1: the tool stayed in the request).
- head, sep, tail = cfg.partition("\n[")
- cfg = head + '\nweb_search = "disabled"' + sep + tail
+ cfg = _codex_insert_top_level(cfg, 'web_search = "disabled"')
if resume:
# A resumed session keeps the provider id it started under; Codex looks that id up in the
# config and refuses to load without it ("Model provider `azure` not found", a July
diff --git a/runner/tests/test_codex_web_search.py b/runner/tests/test_codex_web_search.py
index 98fade27..c0c01dcf 100644
--- a/runner/tests/test_codex_web_search.py
+++ b/runner/tests/test_codex_web_search.py
@@ -28,3 +28,43 @@ def test_the_switch_stays_out_of_config_unless_named(tmp_path):
tomllib.loads((cfg_dir / "config.toml").read_text())
assert rs._codex_web_search_off(["WebSearch"]) and rs._codex_web_search_off(["web-search"]) \
and not rs._codex_web_search_off(None) and not rs._codex_web_search_off(["web"])
+
+
+def test_custom_responses_defaults_to_function_tools_only(tmp_path):
+ env = {"HOME": str(tmp_path)}
+ auth = rs.Auth(api_key="k", base_url="https://example.invalid/v1", api_format="responses")
+ cfg_dir = rs._codex_prepare_env("openai", auth, "gpt-5.5", str(tmp_path), env)
+ import tomllib
+ doc = tomllib.loads((cfg_dir / "config.toml").read_text())
+ assert doc["agents"]["enabled"] is False
+ assert doc["web_search"] == "disabled"
+
+
+def test_native_responses_keep_codex_tools_default(tmp_path):
+ env = {"HOME": str(tmp_path)}
+ auth = rs.Auth(api_key="k", base_url="https://example.invalid/v1")
+ cfg_dir = rs._codex_prepare_env("openai", auth, "gpt-5.5", str(tmp_path), env)
+ import tomllib
+ doc = tomllib.loads((cfg_dir / "config.toml").read_text())
+ assert "agents" not in doc and "web_search" not in doc
+
+
+def test_custom_responses_can_opt_into_codex_tools(tmp_path):
+ env = {"HOME": str(tmp_path)}
+ auth = rs.Auth(api_key="k", base_url="https://example.invalid/v1", api_format="responses",
+ namespace_tools="1", web_search="1")
+ cfg_dir = rs._codex_prepare_env("openai", auth, "gpt-5.5", str(tmp_path), env)
+ import tomllib
+ doc = tomllib.loads((cfg_dir / "config.toml").read_text())
+ assert "agents" not in doc and "web_search" not in doc
+
+
+def test_explicit_disabled_tools_still_override_custom_opt_in(tmp_path):
+ env = {"HOME": str(tmp_path)}
+ auth = rs.Auth(api_key="k", base_url="https://example.invalid/v1", api_format="responses",
+ web_search="1")
+ cfg_dir = rs._codex_prepare_env("openai", auth, "gpt-5.5", str(tmp_path), env,
+ tools_disabled=["web_search"])
+ import tomllib
+ doc = tomllib.loads((cfg_dir / "config.toml").read_text())
+ assert doc["web_search"] == "disabled"
diff --git a/ui/src/app/(app)/integrations/page.tsx b/ui/src/app/(app)/integrations/page.tsx
index 80f493bf..882d5555 100644
--- a/ui/src/app/(app)/integrations/page.tsx
+++ b/ui/src/app/(app)/integrations/page.tsx
@@ -433,6 +433,42 @@ export default function IntegrationsPage() {
</div>
);
}
+ if (isCustom && (f.key === 'namespace_tools' || f.key === 'web_search')) {
+ // Custom Responses endpoints default to function tools only. Keep these
+ // Codex-specific capabilities explicit so an endpoint can opt in safely.
+ if (editing.config['api_format'] !== 'responses') return null;
+ const enabled = editing.config[f.key] === '1' || editing.config[f.key] === 'true';
+ const label = f.key === 'namespace_tools' ? 'Enable Codex namespace tools' : 'Enable Codex web search';
+ const help = f.key === 'namespace_tools'
+ ? 'Off by default because many Responses endpoints accept function tools only.'
+ : 'Off by default; enable only when this endpoint accepts Codex web search.';
+ return (
+ <div className="field" key={f.key}>
+ <label>{label}</label>
+ <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+ <button type="button" role="switch" aria-checked={enabled}
+ className="toggle-button"
+ onClick={() => setEditing({
+ ...editing,
+ config: { ...editing.config, [f.key]: enabled ? '' : '1' },
+ })}
+ style={{ minWidth: 44, minHeight: 26, padding: 0, borderRadius: 999,
+ border: enabled ? '1px solid var(--accent)' : '1px solid var(--line)',
+ background: enabled ? 'var(--accent)' : 'var(--surface-subtle)',
+ cursor: 'pointer', position: 'relative', transition: 'background .15s' }}>
+ <span style={{ display: 'block', width: 18, height: 18, borderRadius: 999,
+ background: enabled ? '#fff' : 'var(--line)',
+ position: 'absolute', top: 3, left: enabled ? 21 : 3,
+ transition: 'left .15s' }} />
+ </button>
+ <span style={{ fontSize: 13, color: enabled ? 'var(--ink)' : 'var(--muted)' }}>
+ {enabled ? 'On' : 'Off'}
+ </span>
+ </div>
+ <p className="field-help">{help}</p>
+ </div>
+ );
+ }
// Dynamic placeholder for base_url based on full_url toggle
let placeholder = f.placeholder || '';
if (isCustom && f.key === 'base_url') {