From f4606c23637b1c6308329fcb6722b59bee483a51 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 06:56:48 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/oauth.md | 166 ++++++++++++++++++----------------- 1 file changed, 84 insertions(+), 82 deletions(-) diff --git a/docs/zh-CN/concepts/oauth.md b/docs/zh-CN/concepts/oauth.md index ae59a158e..78a05d379 100644 --- a/docs/zh-CN/concepts/oauth.md +++ b/docs/zh-CN/concepts/oauth.md @@ -1,185 +1,187 @@ --- read_when: - 你想端到端了解 OpenClaw OAuth - - 你遇到了令牌失效 / 登出问题 - - 你想了解 Claude CLI 或 OAuth 认证流程 - - 你想要多个账户或配置文件路由 + - 你遇到了令牌失效或退出登录问题 + - 你想使用 Claude CLI 或 OAuth 认证流程 + - 你想使用多个账户或配置文件路由 summary: OpenClaw 中的 OAuth：令牌交换、存储和多账户模式 title: OAuth x-i18n: - generated_at: "2026-04-25T05:54:16Z" - model: gpt-5.4 + generated_at: "2026-04-29T06:56:18Z" + model: gpt-5.5 provider: openai - source_hash: c793c52f48a3f49c0677d8e55a84c2bf5cdf0d385e6a858f26c0701d45583211 + source_hash: 493251e4341489e5fba9ab561d71200245d26888e10f153239d2ac8fc8fe1830 source_path: concepts/oauth.md - workflow: 15 + workflow: 16 --- -OpenClaw 支持通过 OAuth 提供“订阅认证”，适用于提供该能力的提供商 -（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic，目前更实际的划分 -如下： +OpenClaw 支持通过 OAuth 使用“订阅凭证”，适用于提供该能力的提供商 +（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic，实际划分 +现在是： -- **Anthropic API 密钥**：标准 Anthropic API 计费 -- **Anthropic Claude CLI / OpenClaw 内的订阅认证**：Anthropic 员工 - 告诉我们，这种用法现在再次被允许 +- **Anthropic API 密钥**：正常的 Anthropic API 计费 +- **OpenClaw 内的 Anthropic Claude CLI / 订阅凭证**：Anthropic 员工 + 告诉我们，这种用法已再次被允许 -OpenAI Codex OAuth 已明确支持在 OpenClaw 这样的外部工具中使用。本页说明： +OpenAI Codex OAuth 明确支持在 OpenClaw 这类外部工具中使用。本页说明： -对于生产环境中的 Anthropic，API 密钥认证仍是更安全、推荐的路径。 +对于生产环境中的 Anthropic，API 密钥凭证是更安全的推荐路径。 -- OAuth **令牌交换** 的工作方式（PKCE） +- OAuth **令牌交换**如何工作（PKCE） - 令牌**存储**在哪里（以及原因） -- 如何处理**多个账户**（配置文件 + 每会话覆盖） +- 如何处理**多个账号**（配置文件 + 按会话覆盖） -OpenClaw 也支持自带 OAuth 或 API 密钥 -流程的**提供商插件**。可通过以下命令运行： +OpenClaw 也支持**提供商插件**，这些插件会附带自己的 OAuth 或 API 密钥 +流程。通过以下命令运行： ```bash openclaw models auth login --provider ``` -## 令牌汇聚点（为什么存在） +## 令牌接收端（为什么存在） -OAuth 提供商通常会在登录/刷新流程中签发一个**新的刷新令牌**。某些提供商（或 OAuth 客户端）在为同一用户/应用签发新刷新令牌时，可能会使旧的刷新令牌失效。 +OAuth 提供商通常会在登录/刷新流程中生成一个**新的刷新令牌**。某些提供商（或 OAuth 客户端）可能会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。 -实际表现： +实际现象： -- 你同时通过 OpenClaw _以及_ Claude Code / Codex CLI 登录 → 之后其中一个会随机出现“已登出” +- 你通过 OpenClaw _以及_ Claude Code / Codex CLI 登录 → 之后其中一个会随机“退出登录” -为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为一个**令牌汇聚点**： +为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌接收端**： -- 运行时从**一个位置**读取凭证 -- 我们可以保留多个配置文件，并以确定性的方式进行路由 -- 外部 CLI 复用是提供商特定的：Codex CLI 可以引导创建一个空的 - `openai-codex:default` 配置文件，但一旦 OpenClaw 已有本地 OAuth 配置文件， - 本地刷新令牌就是规范来源；其他集成可以继续由外部管理， - 并重新读取其 CLI 认证存储 +- 运行时从**一个位置**读取凭据 +- 我们可以保留多个配置文件，并以确定性方式路由它们 +- 外部 CLI 复用是提供商特定的：Codex CLI 可以引导一个空的 + `openai-codex:default` 配置文件，但一旦 OpenClaw 拥有本地 OAuth 配置文件， + 本地刷新令牌就是权威来源；其他集成可以继续由外部管理，并重新读取它们的 + CLI 凭证存储 +- 已经知道已配置提供商集合的 Status 和启动路径，会将外部 CLI 发现限定在 + 该集合内，因此单提供商设置不会探测无关的 CLI 登录存储 ## 存储（令牌存放位置） 密钥按**每个智能体**存储： -- 认证配置文件（OAuth + API 密钥 + 可选的值级引用）：`~/.openclaw/agents//agent/auth-profiles.json` +- 凭证配置文件（OAuth + API 密钥 + 可选的值级引用）：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版兼容文件：`~/.openclaw/agents//agent/auth.json` - （发现静态 `api_key` 条目时会被清除） + （发现静态 `api_key` 条目时会清除） -仅用于导入的旧版文件（仍受支持，但不是主存储）： +仅用于旧版导入的文件（仍受支持，但不是主存储）： -- `~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`） +- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`） -以上所有路径也都遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/zh-CN/gateway/configuration-reference#auth-storage) +以上全部也遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/zh-CN/gateway/configuration-reference#auth-storage) -关于静态 SecretRef 和运行时快照激活行为，请参见[密钥管理](/zh-CN/gateway/secrets)。 +关于静态密钥引用和运行时快照激活行为，请参阅 [密钥管理](/zh-CN/gateway/secrets)。 ## Anthropic 旧版令牌兼容性 -Anthropic 的公开 Claude Code 文档说明，直接使用 Claude Code 仍然受 -Claude 订阅额度约束，而 Anthropic 员工告诉我们，像 OpenClaw 这样使用 Claude -CLI 的方式现在再次被允许。因此，除非 Anthropic 发布新的政策， -否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成中被认可的方式。 +Anthropic 的公开 Claude Code 文档表示，直接使用 Claude Code 会保持在 +Claude 订阅限制内，并且 Anthropic 员工告诉我们，OpenClaw 风格的 Claude +CLI 用法已再次被允许。因此，除非 Anthropic 发布新政策，否则 OpenClaw +会将此集成中的 Claude CLI 复用和 `claude -p` 用法视为已获认可。 -关于 Anthropic 当前直接使用 Claude Code 的套餐文档，请参见 [在你的 Pro 或 Max -套餐中使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) -以及 [在你的 Team 或 Enterprise -套餐中使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)。 +关于 Anthropic 当前的直接 Claude Code 计划文档，请参阅 [通过你的 Pro 或 Max +计划使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) +和 [通过你的 Team 或 Enterprise +计划使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)。 -如果你想在 OpenClaw 中使用其他订阅式选项，请参见 [OpenAI +如果你想在 OpenClaw 中使用其他订阅式选项，请参阅 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud Coding Plan](/zh-CN/providers/qwen)、[MiniMax Coding Plan](/zh-CN/providers/minimax) -以及 [Z.AI / GLM Coding Plan](/zh-CN/providers/glm)。 +和 [Z.AI / GLM Coding Plan](/zh-CN/providers/glm)。 -OpenClaw 也将 Anthropic setup-token 作为受支持的基于令牌的认证路径公开提供，但在可用时，现在更优先推荐复用 Claude CLI 和使用 `claude -p`。 +OpenClaw 也将 Anthropic setup-token 作为受支持的令牌凭证路径公开，但现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。 ## Anthropic Claude CLI 迁移 -OpenClaw 再次支持复用 Anthropic Claude CLI。如果主机上已经有本地 +OpenClaw 再次支持 Anthropic Claude CLI 复用。如果你已经在主机上有本地 Claude 登录，新手引导/配置可以直接复用它。 ## OAuth 交换（登录如何工作） -OpenClaw 的交互式登录流程是在 `@mariozechner/pi-ai` 中实现的，并接入了向导/命令。 +OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并接入向导/命令。 ### Anthropic setup-token 流程形态： -1. 从 OpenClaw 启动 Anthropic setup-token，或粘贴令牌 -2. OpenClaw 将生成的 Anthropic 凭证存储到一个认证配置文件中 -3. 模型选择保持为 `anthropic/...` -4. 现有的 Anthropic 认证配置文件仍可用于回退/顺序控制 +1. 从 OpenClaw 启动 Anthropic setup-token 或 paste-token +2. OpenClaw 将生成的 Anthropic 凭据存储到凭证配置文件中 +3. 模型选择保持在 `anthropic/...` +4. 现有 Anthropic 凭证配置文件仍可用于回滚/顺序控制 ### OpenAI Codex（ChatGPT OAuth） -OpenAI Codex OAuth 已明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。 +OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。 流程形态（PKCE）： -1. 生成 PKCE verifier/challenge 和随机 `state` +1. 生成 PKCE verifier/challenge + 随机 `state` 2. 打开 `https://auth.openai.com/oauth/authorize?...` 3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调 -4. 如果无法绑定回调（或者你处于远程/无头环境），则粘贴重定向 URL/代码 -5. 在 `https://auth.openai.com/oauth/token` 交换令牌 +4. 如果回调无法绑定（或你在远程/无头环境中），粘贴重定向 URL/代码 +5. 在 `https://auth.openai.com/oauth/token` 交换 6. 从访问令牌中提取 `accountId`，并存储 `{ access, refresh, expires, accountId }` -向导路径为 `openclaw onboard` → 认证选项 `openai-codex`。 +向导路径是 `openclaw onboard` → 凭证选择 `openai-codex`。 ## 刷新 + 过期 -配置文件会存储一个 `expires` 时间戳。 +配置文件会存储 `expires` 时间戳。 -在运行时： +运行时： -- 如果 `expires` 仍在未来 → 使用已存储的访问令牌 -- 如果已过期 → 刷新（在文件锁保护下），并覆盖已存储的凭证 -- 例外：某些外部 CLI 凭证仍由外部管理；OpenClaw - 会重新读取这些 CLI 认证存储，而不是使用复制来的刷新令牌。 - Codex CLI 引导的范围被有意收窄：它会初始化一个空的 - `openai-codex:default` 配置文件，然后由 OpenClaw 自主刷新的结果保持该本地 - 配置文件为规范来源。 +- 如果 `expires` 在未来 → 使用存储的访问令牌 +- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据 +- 例外：某些外部 CLI 凭据仍由外部管理；OpenClaw + 会重新读取这些 CLI 凭证存储，而不是消耗复制来的刷新令牌。 + Codex CLI 引导被有意收窄：它会植入一个空的 + `openai-codex:default` 配置文件，然后由 OpenClaw 拥有的刷新流程保持本地 + 配置文件为权威来源。 -刷新流程是自动的；通常你不需要手动管理令牌。 +刷新流程是自动的；你通常不需要手动管理令牌。 -## 多个账户（配置文件）+ 路由 +## 多账号（配置文件）+ 路由 两种模式： -### 1）首选：分离的智能体 +### 1) 推荐：独立智能体 -如果你希望“个人”和“工作”彼此完全隔离，请使用独立的智能体（独立会话 + 凭证 + 工作区）： +如果你希望“个人”和“工作”永不交互，请使用隔离的智能体（独立会话 + 凭据 + 工作区）： ```bash openclaw agents add work openclaw agents add personal ``` -然后按每个智能体配置认证（向导），并将聊天路由到正确的智能体。 +然后按智能体配置凭证（向导），并将聊天路由到正确的智能体。 -### 2）高级：单个智能体中的多个配置文件 +### 2) 高级：一个智能体中的多个配置文件 -`auth-profiles.json` 支持同一提供商使用多个配置文件 ID。 +`auth-profiles.json` 支持同一提供商的多个配置文件 ID。 选择使用哪个配置文件： -- 通过配置顺序全局选择（`auth.order`） -- 通过 `/model ...@` 按会话覆盖 +- 通过配置顺序（`auth.order`）全局选择 +- 通过 `/model ...@` 按会话选择 示例（会话覆盖）： - `/model Opus@anthropic:work` -如何查看现有的配置文件 ID： +如何查看现有配置文件 ID： - `openclaw channels list --json`（显示 `auth[]`） 相关文档： -- [模型故障切换](/zh-CN/concepts/model-failover)（轮换 + 冷却规则） +- [模型故障转移](/zh-CN/concepts/model-failover)（轮换 + 冷却规则） - [斜杠命令](/zh-CN/tools/slash-commands)（命令界面） -## 相关内容 +## 相关 -- [认证](/zh-CN/gateway/authentication) — 模型提供商认证概览 -- [密钥](/zh-CN/gateway/secrets) — 凭证存储和 SecretRef -- [配置参考](/zh-CN/gateway/configuration-reference#auth-storage) — 认证配置键 +- [身份验证](/zh-CN/gateway/authentication) — 模型提供商凭证概览 +- [密钥](/zh-CN/gateway/secrets) — 凭据存储和 SecretRef +- [配置参考](/zh-CN/gateway/configuration-reference#auth-storage) — 凭证配置键