fix(openai): allow RFC 2544 fake-IP range for Realtime session requests by shushushv · Pull Request #86526 · openclaw/openclaw

shushushv · 2026-05-25T14:48:12Z

What Problem This Solves

OpenAI Realtime session-secret requests fail behind Clash-, Surge-, or sing-box-style TUN/fake-IP DNS when api.openai.com resolves into a documented fake-IP range. The generic SSRF guard correctly rejects those private-looking addresses unless the fixed provider hostname explicitly opts in.

Closes the remaining Realtime-specific part of #56535.

Why This Change Was Made

Both Realtime secret endpoints now share one OpenAI-owned SSRF policy. It permits RFC 2544 benchmark addresses and IPv6 unique-local addresses only for api.openai.com; the existing guard still checks redirects and rejects every non-allowlisted hostname and protected address class.

The maintainer rewrite intentionally keeps this policy inside the OpenAI plugin. The original public plugin-SDK export and API-budget changes were removed because there is no second consumer.

User Impact

Realtime voice and transcription session setup can work through TUN/fake-IP proxy DNS without weakening SSRF checks for arbitrary hosts. Users outside those proxy environments see no behavior change and gain no new configuration surface.

Evidence

Blacksmith Testbox tbx_01kwxddkwq631x975x00zmd94t: 74 focused tests passed across the shared helper, Realtime voice, and Realtime transcription.
Same Testbox: changed-surface extension production/test typechecks, lint, import-cycle check, and repository guards passed.
Fresh autoreview: no actionable findings, 0.96 confidence.
The contributor's macOS Clash TUN live proof remains valid: talk.client.create returned ok: true, audio streaming stayed active, and the Realtime response completed. Screenshot: https://github.com/user-attachments/assets/87a884d2-2902-4915-ade1-99993691d5da
Primary contracts checked: OpenAI's Realtime endpoint documentation, RFC 2544/RFC 3330 benchmark addressing, RFC 4193 unique-local IPv6, and the sing-box/Mihomo fake-IP defaults.

Known gap: no independent authenticated OpenAI Realtime call was available through a second local Clash/Surge profile. Exact policy propagation for both endpoints is regression-tested.

clawsweeper · 2026-05-25T14:50:53Z

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 11:48 AM ET / 15:48 UTC.

Summary
The PR adds a host-scoped fake-IP SSRF policy to OpenAI Realtime session-secret requests, exports the policy helper through plugin-sdk/ssrf-runtime, updates Realtime tests, and adjusts Plugin SDK export budgets.

PR surface: Source +9, Tests +20, Other 0. Total +29 across 5 files.

Reproducibility: yes. with high confidence from source and supplied proof rather than a local fake-IP run: current main and v2026.6.11 call the guarded Realtime secret fetch without a policy, while the guard blocks fake-IP ranges unless policy opts in. The inspected screenshots show the before-fix block and after-fix successful Realtime RPC activity.

Review metrics: 3 noteworthy metrics.

Public SDK exports: 1 function export added. The new plugin-sdk/ssrf-runtime export is third-party Plugin SDK API surface, not only an internal OpenAI plugin detail.
SSRF policy exceptions: 1 host-scoped exception added. Realtime secret requests would newly allow fake-IP DNS ranges for api.openai.com, which maintainers should explicitly notice before merge.
SDK budget baseline: PR sets 10272/5162; current main is 10430/5207. The branch is based on older Plugin SDK export budgets and needs a rebase plus fresh API check before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Rebase on current main, resolve conflicts, and refresh the Plugin SDK surface budget.
Rerun pnpm plugin-sdk:api:check and the focused OpenAI Realtime voice/transcription tests after the rebase.

Risk before merge

[P1] Merging intentionally relaxes the resolved-address SSRF block for OpenAI Realtime session-secret requests when api.openai.com resolves to RFC 2544 or IPv6 ULA fake-IP ranges; the exception is hostname-scoped but security-sensitive.
[P1] The PR adds a public plugin-sdk/ssrf-runtime helper export for a bundled OpenAI plugin fix, so maintainers should decide whether that Plugin SDK API surface is wanted or whether the policy should stay local.
[P1] The branch is currently conflicting and its Plugin SDK budget edit is stale against current main, so it needs a rebase and fresh API/test proof before merge.

Maintainer options:

Accept scoped exception after rebase (recommended)
A maintainer can accept the hostname-scoped SSRF and SDK API tradeoff, then require conflict resolution, refreshed SDK budgets, and focused API/test proof before merge.
Avoid public SDK growth
The OpenAI plugin can keep an equivalent local policy literal and remove the plugin-sdk/ssrf-runtime export if maintainers do not want the helper promoted.
Pause fake-IP relaxation
If this exception is not an accepted security boundary change, pause or close the PR and document proxy DNS exclusions as the supported workaround.

Next step before merge

[P2] The remaining blocker is maintainer acceptance of the SSRF security-boundary change and public SDK export plus conflict resolution, not a narrow automated repair on this contributor PR.

Maintainer decision needed

Question: Should OpenClaw accept this hostname-scoped fake-IP SSRF exception for OpenAI Realtime session-secret requests, and should the helper be exposed through the public Plugin SDK?
Rationale: The implementation is narrow, but it intentionally changes a security boundary and expands public Plugin SDK surface, which requires maintainer intent rather than automated cleanup.
Likely owner: steipete — He has the strongest recent history across the OpenAI Realtime helper and fake-IP SSRF policy paths.
Options:
- Accept after rebase (recommended): Approve the scoped SSRF and SDK tradeoff, then require a rebase, refreshed SDK budgets, and focused API/test proof before merge.
- Keep policy local: Use the same SsrFPolicy shape inside the OpenAI plugin and avoid exporting another public Plugin SDK helper.
- Decline the exception: Leave fake-IP proxy users on DNS/proxy exclusions or disabled fake-IP mode for Realtime until a broader networking policy is chosen.

Security
Needs attention: The diff has no supply-chain concern, but its host-scoped fake-IP SSRF relaxation is a security-boundary decision that needs maintainer approval.

Review details

Best possible solution:

Land a rebased, policy-approved Realtime fix; if maintainers do not want the new SDK export, keep the same host-scoped policy local to the OpenAI plugin.

Do we have a high-confidence way to reproduce the issue?

Yes, with high confidence from source and supplied proof rather than a local fake-IP run: current main and v2026.6.11 call the guarded Realtime secret fetch without a policy, while the guard blocks fake-IP ranges unless policy opts in. The inspected screenshots show the before-fix block and after-fix successful Realtime RPC activity.

Is this the best way to solve the issue?

Yes as a narrow implementation, pending maintainer policy acceptance. Reusing the existing host-scoped fake-IP policy in the shared Realtime secret helper covers both voice and transcription without broadly allowing private networks; keeping the policy local is the safer alternative if maintainers do not want a public SDK export.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a308e3b83429.

Label changes

Label changes:

add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): The PR body and inspected screenshots provide after-fix real behavior proof from a macOS Clash TUN/fake-IP setup, showing active Realtime UI and successful Realtime audio RPC calls after the fix.
remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

P2: This is a bounded OpenAI Realtime compatibility bugfix with meaningful but non-emergency SSRF and SDK review needs.
merge-risk: 🚨 compatibility: The PR expands public Plugin SDK API surface and currently carries stale SDK budget edits against main.
merge-risk: 🚨 security-boundary: The PR intentionally allows fake-IP DNS ranges for a hostname-scoped OpenAI Realtime secret request path.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): The PR body and inspected screenshots provide after-fix real behavior proof from a macOS Clash TUN/fake-IP setup, showing active Realtime UI and successful Realtime audio RPC calls after the fix.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body and inspected screenshots provide after-fix real behavior proof from a macOS Clash TUN/fake-IP setup, showing active Realtime UI and successful Realtime audio RPC calls after the fix.
proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body and inspected screenshots provide after-fix real behavior proof from a macOS Clash TUN/fake-IP setup, showing active Realtime UI and successful Realtime audio RPC calls after the fix.

Evidence reviewed

PR surface:

Source +9, Tests +20, Other 0. Total +29 across 5 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	2	10	1	+9
Tests	2	20	0	+20
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	2	2	0
Total	5	32	3	+29

Security concerns:

[medium] Approve scoped fake-IP SSRF relaxation — extensions/openai/realtime-provider-shared.ts:113
Passing this policy allows OpenAI Realtime session-secret requests to proceed when api.openai.com resolves to RFC 2544 or IPv6 ULA fake-IP addresses; the helper remains hostname-scoped, but maintainers should explicitly accept the boundary change.
Confidence: 0.9

What I checked:

Repository policy read and applied: Root AGENTS.md and scoped extensions/AGENTS.md, src/plugin-sdk/AGENTS.md, and scripts/AGENTS.md were read; the Plugin SDK and security-boundary guidance directly affects this review. (AGENTS.md:1, a308e3b83429)
Current main still lacks the policy on the Realtime secret fetch: createOpenAIRealtimeSecret calls fetchWithSsrFGuard with URL, init, and audit context only; no policy is passed on current main. (extensions/openai/realtime-provider-shared.ts:88, a308e3b83429)
Latest release is not already fixed: v2026.6.11 has the same unpolicyed Realtime secret fetch path, so the PR is not obsolete on shipped code. (extensions/openai/realtime-provider-shared.ts:87, e085fa1a3ffd)
PR applies the policy at the shared Realtime helper: The PR commit adds OPENAI_REALTIME_SSRF_POLICY and passes it as policy to the shared Realtime secret fetch, covering voice and transcription callers. (extensions/openai/realtime-provider-shared.ts:113, f0aeb1572089)
Fake-IP helper is host-scoped: The existing helper returns allowRfc2544BenchmarkRange, allowIpv6UniqueLocalRange, and hostnameAllowlist derived from the supplied HTTP base URL. (src/infra/net/ssrf.ts:189, a308e3b83429)
Guard still blocks special-use DNS answers by default: Resolved addresses are rejected with Blocked: resolves to private/internal/special-use IP address unless policy flags allow the relevant range; exact-host trust still blocks metadata/link-local answers. (src/infra/net/ssrf.ts:401, a308e3b83429)

Likely related people:

steipete: Peter Steinberger authored recent OpenAI Realtime shared-helper work and fake-IP SSRF policy work that this PR reuses. (role: recent Realtime and SSRF contributor; confidence: high; commits: edb7e00721fd, dca53afd5301, 6dfdc92bd4c6; files: extensions/openai/realtime-provider-shared.ts, src/infra/net/ssrf.ts)
Kaspre: Kaspre authored origin-scoped SSRF trust and SDK-level SSRF export work near the public boundary touched by this PR. (role: SSRF and Plugin SDK contract contributor; confidence: medium; commits: 44840007d42d; files: src/infra/net/ssrf.ts, src/plugin-sdk/ssrf-runtime.ts)
vincentkoc: Vincent Koc worked on canonical private-network opt-in semantics and recent Plugin SDK surface-budget tightening relevant to the new export and budget edit. (role: Plugin SDK and private-network policy contributor; confidence: medium; commits: 63db3443f131, 497d53d821e6, e085fa1a3ffd; files: src/plugin-sdk/ssrf-runtime.ts, scripts/plugin-sdk-surface-report.mjs)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (3 earlier review cycles)

reviewed 2026-06-24T16:26:27.252Z sha f0aeb15 :: needs maintainer review before merge. :: none
reviewed 2026-06-29T13:23:28.833Z sha f0aeb15 :: needs maintainer review before merge. :: none
reviewed 2026-07-05T15:40:50.811Z sha f0aeb15 :: needs maintainer review before merge. :: none

clawsweeper · 2026-05-25T15:01:04Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Neon Review Wisp

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: sparkles near resolved comments.
Image traits: location diff observatory; accessory tiny test log scroll; palette seafoam, black, and opal; mood calm; pose balancing on a branch marker; shell matte ceramic shell; lighting warm desk-lamp glow; background small review tokens.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Neon Review Wisp in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

shushushv · 2026-05-26T02:26:16Z

/recheck

shushushv · 2026-06-03T09:21:51Z

Friendly ping on this one. The user-visible failure is attached: without the scoped fake-IP policy, OpenAI Realtime users behind Clash/Surge/sing-box TUN mode hit “Blocked: resolves to private/internal/special-use IP address” and cannot establish a Realtime session.
This PR keeps the SSRF relaxation host-scoped to api.openai.com rather than opening the guard broadly.

shushushv · 2026-06-07T12:39:39Z

@clawsweeper re-review

clawsweeper · 2026-06-07T12:39:41Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/27092837360
Updated: 2026-06-07T12:49:16.280Z

Co-authored-by: shushushu <[email protected]>

openclaw-barnacle · 2026-07-07T04:43:38Z

This assigned pull request has been automatically marked as stale after being open for 27 days.
Please add updates or it will be closed.

steipete · 2026-07-07T04:48:38Z

Land-ready maintainer rewrite completed.

Kept the fake-IP exception inside the OpenAI plugin; removed the proposed one-consumer public SDK export and SDK-budget changes.
Scoped the exception to the fixed api.openai.com hostname. RFC 2544 benchmark and IPv6 ULA addresses are accepted only for that host; redirect targets and all other protected address classes remain guarded.
Blacksmith Testbox tbx_01kwxddkwq631x975x00zmd94t: 74 focused Realtime tests passed.
Same Testbox: changed-surface extension production/test typechecks, lint, import-cycle check, and repository guards passed.
Fresh autoreview: no actionable findings, 0.96 confidence.
Exact-head CI: https://github.com/openclaw/openclaw/actions/runs/28841884187 — passed.
Commit f7e37bc383626f032e171851b6fc2f35c684d5d4 is GitHub-verified and includes contributor co-authorship.

Known live-proof gap: I did not have a second authenticated Clash/Surge TUN profile. The contributor's credentialed before/after Realtime proof remains in the PR body, and both secret endpoints assert the exact policy in regression tests.

steipete · 2026-07-07T04:49:03Z

Merged via squash.

Prepared head SHA: f7e37bc383626f032e171851b6fc2f35c684d5d4
Landed commit: a596ca1795b6fd012aa4c66d6beb967d4538b247

openclaw-barnacle Bot added extensions: openai size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 25, 2026

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 25, 2026

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 26, 2026

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch from 89f9ec8 to df4eae8 Compare May 26, 2026 07:34

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch 2 times, most recently from df4eae8 to b25519a Compare May 26, 2026 08:38

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 26, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 26, 2026

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch from b25519a to 8d5d785 Compare May 26, 2026 08:54

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch from 114bb7b to 6cb8194 Compare June 2, 2026 10:02

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 2, 2026

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch from 6cb8194 to 621f9a5 Compare June 7, 2026 12:37

openclaw-barnacle Bot added the docs Improvements or additions to documentation label Jun 7, 2026

clawsweeper Bot added the merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. label Jun 7, 2026

clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels Jun 15, 2026

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch from 621f9a5 to 49b9ba0 Compare June 15, 2026 07:31

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 15, 2026

shushushv force-pushed the fix/openai-realtime-ssrf-rfc2544 branch from 49b9ba0 to f1c6bc6 Compare June 16, 2026 11:44

fix(openai): allow fake-IP Realtime requests

f7e37bc

Co-authored-by: shushushu <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(openai): allow RFC 2544 fake-IP range for Realtime session requests#86526

fix(openai): allow RFC 2544 fake-IP range for Realtime session requests#86526
steipete merged 1 commit into
openclaw:mainfrom
shushushv:fix/openai-realtime-ssrf-rfc2544

shushushv commented May 25, 2026 •

edited by steipete

Loading

Uh oh!

clawsweeper Bot commented May 25, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 25, 2026 •

edited

Loading

Uh oh!

shushushv commented May 26, 2026

Uh oh!

shushushv commented Jun 3, 2026

Uh oh!

shushushv commented Jun 7, 2026

Uh oh!

clawsweeper Bot commented Jun 7, 2026 •

edited

Loading

Uh oh!

openclaw-barnacle Bot commented Jul 7, 2026

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

shushushv commented May 25, 2026 • edited by steipete Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Hatch command

Uh oh!

shushushv commented May 26, 2026

Uh oh!

shushushv commented Jun 3, 2026

Uh oh!

shushushv commented Jun 7, 2026

Uh oh!

clawsweeper Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openclaw-barnacle Bot commented Jul 7, 2026

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shushushv commented May 25, 2026 •

edited by steipete

Loading

clawsweeper Bot commented May 25, 2026 •

edited

Loading

clawsweeper Bot commented May 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 7, 2026 •

edited

Loading