Greptile Summary

This PR correctly fixes the /v1/responses endpoint by updating FunctionToolDefinitionSchema from the Chat Completions wrapped format (function: { name, ... }) to the Responses API flat format (name, description, parameters at the top level), and adds a normalization step in extractClientTools to convert the flat format back to the internal ClientToolDefinition wrapped format. The schema fix and the HTTP normalization logic are both correct.

However, two tests in openresponses-parity.test.ts were not updated and will fail:

• \"should validate request with client tools\" (line 185) — still passes wrapped format tools and expects success: true
• \"should validate complete turn-based tool flow\" (line 233) — turn1Request still uses wrapped format tools and expects success: true

These tests need to be updated to the flat Responses API format before merging.

Confidence Score: 4/5

Safe to merge after fixing two stale test cases in the CreateResponseBody Schema block that still use the old wrapped format.

The schema and HTTP normalization changes are correct and well-motivated. The only concrete defects are two test cases that were not updated alongside the schema change and will produce test failures on CI. These must be fixed before merging.

src/gateway/openresponses-parity.test.ts — the 'should validate request with client tools' and 'should validate complete turn-based tool flow' tests still use the wrapped format.

This is a comment left during a code review.
Path: src/gateway/openresponses-parity.test.ts
Line: 185-215

Comment:
**Stale wrapped-format tools will cause this test to fail**

This test still passes the old Chat Completions wrapped format (`function: { name, ... }`) inside the `tools` array and asserts `result.success === true`. However, `CreateResponseBodySchema` now delegates to `ToolDefinitionSchema` → `FunctionToolDefinitionSchema`, which uses `.strict()` and only accepts the flat format (`name`, `description`, `parameters` at the top level). Sending `{ type: "function", function: { ... } }` will be rejected, so this test will fail after the PR is merged.

The same stale format also appears at lines 243–255 inside the `"should validate complete turn-based tool flow"` test.

Both need to be updated to the flat Responses API format — for example:

```suggestion
    it("should validate request with client tools", async () => {
      const validRequest = {
        model: "claude-sonnet-4-20250514",
        input: [
          {
            type: "message" as const,
            role: "user" as const,
            content: "What's the weather?",
          },
        ],
        tools: [
          {
            type: "function" as const,
            name: "get_weather",
            description: "Get weather for a location",
            parameters: {
              type: "object",
              properties: {
                location: { type: "string" },
              },
              required: ["location"],
            },
          },
        ],
      };

      const result = CreateResponseBodySchema.safeParse(validRequest);
      expect(result.success).toBe(true);
    });
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/gateway/openresponses-parity.test.ts
Line: 233-255

Comment:
**Stale wrapped-format tools in turn-based flow test**

The `turn1Request` here still uses the wrapped `{ type: "function", function: { ... } }` format and asserts `turn1Result.success === true`. With the new strict flat schema this will fail. The `tools` array needs to be updated to the flat Responses API format, matching the fix applied everywhere else.

```suggestion
      const turn1Request = {
        model: "claude-sonnet-4-20250514",
        input: [
          {
            type: "message" as const,
            role: "user" as const,
            content: "What's the weather in San Francisco?",
          },
        ],
        tools: [
          {
            type: "function" as const,
            name: "get_weather",
            description: "Get weather for a location",
          },
        ],
      };
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "gateway: fix /v1/responses tool schema t..." | Re-trigger Greptile}

Fixed — updated the two stale test cases in the CreateResponseBody Schema block (should validate request with client tools and should validate complete turn-based tool flow) to use the flat Responses API format. @codex review

Addressed the P2: added strict?: boolean to ClientToolDefinition.function in params.ts and now propagate it through extractClientTools. @codex review

Codex Review: Didn't find any major issues. Nice work!

@greptile , are you good with the updated code as well?

Yes, looks solid. The boundary layer is clean:

1. Schema now correctly accepts the flat Responses API format
2. extractClientTools normalizes flat → wrapped at the HTTP boundary
3. Internal types unchanged (added strict field which is good)
4. Tests now cover both the valid flat format and explicitly reject the wrapped format

The separation between API surface (flat) and internal representation (wrapped) is exactly where it should be. Good fix.

Gateway + Client Configuration Details

For anyone wanting to reproduce the Codex CLI → OpenClaw → local model setup:

OpenClaw gateway config (~/.openclaw/openclaw.json):

{
  gateway: {
    port: 18789,
    bind: "lan",
    auth: { mode: "token", token: "<token>" },
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
        responses: { enabled: true }
      }
    }
  },
  models: {
    mode: "replace",
    providers: {
      "local-vllm": {
        baseUrl: "http://10.15.0.166:8000/v1",
        apiKey: "local-only-key",
        api: "openai-completions",
        models: [{
          id: "qwen35-397b",
          name: "Qwen3.5-397B-NVFP4",
          api: "openai-completions",
          reasoning: true,
          input: ["text", "image"],
          contextWindow: 500000,
          maxTokens: 32768,
          compat: { supportsDeveloperRole: false, supportsUsageInStreaming: true }
        }]
      }
    }
  }
}

Codex CLI config (~/.codex/config.toml):

model = "openclaw"
model_provider = "openclaw-local"

[model_providers.openclaw-local]
name = "OpenClaw Gateway"
base_url = "http://<gateway-host>:18789/v1"
wire_api = "responses"
env_key = "OPENCLAW_TOKEN"

[model_providers.openclaw-local.http_headers]
"x-openclaw-scopes" = "operator.write"

The wire_api = "responses" setting is what makes Codex use the /v1/responses endpoint (and the flat tool format that this PR fixes).

Local Testing Evidence

Tested the fix end-to-end on a self-hosted OpenClaw v2026.3.28 instance (Ubuntu 24.04, Qwen3.5-397B via vLLM):

1. curl — flat Responses API format (success)

curl -s http://localhost:18789/v1/responses \
  -H "Authorization: Bearer <token>" \
  -H "x-openclaw-scopes: operator.write" \
  -H "Content-Type: application/json" \
  -d '{"model":"openclaw","input":"Use the crpc_respond tool to say hello","stream":false,
       "tools":[{"type":"function","name":"crpc_respond","description":"Send a response",
                 "parameters":{"type":"object","properties":{"content":{"type":"string"},"done":{"type":"boolean"}},"required":["content","done"]}}]}'

Result: HTTP 200, agent returned function_call output for crpc_respond with {"content":"Hello! 👋","done":true}.

2. OpenAI Codex CLI — connected and working

Configured Codex CLI v0.117.0 with wire_api = "responses" pointing at the patched gateway.

$ OPENCLAW_TOKEN=<token> codex exec --full-auto --provider openclaw-local \
    "Read /tmp/test.js and tell me what value it prints"

Result: Codex successfully connected, delegated its tools via the flat Responses API format, and the agent correctly answered the query. Token usage: 42,387 tokens routed through Qwen3.5-397B.

3. Wrapped format correctly rejected

After the patch, sending the old Chat Completions wrapped format ({type:"function", function:{...}}) is rejected by the .strict() schema as expected.

Tested with the monkey-patched compiled bundle on the installed npm module; the same source changes are in this PR.

Regarding the automated review feedback:

Re: strict field passthrough — The Zod schema uses .strict() as a validation method (rejecting extra properties), not as a field in the tool definition. Neither FunctionToolDefinitionSchema nor ClientToolDefinition define a strict field, so there's nothing to forward. If OpenResponses adds strict support in the future, both the Zod schema and ClientToolDefinition type would need updating — but that's a separate concern.

Re: test fixture consistency — All tool definitions in both openresponses-http.test.ts and openresponses-parity.test.ts use the nested function: {} format consistently. The flat format acceptance was added at the schema validation layer (where both formats should be accepted), not in the test fixtures. The tests are internally consistent.

The failing CI checks (checks-fast-contracts-protocol, checks-node-test-3, checks-node-channels-1, Windows node tests) — are these related to this PR or pre-existing failures on main? Happy to investigate if needed.

Investigated the CI failures — none are related to this PR:

• checks-fast-contracts-protocol: Fails with "Vitest cannot be imported in a CommonJS module using require()" in src/channels/plugins/contracts/group-policy.contract.test.ts — a CJS/ESM infrastructure issue in the contracts test suite, unrelated to gateway changes.
• checks-node-test-3: Fails in src/config/config.allowlist-requires-allowfrom.test.ts (test timeout ~3min) and src/plugins/bundled-plugin-metadata.test.ts (assertion on plugin build artifacts) — both unrelated to tool schema.
• checks-windows-node-test-*: Various failures in src/cron/, src/infra/, src/channels/plugins/ — Windows-specific environment failures, unrelated to our changes.

This PR only touches src/gateway/openresponses-http.ts, open-responses.schema.ts, and openresponses-parity.test.ts. None of the failing test files are in those paths.