fix(onboard): guide users to a compatible endpoint or agent when Chat Completions is missing by laitingsheng · Pull Request #6769 · NVIDIA/NemoClaw

laitingsheng · 2026-07-13T12:19:56Z

Summary

When onboarding selects an agent that requires OpenAI Chat Completions (such as Deep Agents) against an Anthropic-compatible endpoint that does not serve /v1/chat/completions, validation now prints an actionable next step before exiting: use an OpenAI-compatible endpoint or switch to OpenClaw. The guidance uses the same failure classification as recovery, so a model-specific 404 continues to offer a model retry without incorrectly claiming the route is absent.

Related Issue

Fixes #6765

Changes

Print actionable endpoint/agent guidance after the existing validation-failure summary and before the existing non-interactive exit.
Gate the guidance on intendedApi === "openai-completions" and the existing endpoint failure classification. Authentication errors, transport errors, and model-specific 404 responses do not print route-missing guidance.
Recommend OpenClaw as the supported Anthropic-native alternative. Hermes is intentionally omitted because compatible-Anthropic Hermes routing currently requires Chat Completions ([DGX Station][Inference] NemoHermes -z fails "no final response" on Anthropic-compatible route — managed proxy emits duplicate SSE message_start #6289).
Cover a missing-route 404, a model-specific 404, a native Anthropic failure, and an authentication failure.

No new abstraction, configuration, fallback, or compatibility path is introduced.

Type of Change

Code change (feature, bug fix, or refactor)
Code change with doc updates
Doc only (prose changes, no code sample modifications)
Doc only (includes code sample changes)

Quality Gates

Tests added or updated for changed behavior
Existing tests cover changed behavior — justification:
Tests not applicable — justification:
Docs updated for user-facing behavior changes
Docs not applicable — justification: existing provider-validation docs already describe the supported protocol surfaces and recovery flow; this change only narrows when an existing diagnostic is shown.
Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: exact-head maintainer approval pending.
Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
Targeted behavior tests pass for the current change set — npx vitest run --project cli src/lib/onboard/inference-selection-validation.test.ts → 18 passed.
Applicable broad gate passed — not applicable; this is a focused validation diagnostic and regression-test change.
Quality Gates section completed with required justifications or waivers
No secrets, API keys, or credentials committed
npm run docs builds without warnings (doc changes only)
Doc pages follow the style guide (doc changes only)
New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

Bug Fixes
- Improved validation for custom Anthropic-compatible setups when the required OpenAI Chat Completions endpoint is unavailable (e.g., 404), including correct non-interactive failure behavior and more specific messaging.
- Added clearer guidance indicating the correct OpenAI-compatible path must be served, or when to switch to an Anthropic-native agent.
- Refined retry recommendations for native Anthropic 404s (retry model) and for OpenAI surface auth failures (retry credentials).
Tests
- Added new validation test cases covering these 404/403 scenarios and expected recovery outcomes.

… Completions is missing When onboarding an agent that requires the OpenAI Chat Completions surface (such as Deep Agents) against an Anthropic-compatible endpoint that does not serve /v1/chat/completions, the validation failure now prints an actionable next step: use an OpenAI-compatible endpoint, or switch to an Anthropic-native agent (openclaw or hermes). The hint prints before the non-interactive exit and is gated on a missing-surface (404) probe result so genuine auth or server errors are not misdirected. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

coderabbitai · 2026-07-13T12:20:29Z

📝 Walkthrough

Walkthrough

Adds OpenAI Chat Completions surface guidance to custom Anthropic endpoint validation and tests 404, native Anthropic, and authentication failure behavior.

Changes

Anthropic validation guidance

Layer / File(s)	Summary
OpenAI surface detection and guidance `src/lib/onboard/inference-selection-validation.ts`	Computes probe recovery and prints guidance requiring `/v1/chat/completions` plus the OpenClaw command for endpoint-level failures.
Validation behavior tests `src/lib/onboard/inference-selection-validation.test.ts`	Covers non-interactive 404 handling, model-specific 404 recovery, native Anthropic 404 handling, and 403 credential failures with corresponding message assertions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: area: inference

Suggested reviewers: hoyalim, amata-human, sandl99, tonyluo-nv, yimoj

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes add the requested actionable guidance and preserve the non-zero validation failure for Anthropic-only endpoints.
Out of Scope Changes check	✅ Passed	The PR stays focused on onboarding validation guidance and related tests without unrelated feature changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: onboarding now guides users to a compatible endpoint or agent when Chat Completions is missing.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/6765-dcode-anthropic-endpoint-guidance

_{Comment @coderabbitai help to get the list of available commands.}

github-code-quality · 2026-07-13T12:20:43Z

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

_{Updated July 13, 2026 21:20 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

github-actions · 2026-07-13T12:20:46Z

E2E Advisor Recommendation

Required E2E: inference-routing, network-policy, onboard-resume, onboard-repair, cloud-onboard
Optional E2E: None

Dispatch hint: inference-routing,network-policy,onboard-resume,onboard-repair

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

inference-routing: Required floor: validates real custom-endpoint inference routing, failed onboarding cleanup, and host-to-sandbox inference behavior.
network-policy: Required floor: validates that intended inference routes remain usable while policy boundaries deny unintended egress.
onboard-resume: Required floor: validates interrupted onboarding recovery and persisted inference/session state convergence.
onboard-repair: Required floor: validates repair of partial onboarding state and cleanup without affecting unrelated resources.
cloud-onboard (high): Changed onboard, trace timing, scorecard, or E2E workflow code can affect cloud onboard wall-clock behavior and should refresh the trusted cloud-onboard trace timing signal.

Optional E2E

None.

New E2E recommendations

inference-policy (medium): Current unit coverage verifies the 404-specific agent-switch message, but a live CLI flow should prove a custom Anthropic-compatible selection routed to OpenAI completions emits the safe guidance, fails non-interactively, redacts credentials, and leaves no sandbox behind.
- Suggested test: Add a PR-safe inference-routing live case using a fake Anthropic-compatible endpoint whose OpenAI Chat Completions route returns 404; assert non-interactive onboarding fails, prints the OpenAI-compatible/switch-agent guidance, redacts the submitted credential, and cleans up the sandbox.

Dispatch hint

Workflow: e2e.yaml
jobs input: inference-routing,network-policy,onboard-resume,onboard-repair

github-actions · 2026-07-13T12:22:35Z

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Findings: 0 required · 0 warnings · 0 optional suggestions
Since last review: 1 prior item resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

wscurran · 2026-07-13T14:49:19Z

✨ Thanks for the fix, @laitingsheng. Adding actionable guidance when an Anthropic-only endpoint is used with an OpenAI-completions agent will help users self-correct. Ready for maintainer review.

Related open issues:

#6765 [All Platforms][Onboard] dcode onboard with Anthropic-only endpoint exits correctly but omits actionable guidance to use openclaw or hermes

Hermes on a compatible-Anthropic endpoint is force-routed to the OpenAI Completions surface by resolveAgentInferenceApi (src/lib/inference/config.ts, #6289 duplicate message_start workaround), so recommending `nemohermes onboard` as an Anthropic-native fallback would hit the same missing /v1/chat/completions failure again. Guidance now only points to the supported OpenClaw path; the guidance test asserts nemohermes is absent. Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

cjagwani

Requesting one focused correctness change on exact head d40eb014cec20f591f0466591f351008acb8c747.

[P2] A raw HTTP 404 does not prove that /v1/chat/completions is absent. A valid Chat Completions endpoint can return 404 because the selected model is unknown or unavailable. NemoClaw already distinguishes that case: classifyValidationFailure recognizes model-not-found messages before its generic endpoint-404 classification, and this caller allows model retry. With a probe failure such as HTTP 404 + model foo not found, the current patch prints “the endpoint does not serve it” and recommends switching endpoints/agents while recovery simultaneously offers a model retry.

Please gate the new guidance on the existing endpoint failure classification (rather than status alone) and add a negative test for a model-specific 404. The bare-route 404 and auth 403 cases should retain their current behavior.

Separately, the implementation is correct to omit Hermes: current Hermes custom-Anthropic routing also requires Chat Completions due #6289. Please reconcile the PR body and linked issue, which still promise an OpenClaw-or-Hermes fallback, before closure.

github-actions · 2026-07-13T18:09:55Z

E2E Target Results — ✅ All requested tests passed

Run: 29272804761
Workflow ref: fix/6765-dcode-anthropic-endpoint-guidance
Requested targets: (default — all supported)
Requested test IDs: inference-routing,network-policy,onboard-resume,onboard-repair,cloud-onboard
Summary: 5 passed, 0 failed, 0 cancelled, 0 skipped, 0 unknown

Test	Result
cloud-onboard	✅ success
inference-routing	✅ success
network-policy	✅ success
onboard-repair	✅ success
onboard-resume	✅ success

Signed-off-by: Charan Jagwani <cjagwani@nvidia.com>

laitingsheng self-assigned this Jul 13, 2026

laitingsheng removed their assignment Jul 13, 2026

laitingsheng added the v0.0.82 Release target label Jul 13, 2026

cjagwani requested changes Jul 13, 2026

View reviewed changes

cjagwani self-assigned this Jul 13, 2026

fix(onboard): distinguish model-specific 404 guidance

87c0c4a

Signed-off-by: Charan Jagwani <cjagwani@nvidia.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(onboard): guide users to a compatible endpoint or agent when Chat Completions is missing#6769

fix(onboard): guide users to a compatible endpoint or agent when Chat Completions is missing#6769
laitingsheng wants to merge 3 commits into
mainfrom
fix/6765-dcode-anthropic-endpoint-guidance

laitingsheng commented Jul 13, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

github-code-quality Bot commented Jul 13, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 13, 2026 •

edited

Loading

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

github-actions Bot commented Jul 13, 2026 •

edited

Loading

Uh oh!

wscurran commented Jul 13, 2026

Uh oh!

cjagwani left a comment

Uh oh!

github-actions Bot commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

laitingsheng commented Jul 13, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Quality Gates

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

github-code-quality Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Overview

TypeScript / code-coverage/plugin

Uh oh!

github-actions Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

github-actions Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor — No blocking findings

Uh oh!

wscurran commented Jul 13, 2026

Uh oh!

cjagwani left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 13, 2026

E2E Target Results — ✅ All requested tests passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

laitingsheng commented Jul 13, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

github-code-quality Bot commented Jul 13, 2026 •

edited

Loading

github-actions Bot commented Jul 13, 2026 •

edited

Loading

github-actions Bot commented Jul 13, 2026 •

edited

Loading