[codex] refresh integration and settings docs for current UI and provider coverage#398
Merged
[codex] refresh integration and settings docs for current UI and provider coverage#398
Conversation
github-actions
bot
added
area: docs
📝 WalkthroughWalkthroughThis PR adds OAuth management documentation and management-API endpoints, restructures upstream integration guidance into three modes (panel aggregators, official presets, OAuth), updates multiple docs and site navigation, and extends Changes
Sequence Diagram(s)sequenceDiagram
participant User as "User / Admin"
participant UI as "Management UI"
participant API as "Management API"
participant OAuth as "OAuth Provider"
participant DB as "DB / Connections Store"
rect rgba(200,200,255,0.5)
User->>UI: Click "Start OAuth" (choose provider)
UI->>API: POST /api/oauth/providers/:provider/start
API->>OAuth: Redirect / Auth request
end
rect rgba(200,255,200,0.5)
OAuth-->>User: Authorization page
User->>OAuth: Grant access (consent)
OAuth->>API: Redirect/Callback (state)
API->>DB: Persist connection / tokens
API->>UI: Notify success (session/state)
UI->>User: Show connected account
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
.env.example (2)
9-11: Add inline “required when enabled” hints for provider secretsThese keys are easy to misconfigure (e.g., Gemini requires both ID+secret; Claude secret has no fallback). A short inline note here would reduce setup errors.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env.example around lines 9 - 11, Update the .env.example entries for CLAUDE_CLIENT_SECRET, GEMINI_CLI_CLIENT_ID, and GEMMINI_CLI_CLIENT_SECRET (note: variable names in the diff) to include short inline hints indicating they are "required when enabled" and any provider-specific requirements (e.g., "Gemini requires both ID + secret; Claude secret has no fallback") so users see at-a-glance when each secret must be supplied.
7-11: Optional: reorder new keys to satisfy dotenv-linter ordering checksStatic analysis flags these additions as unordered. If lint cleanliness is required in CI, reorder keys per project convention.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env.example around lines 7 - 11, The added environment keys (CODEX_CLIENT_ID, CLAUDE_CLIENT_ID, CLAUDE_CLIENT_SECRET, GEMINI_CLI_CLIENT_ID, GEMINI_CLI_CLIENT_SECRET) are out of order for the project's dotenv-linter; reorder these entries to match the repository's .env key ordering convention (e.g., alphabetical or the established grouping used in the file) so they pass dotenv-linter checks, keeping the exact key names and any surrounding blank lines intact.docs/k3s-update-center.md (1)
374-374: 建议把“对齐的 token”改成明确变量名。Line 374 可直接写成
DEPLOY_HELPER_TOKEN（含主服务别名UPDATE_CENTER_HELPER_TOKEN）与 helper 侧DEPLOY_HELPER_TOKEN必须一致，减少歧义。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/k3s-update-center.md` at line 374, 将文档中模糊的“对齐的 token”替换为明确的环境变量名，直接写成 DEPLOY_HELPER_TOKEN（并标注主服务的别名 UPDATE_CENTER_HELPER_TOKEN），并说明主服务与 helper 侧必须使用相同的 DEPLOY_HELPER_TOKEN 值以避免歧义；在涉及生成、配置或示例的部分明确指出两端变量名和一致性要求（DEPLOY_HELPER_TOKEN 与 UPDATE_CENTER_HELPER_TOKEN 对应且相同）。
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.env.example:
- Line 4: Update .env.example so ACCOUNT_CREDENTIAL_SECRET is not shipped empty
and clearly instructs developers to set a strong secret (do not leave blank);
explicitly replace the empty value with a placeholder like
ACCOUNT_CREDENTIAL_SECRET=REPLACE_WITH_STRONG_RANDOM_SECRET and a short note
that it must be a cryptographically-random secret (e.g., 32+ bytes) and must not
be re-used, because leaving it blank triggers the fallback in the config logic
(used by src/server/config.ts) which causes account credential encryption to
fall back to AUTH_TOKEN/hardcoded defaults and weakens security in
accountCredentialService.ts; ensure the example warns to generate the secret
securely and keep it out of source control.
In `@docs/upstream-integration.md`:
- Line 352: Change the two out-of-order headings "#### 当前内置预设" and the other
"#### ..." occurrence (the headings flagged at lines 352 and 382) from level 4
to level 3 to maintain proper markdown heading hierarchy (use "### 当前内置预设" and
the corresponding "### ..." for the other occurrence); update both heading
tokens so markdownlint MD001 no longer reports a heading level jump.
---
Nitpick comments:
In @.env.example:
- Around line 9-11: Update the .env.example entries for CLAUDE_CLIENT_SECRET,
GEMINI_CLI_CLIENT_ID, and GEMMINI_CLI_CLIENT_SECRET (note: variable names in the
diff) to include short inline hints indicating they are "required when enabled"
and any provider-specific requirements (e.g., "Gemini requires both ID + secret;
Claude secret has no fallback") so users see at-a-glance when each secret must
be supplied.
- Around line 7-11: The added environment keys (CODEX_CLIENT_ID,
CLAUDE_CLIENT_ID, CLAUDE_CLIENT_SECRET, GEMINI_CLI_CLIENT_ID,
GEMINI_CLI_CLIENT_SECRET) are out of order for the project's dotenv-linter;
reorder these entries to match the repository's .env key ordering convention
(e.g., alphabetical or the established grouping used in the file) so they pass
dotenv-linter checks, keeping the exact key names and any surrounding blank
lines intact.
In `@docs/k3s-update-center.md`:
- Line 374: 将文档中模糊的“对齐的 token”替换为明确的环境变量名，直接写成 DEPLOY_HELPER_TOKEN（并标注主服务的别名
UPDATE_CENTER_HELPER_TOKEN），并说明主服务与 helper 侧必须使用相同的 DEPLOY_HELPER_TOKEN
值以避免歧义；在涉及生成、配置或示例的部分明确指出两端变量名和一致性要求（DEPLOY_HELPER_TOKEN 与
UPDATE_CENTER_HELPER_TOKEN 对应且相同）。
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e554fa0a-2e1c-4080-8f02-a652d2e75c58
📒 Files selected for processing (12)
.env.exampleREADME.mddocs/.vitepress/config.tsdocs/README.mddocs/configuration.mddocs/faq.mddocs/getting-started.mddocs/index.mddocs/k3s-update-center.mddocs/management-api.mddocs/oauth.mddocs/upstream-integration.md
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.env.example (1)
6-13: Clarify OAuth credential requirements in the comment.The comment states "Claude requires a client secret with no fallback" but all OAuth fields are left blank. This could confuse users about which credentials are truly required versus optional.
Consider rewording to make the requirement clearer:
💡 Suggested improvement
-# Optional OAuth overrides. Fill the matching credentials when an override is enabled; Claude requires a client secret with no fallback. +# Optional OAuth provider credential overrides (see docs/oauth.md). +# Claude: both CLAUDE_CLIENT_ID and CLAUDE_CLIENT_SECRET are required (no fallback). +# Codex: only CODEX_CLIENT_ID is required. +# Gemini CLI: both GEMINI_CLI_CLIENT_ID and GEMINI_CLI_CLIENT_SECRET are required together. CLAUDE_CLIENT_ID= CLAUDE_CLIENT_SECRET= -# Codex OAuth override only needs CODEX_CLIENT_ID. CODEX_CLIENT_ID= -# Gemini CLI override requires both GEMINI_CLI_CLIENT_ID and GEMINI_CLI_CLIENT_SECRET together. GEMINI_CLI_CLIENT_ID= GEMINI_CLI_CLIENT_SECRET=🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env.example around lines 6 - 13, Update the .env.example comment to clearly indicate which OAuth entries are optional vs required: explicitly mark CLAUDE_CLIENT_ID and CLAUDE_CLIENT_SECRET as required when using Claude and note that CLAUDE_CLIENT_SECRET has no fallback, mark CODEX_CLIENT_ID as optional/only-needed for Codex override, and mark GEMINI_CLI_CLIENT_ID and GEMINI_CLI_CLIENT_SECRET as a paired optional override for the Gemini CLI (both required together). Reference the exact variable names CLAUDE_CLIENT_ID, CLAUDE_CLIENT_SECRET, CODEX_CLIENT_ID, GEMINI_CLI_CLIENT_ID, and GEMINI_CLI_CLIENT_SECRET in the updated comment and keep examples minimal so users aren’t confused by blank entries.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/k3s-update-center.md`:
- Line 32: 将“这张对照表”改为更自然的量词搭配“这份对照表”：在 docs/k3s-update-center.md
中定位包含短语“建议先看下面这张对照表”的句子并替换为“建议先看下面这份对照表”，保持原句其他部分不变以改善读感和措辞准确性。
---
Nitpick comments:
In @.env.example:
- Around line 6-13: Update the .env.example comment to clearly indicate which
OAuth entries are optional vs required: explicitly mark CLAUDE_CLIENT_ID and
CLAUDE_CLIENT_SECRET as required when using Claude and note that
CLAUDE_CLIENT_SECRET has no fallback, mark CODEX_CLIENT_ID as
optional/only-needed for Codex override, and mark GEMINI_CLI_CLIENT_ID and
GEMINI_CLI_CLIENT_SECRET as a paired optional override for the Gemini CLI (both
required together). Reference the exact variable names CLAUDE_CLIENT_ID,
CLAUDE_CLIENT_SECRET, CODEX_CLIENT_ID, GEMINI_CLI_CLIENT_ID, and
GEMINI_CLI_CLIENT_SECRET in the updated comment and keep examples minimal so
users aren’t confused by blank entries.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 893ad598-1dc7-4d80-a812-442fd5cce2ab
📒 Files selected for processing (3)
.env.exampledocs/k3s-update-center.mddocs/upstream-integration.md
| ## 先判断：你需不需要看这页 | ||
| ## 配置到底在哪里配 | ||
|
|
||
| 更新中心涉及后台页面、主服务环境变量、helper 部署清单三层配置，最容易混淆，建议先看下面这张对照表。 |
There was a problem hiding this comment.
措辞可再精确：将“这张对照表”改为“这份对照表”。
Line 32 的量词搭配略不自然，建议改成“建议先看下面这份对照表”，读感更顺。
🧰 Tools
🪛 LanguageTool
[uncategorized] ~32-~32: “张” 不能与 “对照表” 搭配，请更换量词。
Context: ...台页面、主服务环境变量、helper 部署清单三层配置，最容易混淆，建议先看下面这张对照表。 | 你要配什么 | 去哪里配 | 说明 | |------|------|...
(wa5)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/k3s-update-center.md` at line 32, 将“这张对照表”改为更自然的量词搭配“这份对照表”：在
docs/k3s-update-center.md
中定位包含短语“建议先看下面这张对照表”的句子并替换为“建议先看下面这份对照表”，保持原句其他部分不变以改善读感和措辞准确性。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR refreshes the public docs so they match the current Metapi product surface instead of the older, narrower documentation set.
Users were running into two kinds of drift. First, the upstream integration docs no longer reflected the real set of supported site types and entry points: CPA /
cliproxyapi, official vendor presets such as Coding Plan / DeepSeek / Moonshot / MiniMax / ModelScope, AI request endpoint pools, and the dedicated OAuth management flow were either missing or underexplained. Second, the settings and K3s update-center docs still leaned too heavily on environment-variable explanations even though much of the real operator workflow has already moved into the web UI. That mismatch made the product feel harder to configure than it actually is, and it also caused the docs tone to drift away from the more user-facing style already used in the upstream integration guide.This change updates the docs around the actual user journey. The upstream integration guide now keeps its tutorial-style structure and screenshots while expanding coverage for current platform types, CPA, vendor presets, OAuth entry points, AI request address pools, and the newer detection rules. A new OAuth guide explains the dedicated OAuth management page, supported providers, callback expectations, and the difference between provider authorization and ordinary site/API-key onboarding. The configuration docs now describe the real UI-first flow for ordinary users while still preserving the environment-variable details that matter for first boot, deployment-time setup, OAuth client overrides, and Deploy Helper wiring. The K3s update-center guide now makes the UI-vs-env split explicit, so operators know which fields belong in “Settings -> Update Center” and which ones still belong in service env or helper manifests.
The supporting docs and entry points were updated as well so the new pages are discoverable: the docs navigation, docs maintenance map, getting-started guide, FAQ, management API docs, docs index, README, and
.env.examplewere brought in line with the expanded coverage.Validation:
npm run docs:buildSummary by CodeRabbit
New Features
Documentation