docs(config): add worked examples for hosted /v1 gateways and MindsHub (#10362, #9746)

[now-ing]

What this PR does

Adds two worked examples to the OpenAI-compatible section of docs/users/configuration/model-providers.md:

1. A hosted /v1 endpoint example with the three details the issue found easy to get wrong called out explicitly: security.auth.selectedType must be "openai", baseUrl is the /v1 root (not the full chat-completions path), and a custom provider id is skipped by /model unless mapped through the top-level providerProtocol setting. Includes the full security.auth + modelProviders.openai JSON shape and an envKey-over-apiKey note.
2. A MindsHub gateway example covering both of its protocol faces — an OpenAI chat-completions entry under modelProviders.openai and an Anthropic messages entry under modelProviders.anthropic — sharing one MINDSHUB_API_KEY env var, alongside the existing OpenRouter/Requesty examples.

All key names (security.auth.selectedType, providerProtocol, envKey fallback, modelProviders array shape) were verified against the current settings schema and the surrounding documentation rather than written from memory; the model ids in the MindsHub example are explicitly marked as placeholders since the gateway catalog changes.

Why it's needed

Closes #10362 and closes #9746 — both status/ready-for-human documentation gaps on the same page. The hosted-/v1 example gives users copying from the existing OpenRouter/Requesty entries a correct full security.auth shape (the three failure modes in the issue all produce "model never appears / wrong protocol" symptoms), and the MindsHub entry is the requested addition alongside the existing aggregator examples.

Reviewer Test Plan

How to verify

Docs-only change. Open docs/users/configuration/model-providers.md:

1. Confirm the two new subsections sit at the end of the ### OpenAI-compatible providers (openai) section, before ### Anthropic (anthropic).
2. Cross-check security.auth.selectedType / providerProtocol / envKey semantics against the schema table in settings.md and the custom-provider-ids section of the same page.
3. npx prettier --check docs/users/configuration/model-providers.md passes.

Evidence (Before & After)

N/A (docs-only; no behavior change)

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	N/A
🐧 Linux	N/A

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

@now-ing thanks for picking up both of these. I have to stop it at the gate, and the template is only the first reason — please read the second one before respinning, because filling in the template alone won't make this mergeable.

1. The PR body is missing required template sections. Compared with .github/pull_request_template.md, this body has What this PR does, Why it's needed and the Test Plan, but not ## Risk & Scope (main risk / not validated / breaking changes), not ## Linked Issues (your Closes #10362 and closes #9746 currently sits inside Why it's needed), and not the Chinese <details> translation. Those three are part of the template, not optional extras — only ### Environment is marked optional.

2. Both linked issues were already triaged, and neither recommendation was to accept these examples.

• #9746 (MindsHub) was closed out with "recommend not accepting the named MindsHub example at this time — there is no documentation gap to fill, and named provider placement is endorsement-gated." The issue author then disclosed an affiliation with MindsHub. Both issues are still open and still carry status/ready-for-human, i.e. they were parked for a human decision, not green-lit.
• #10362 (hosted /v1) was triaged the same way: the three gotchas were checked against the current docs and found already covered — providerProtocol has its own section plus a warning box, security.auth.selectedType is documented in auth.md and in the Resolution Layers table, and the openai/ prefix point is a usage mistake rather than a docs gap. The one sliver judged worth landing was a single generic line saying baseUrl is the /v1 root. To your credit this PR drops the PZERO name, but it still restates the two gotchas that were already documented.

The blocker on the MindsHub half is CONTRIBUTING.md § Adding a Provider Preset: "A built-in preset is an endorsement, not just a convenience. Users route API keys and full prompt data through these endpoints, so the bar is high." Tier 1 requires affiliation disclosure, operational maturity, and organic user demand — "not just a self-listing". Providers below that bar use the custom-provider flow, which the same section says needs "no code change or project endorsement."

That gate is about prominence, and a named subsection in this page is prominence. Every third-party gateway currently named in model-providers.md maps to an approved preset in packages/core/src/providers/presets/ (openrouter.ts, requesty.ts, deepseek.ts, grok.ts, minimax.ts, modelscope.ts, moonshot.ts, zai.ts, idealab.ts). A repo-wide search finds MindsHub nowhere — no prior issue other than #9746, no PR, no code. Adding it beside the Tier-1-approved names grants comparable visibility without the process, and you are not the person who asked for it in #9746, so your own relationship to MindsHub is unstated either way.

What I'd suggest: split it. The generic hosted-/v1 note is the part with a real, already-agreed docs gap — land that on its own, small. The MindsHub subsection is a listing decision that belongs to a maintainer; it should not ride along in a docs PR. Maintainers: the endorsement call above is grounded in current project policy, and it is yours to override — I have no owner to route this to (the assignment policy has no documentation area, and there are no human reviewers on this PR yet), so it is flagged here rather than assigned.

3. If the vendor section does get a maintainer nod, two things in it are wrong as written.

• The hosted-/v1 example teaches a deprecated config shape. It hardcodes security.auth.apiKey and security.auth.baseUrl — the exact two fields this page already carries a warning box about: "Deprecation of security.auth.apiKey and security.auth.baseUrl … is deprecated … It is strongly recommended to migrate to modelProviders." It also contradicts the page's own Overview ("Credentials are never persisted in settings; the runtime reads them from process.env[envKey]") and your own next sentence ("Prefer envKey over a literal apiKey"), since the modelProviders.openai entry in that same block has no envKey. A worked example that a searcher copies is the worst place to model a shape we are actively migrating off. The description says every key name was verified against the current schema and surrounding documentation — this one wasn't.
• The MindsHub anthropic entry uses baseUrl: "https://api.mindshub.ai/v1", but #9746 specified host-only (https://api.mindshub.ai) precisely because "the Anthropic client appends /v1/messages itself." That matches the code: anthropicContentGenerator.ts passes baseUrl straight into new Anthropic({ baseURL }), and its resolveEffectiveBaseUrl treats the SDK default as host-only (https://api.anthropic.com, no /v1). So /v1 looks like it would produce /v1/v1/messages. I could not confirm that by execution — this review is static and never runs PR code — and I'll note the page's existing Anthropic examples also carry /v1, so one of the two is wrong and worth settling before anyone copies either. Separately, an anthropic provider entry living inside the "OpenAI-compatible providers" section is not where a reader configuring Claude-wire routing will look for it.

4. No CI evidence exists for this commit. Qwen Code CI and Security Checks both completed as action_required, which means they are waiting on a maintainer to approve the fork's workflow run — they never executed. So the prettier --check you ask reviewers to confirm in the test plan has not actually run either. Nothing here is a claim that the change is broken; it is a note that there is currently no test signal at all on 34989f1.

中文说明

@now-ing 感谢跟进这两个 issue。这个 PR 我需要在 gate 阶段拦下，而且模板只是第一个原因——请先看第二点再重做，因为仅补齐模板并不能让它可合并。

1. PR 描述缺少模板必填章节。 对照 .github/pull_request_template.md：当前描述有 What this PR does、Why it's needed 和 Test Plan，但缺少 ## Risk & Scope（主要风险 / 未验证项 / 破坏性变更）、## Linked Issues（你的 Closes #10362 and closes #9746 目前写在 Why it's needed 里），以及中文 <details> 翻译。这三项都是模板组成部分，只有 ### Environment 标注为可选。

2. 两个关联 issue 都已完成 triage，结论都不是"接受这些示例"。

• **#9746（MindsHub）**的结论是："暂不建议收录 MindsHub 具名示例——不存在需要填补的文档缺口，且具名 provider 展示受背书门槛约束。" issue 作者随后披露了自己与 MindsHub 的关联关系。两个 issue 至今仍是 open，且都带 status/ready-for-human 标签——也就是留给人类决策，而不是已经放行。
• **#10362（托管 /v1）**结论相同：三个易错点已对照当前文档逐条核查，均已覆盖——providerProtocol 有独立章节和警告框，security.auth.selectedType 在 auth.md 和 Resolution Layers 表中都有说明，openai/ 前缀属于用法错误而非文档缺口。当时判断唯一值得补的，是一行通用说明：baseUrl 应为 /v1 根路径。本 PR 没有具名 PZERO，这点做得对，但仍然重述了那两个已有文档覆盖的易错点。

MindsHub 这部分的关键约束在 CONTRIBUTING.md《Adding a Provider Preset》："内置 preset 是一种背书，而不仅仅是便利。用户会将 API key 和完整 prompt 数据经由这些端点传输，因此门槛很高。" Tier 1 要求关联关系披露、运营成熟度，以及自然用户需求——"而非自我挂名"。未达 Tier 1 的 provider 走 Custom Provider 流程，同一章节明确说明该路径"无需代码改动或项目背书"。

这道门槛管的是曝光度，而在本页面开设具名小节就是曝光度。目前 model-providers.md 中出现的每个第三方网关都对应 packages/core/src/providers/presets/ 下已批准的 preset（openrouter.ts、requesty.ts、deepseek.ts、grok.ts、minimax.ts、modelscope.ts、moonshot.ts、zai.ts、idealab.ts）。全仓库搜索找不到 MindsHub——除 #9746 外无历史 issue、无 PR、无代码。把它与已获 Tier-1 批准的名字并列，等于绕过流程授予同等曝光；而且你并非 #9746 的提出者，你与 MindsHub 是否存在关联也无从得知。

建议做法： 拆开。通用的托管 /v1 说明是真正已被认可存在缺口的那部分——单独提一个小 PR 合入即可。MindsHub 小节属于收录决策，应由维护者裁定，不宜夹带在 docs PR 里。维护者：上述背书判断依据现行项目规则，是否推翻由你们决定——本次没有可路由的负责人（分配策略中没有 documentation 领域，PR 上也还没有人类 reviewer），因此只在此标记，未做指派。

3. 如果维护者认可保留厂商小节，其中有两处按现状是错误的。

• 托管 /v1 示例教的是已废弃的配置形态。 它硬编码了 security.auth.apiKey 和 security.auth.baseUrl——正是本页面已有警告框点名的两个字段："security.auth.apiKey 与 security.auth.baseUrl 的废弃……已废弃……强烈建议迁移到 modelProviders。" 它同时与本页 Overview（"凭证不会持久化在 settings 中；运行时从 process.env[envKey] 读取"）以及你自己下一句（"优先用 envKey 而非字面量 apiKey"）矛盾——同一个代码块里的 modelProviders.openai 条目并没有 envKey。会被搜索者直接复制的"完整示例"，恰恰是最不该示范我们正 actively 迁移掉的形态的地方。PR 描述称所有 key 名都对照当前 schema 与周边文档核验过——这一处没有。
• MindsHub 的 anthropic 条目用了 baseUrl: "https://api.mindshub.ai/v1"，而 #9746 明确要求只写主机名（https://api.mindshub.ai），理由正是*"Anthropic 客户端会自行拼接 /v1/messages"。这与代码一致：anthropicContentGenerator.ts 把 baseUrl 原样传给 new Anthropic({ baseURL })，其 resolveEffectiveBaseUrl 也把 SDK 默认值视为主机名（https://api.anthropic.com，不带 /v1）。因此带上 /v1 看起来会得到 /v1/v1/messages。我无法通过实际执行确认——本次为静态审查，不会运行 PR 代码——另外需说明：页面现有的 Anthropic 示例同样带 /v1，所以两者必有一处是错的，在有人复制之前值得先厘清。此外，把 anthropic provider 条目放在"OpenAI-compatible providers"*小节内，也不是配置 Claude 协议路由的读者会去找的位置。

4. 该 commit 没有任何 CI 证据。 Qwen Code CI 与 Security Checks 的结论都是 action_required，即等待维护者批准 fork 的 workflow 运行——它们从未真正执行。因此你在测试计划中请 reviewer 确认的 prettier --check 实际上也没有跑过。这不是在断言改动有问题，只是说明 34989f1 上目前完全没有测试信号。

— Qwen Code · qwen3.8-max-2026-09-02

[qwen-code-ci-bot]

📄 Docs-only change — the automatic review ran at --effort medium (verified findings, no reverse audit; medium posts no inline comments). Outcome:

Review complete: pr-10997 — Request changes, not posted (1 Critical, 3 Suggestion)

Reviewed head: 34989f143e95802262a4568b5d70915365f891d6. Full report in the workflow run. For a full high-effort review with inline comments, comment @qwen-code /review.

中文说明

📄 纯文档变更 —— 自动评审以 --effort medium 运行（发现已验证、无反向审计；medium 不发布行内评论），结果见上方引用行。评审的 head：34989f143e95802262a4568b5d70915365f891d6。完整报告见 workflow 运行；如需带行内评论的完整高强度（high-effort）评审，请评论 @qwen-code /review。