better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/microsoft-graph-app-registration.md

@@ -0,0 +1,180 @@
+---
+title: "注册 Microsoft Graph 应用程序"
+description: "Azure 门户操作指南：创建为 Teams 会议流水线提供支持的应用注册"
+---
+
+# 注册 Microsoft Graph 应用程序
+
+Teams 会议流水线使用**仅限应用**（daemon）身份验证从 Microsoft Graph 读取会议转录、录制及相关产物——无需用户登录，无需每次会议单独交互式授权。这需要一个经过管理员同意、具备应用程序权限的 Azure AD 应用注册。
+
+本指南涵盖以下步骤：
+
+1. 创建应用注册
+2. 创建客户端密钥
+3. 授予流水线所需的 Graph API 权限
+4. 管理员同意这些权限
+5. （可选）通过应用程序访问策略将应用限定到特定用户
+
+完成本指南需要**租户管理员权限**（或由管理员代为授予同意）。请记录收集到的值——最终需要填入 `~/.hermes/.env`。
+
+## 前提条件
+
+- 一个具备 Teams Premium 或 Teams 许可证（可生成会议转录和录制）的 Microsoft 365 租户
+- 可访问 Azure 门户 [entra.microsoft.com](https://entra.microsoft.com) 的管理员权限
+- 一个可公开访问的 HTTPS 端点，用于接收 Graph 变更通知（在后续 webhook 监听器步骤中配置）
+
+## 步骤 1：创建应用注册
+
+1. 以租户管理员身份登录 [entra.microsoft.com](https://entra.microsoft.com)。
+2. 导航至 **Identity → Applications → App registrations**。
+3. 点击 **New registration**。
+4. 填写以下内容：
+   - **Name：**`Hermes Teams Meeting Pipeline`（或任何你能识别的名称）。
+   - **Supported account types：***Accounts in this organizational directory only (Single tenant)*。
+   - **Redirect URI：**留空——仅限应用的身份验证不需要此项。
+5. 点击 **Register**。
+
+页面将跳转至应用概览页。复制以下两个值：
+
+- **Application (client) ID** → `MSGRAPH_CLIENT_ID`
+- **Directory (tenant) ID** → `MSGRAPH_TENANT_ID`
+
+## 步骤 2：创建客户端密钥
+
+1. 在左侧导航栏中，打开 **Certificates & secrets**。
+2. 点击 **New client secret**。
+3. **Description：**`hermes-graph-secret`。**Expires：**根据你的轮换策略选择合适的值（通常为 6-24 个月）。
+4. 点击 **Add**。
+5. 立即复制 **Value** 列的值——该值仅显示一次。此值即为 `MSGRAPH_CLIENT_SECRET`。
+
+> **Secret ID** 列不是密钥本身。你需要的是 **Value** 列。
+
+## 步骤 3：授予 Graph API 权限
+
+流水线使用最小化的应用程序权限集。仅添加所需权限；每项权限都会扩大应用在租户范围内的读取能力。
+
+1. 在左侧导航栏中，打开 **API permissions**。
+2. 点击 **Add a permission** → **Microsoft Graph** → **Application permissions**。
+3. 根据下表添加流水线所需的权限。
+4. 添加完成后，点击 **Grant admin consent for `<your tenant>`**。每项权限的 Status 列应变为绿色对勾。
+
+### 转录优先摘要所需权限
+
+| 权限 | 允许应用执行的操作 |
+|------------|--------------------------|
+| `OnlineMeetings.Read.All` | 读取 Teams 在线会议元数据（主题、参与者、加入 URL）。 |
+| `OnlineMeetingTranscript.Read.All` | 读取 Teams 生成的会议转录。 |
+
+### 录制回退所需权限（当转录不可用时）
+
+| 权限 | 允许应用执行的操作 |
+|------------|--------------------------|
+| `OnlineMeetingRecording.Read.All` | 下载 Teams 会议录制以进行离线语音转文字处理。 |
+| `CallRecords.Read.All` | 仅知道加入 URL 时，通过通话记录解析会议信息。 |
+
+### 出站摘要投递所需权限（仅限 Graph 模式）
+
+若 `platforms.teams.extra.delivery_mode` 设置为 `graph`，流水线将通过 Graph API 将摘要发布到 Teams 频道或聊天。如果使用 `incoming_webhook` 投递模式，可跳过这些权限。
+
+| 权限 | 允许应用执行的操作 |
+|------------|--------------------------|
+| `ChannelMessage.Send` | 以应用身份向 Teams 频道发布消息。 |
+| `Chat.ReadWrite.All` | 向一对一及群组聊天发布消息（仅在将 `chat_id` 设为投递目标时需要）。 |
+
+### 不推荐的权限
+
+- `OnlineMeetings.ReadWrite.All` / `Chat.ReadWrite`（不带 `.All`）——权限范围超出流水线所需。
+- 委托权限——流水线使用仅限应用（客户端凭据）流程；委托权限在没有用户登录的情况下无法生效。
+
+## 步骤 4：（推荐）通过应用程序访问策略限定应用范围
+
+默认情况下，`OnlineMeetings.Read.All` 等应用程序权限会授予应用访问租户中**所有**会议的权限。对于合作伙伴演示和开发租户而言这没有问题；但在生产环境中，你几乎肯定需要限制应用可读取哪些用户的会议。
+
+Microsoft 专门为 Teams 提供了**应用程序访问策略**（Application Access Policies）。该策略仅支持 PowerShell 操作，没有门户 UI。
+
+在已安装并连接 MicrosoftTeams 模块的管理员 PowerShell 中（`Connect-MicrosoftTeams`）执行：
+
+```powershell
+# Create a policy scoped to the Hermes app
+New-CsApplicationAccessPolicy `
+  -Identity "Hermes-Meeting-Pipeline-Policy" `
+  -AppIds "<MSGRAPH_CLIENT_ID>" `
+  -Description "Restrict Hermes meeting pipeline to allow-listed users"
+
+# Grant the policy to specific users whose meetings the pipeline may read
+Grant-CsApplicationAccessPolicy `
+  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
+  -Identity "alice@example.com"
+
+Grant-CsApplicationAccessPolicy `
+  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
+  -Identity "bob@example.com"
+```
+
+授权后策略生效最长需要 30 分钟。使用以下命令验证：
+
+```powershell
+Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "<MSGRAPH_CLIENT_ID>"
+```
+
+若不配置此策略，**任何**用户的会议均可被读取——这正是该权限在技术层面所授予的范围。生产租户请勿跳过此步骤。
+
+## 步骤 5：将凭据写入环境文件
+
+将收集到的三个值填入 `~/.hermes/.env`：
+
+```bash
+MSGRAPH_TENANT_ID=<directory-tenant-id>
+MSGRAPH_CLIENT_ID=<application-client-id>
+MSGRAPH_CLIENT_SECRET=<client-secret-value>
+```
+
+设置文件权限，确保只有你能读取密钥：
+
+```bash
+chmod 600 ~/.hermes/.env
+```
+
+## 步骤 6：验证令牌流程
+
+Hermes 内置了 Graph 身份验证冒烟测试。在 Hermes 安装目录下执行：
+
+```python
+python -c "
+import asyncio
+from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
+provider = MicrosoftGraphTokenProvider.from_env()
+token = asyncio.run(provider.get_access_token())
+print('Token acquired, length:', len(token))
+print(provider.inspect_token_health())
+"
+```
+
+成功执行后将打印一个较长的 token（令牌）字符串，以及一个健康状态字典，其中 `cached: True`，`expires_in_seconds` 值接近 3600。失败时将抛出 `MicrosoftGraphTokenError`，并附带 Azure 错误码——最常见的错误如下：
+
+| Azure 错误码 | 含义 | 修复方法 |
+|-------------|---------|-----|
+| `AADSTS7000215: Invalid client secret` | 密钥值不匹配或已过期。 | 在步骤 2 中生成新密钥，并更新 `.env`。 |
+| `AADSTS700016: Application not found` | `MSGRAPH_CLIENT_ID` 错误或租户不匹配。 | 确认步骤 1 中的值来自同一应用。 |
+| `AADSTS90002: Tenant not found` | `MSGRAPH_TENANT_ID` 存在拼写错误。 | 重新从应用概览页复制 Directory (tenant) ID。 |
+| `insufficient_claims`（调用时报错，非获取令牌时） | 令牌获取成功，但 Graph 返回 401/403。 | 跳过了步骤 3 的管理员同意，或添加权限后未重新同意。重新进入 API permissions 并点击 **Grant admin consent**。 |
+
+## 轮换客户端密钥
+
+Azure 客户端密钥有固定的过期时间。在密钥过期前：
+
+1. 在步骤 2 中创建第二个客户端密钥，不要删除第一个。
+2. 用新值更新 `~/.hermes/.env` 中的 `MSGRAPH_CLIENT_SECRET`。
+3. 重启 gateway 以使新密钥生效：`hermes gateway restart`。
+4. 使用上述冒烟测试进行验证。
+5. 在 Azure 门户中删除旧密钥。
+
+## 后续步骤
+
+凭据验证通过后，继续完成以下配置：
+
+- **Webhook 监听器配置**——部署接收 Graph 变更通知的 `msgraph_webhook` gateway 平台。
+- **流水线配置**——配置 Teams 会议流水线运行时及操作员 CLI。
+- **出站投递**——将摘要回传至 Teams 频道或聊天。
+
+上述页面将随添加对应运行时的 PR 一并发布。本凭据配置是独立的前提步骤，可提前完成。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/migrate-from-openclaw.md

@@ -0,0 +1,244 @@
+---
+sidebar_position: 10
+title: "从 OpenClaw 迁移"
+description: "将 OpenClaw / Clawdbot 配置迁移到 Hermes Agent 的完整指南——包括迁移内容、配置键映射及迁移后的检查事项。"
+---
+
+# 从 OpenClaw 迁移
+
+`hermes claw migrate` 将你的 OpenClaw（或旧版 Clawdbot/Moldbot）配置导入 Hermes。本指南详细说明迁移内容、配置键映射以及迁移后的验证步骤。
+
+## 快速开始
+
+```bash
+# 预览后迁移（始终先显示预览，再要求确认）
+hermes claw migrate
+
+# 仅预览，不做任何更改
+hermes claw migrate --dry-run
+
+# 完整迁移，包含 API 密钥，跳过确认
+hermes claw migrate --preset full --migrate-secrets --yes
+```
+
+迁移操作在执行任何更改前，始终会显示完整的导入预览。请检查列表后确认继续。
+
+默认从 `~/.openclaw/` 读取。旧版 `~/.clawdbot/` 或 `~/.moltbot/` 目录会被自动检测，旧版配置文件名（`clawdbot.json`、`moltbot.json`）同理。
+
+## 选项
+
+| 选项 | 说明 |
+|--------|-------------|
+| `--dry-run` | 仅预览——显示将迁移的内容后停止。 |
+| `--preset <name>` | `full`（所有兼容设置）或 `user-data`（排除基础设施配置）。两种预设默认均不导入密钥——需显式传入 `--migrate-secrets`。 |
+| `--overwrite` | 冲突时覆盖已有 Hermes 文件（默认：计划存在冲突时拒绝执行）。 |
+| `--migrate-secrets` | 包含 API 密钥。即使使用 `--preset full` 也需要显式指定——没有任何预设会静默导入密钥。 |
+| `--no-backup` | 跳过迁移前对 `~/.hermes/` 的 zip 快照备份（默认在执行前写入单个还原点归档，位于 `~/.hermes/backups/pre-migration-*.zip`；可通过 `hermes import` 还原）。 |
+| `--source <path>` | 自定义 OpenClaw 目录。 |
+| `--workspace-target <path>` | `AGENTS.md` 的放置位置。 |
+| `--skill-conflict <mode>` | `skip`（默认）、`overwrite` 或 `rename`。 |
+| `--yes` | 跳过预览后的确认提示。 |
+
+## 迁移内容
+
+### Persona（角色设定）、记忆与指令
+
+| 内容 | OpenClaw 来源 | Hermes 目标 | 备注 |
+|------|----------------|-------------------|-------|
+| Persona | `workspace/SOUL.md` | `~/.hermes/SOUL.md` | 直接复制 |
+| 工作区指令 | `workspace/AGENTS.md` | `--workspace-target` 中的 `AGENTS.md` | 需要 `--workspace-target` 标志 |
+| 长期记忆 | `workspace/MEMORY.md` | `~/.hermes/memories/MEMORY.md` | 解析为条目，与现有内容合并并去重，使用 `§` 分隔符 |
+| 用户档案 | `workspace/USER.md` | `~/.hermes/memories/USER.md` | 与记忆相同的条目合并逻辑 |
+| 每日记忆文件 | `workspace/memory/*.md` | `~/.hermes/memories/MEMORY.md` | 所有每日文件合并至主记忆 |
+
+工作区文件还会在 `workspace.default/` 和 `workspace-main/` 作为备用路径进行检测（OpenClaw 在近期版本中将 `workspace/` 重命名为 `workspace-main/`，多 Agent 配置下使用 `workspace-{agentId}`）。
+
+### Skills（技能，4 个来源）
+
+| 来源 | OpenClaw 位置 | Hermes 目标 |
+|--------|------------------|-------------------|
+| 工作区 skills | `workspace/skills/` | `~/.hermes/skills/openclaw-imports/` |
+| 托管/共享 skills | `~/.openclaw/skills/` | `~/.hermes/skills/openclaw-imports/` |
+| 个人跨项目 skills | `~/.agents/skills/` | `~/.hermes/skills/openclaw-imports/` |
+| 项目级共享 skills | `workspace/.agents/skills/` | `~/.hermes/skills/openclaw-imports/` |
+
+Skill 冲突由 `--skill-conflict` 处理：`skip` 保留现有 Hermes skill，`overwrite` 替换，`rename` 创建带 `-imported` 后缀的副本。
+
+### 模型与 Provider 配置
+
+| 内容 | OpenClaw 配置路径 | Hermes 目标 | 备注 |
+|------|---------------------|-------------------|-------|
+| 默认模型 | `agents.defaults.model` | `config.yaml` → `model` | 可为字符串或 `{primary, fallbacks}` 对象 |
+| 自定义 providers | `models.providers.*` | `config.yaml` → `custom_providers` | 映射 `baseUrl`、`apiType`/`api`——同时处理短格式（"openai"、"anthropic"）和带连字符格式（"openai-completions"、"anthropic-messages"、"google-generative-ai"） |
+| Provider API 密钥 | `models.providers.*.apiKey` | `~/.hermes/.env` | 需要 `--migrate-secrets`。参见下方 [API 密钥解析](#api-key-resolution) |
+
+### Agent 行为
+
+| 内容 | OpenClaw 配置路径 | Hermes 配置路径 | 映射规则 |
+|------|---------------------|-------------------|---------|
+| 最大轮次 | `agents.defaults.timeoutSeconds` | `agent.max_turns` | `timeoutSeconds / 10`，上限 200 |
+| 详细模式 | `agents.defaults.verboseDefault` | `agent.verbose` | "off" / "on" / "full" |
+| 推理强度 | `agents.defaults.thinkingDefault` | `agent.reasoning_effort` | "always"/"high"/"xhigh" → "high"，"auto"/"medium"/"adaptive" → "medium"，"off"/"low"/"none"/"minimal" → "low" |
+| 压缩 | `agents.defaults.compaction.mode` | `compression.enabled` | "off" → false，其他 → true |
+| 压缩模型 | `agents.defaults.compaction.model` | `compression.summary_model` | 直接字符串复制 |
+| 人工延迟 | `agents.defaults.humanDelay.mode` | `human_delay.mode` | "natural" / "custom" / "off" |
+| 人工延迟时间 | `agents.defaults.humanDelay.minMs` / `.maxMs` | `human_delay.min_ms` / `.max_ms` | 直接复制 |
+| 时区 | `agents.defaults.userTimezone` | `timezone` | 直接字符串复制 |
+| 执行超时 | `tools.exec.timeoutSec` | `terminal.timeout` | 直接复制（字段名为 `timeoutSec`，非 `timeout`） |
+| Docker 沙箱 | `agents.defaults.sandbox.backend` | `terminal.backend` | "docker" → "docker" |
+| Docker 镜像 | `agents.defaults.sandbox.docker.image` | `terminal.docker_image` | 直接复制 |
+
+### 会话生命周期
+
+不会导入空闲或每日重置计时器。Hermes 会话会持续保留，直到显式使用 `/new` 或 `/reset`。身份关联、线程绑定、维护、作用域和发送策略等高级设置仍会归档以供参考。
+
+### MCP 服务器
+
+| OpenClaw 字段 | Hermes 字段 | 备注 |
+|----------------|-------------|-------|
+| `mcp.servers.*.command` | `mcp_servers.*.command` | stdio 传输 |
+| `mcp.servers.*.args` | `mcp_servers.*.args` | |
+| `mcp.servers.*.env` | `mcp_servers.*.env` | |
+| `mcp.servers.*.cwd` | `mcp_servers.*.cwd` | |
+| `mcp.servers.*.url` | `mcp_servers.*.url` | HTTP/SSE 传输 |
+| `mcp.servers.*.tools.include` | `mcp_servers.*.tools.include` | 工具过滤 |
+| `mcp.servers.*.tools.exclude` | `mcp_servers.*.tools.exclude` | |
+
+### TTS（文字转语音）
+
+TTS 设置从 OpenClaw 配置的**两个**位置读取，优先级如下：
+
+1. `messages.tts.providers.{provider}.*`（规范位置）
+2. 顶层 `talk.providers.{provider}.*`（备用）
+3. 旧版扁平键 `messages.tts.{provider}.*`（最旧格式）
+
+| 内容 | Hermes 目标 |
+|------|-------------------|
+| Provider 名称 | `config.yaml` → `tts.provider` |
+| ElevenLabs voice ID | `config.yaml` → `tts.elevenlabs.voice_id` |
+| ElevenLabs model ID | `config.yaml` → `tts.elevenlabs.model_id` |
+| OpenAI 模型 | `config.yaml` → `tts.openai.model` |
+| OpenAI 语音 | `config.yaml` → `tts.openai.voice` |
+| Edge TTS 语音 | `config.yaml` → `tts.edge.voice`（OpenClaw 将 "edge" 重命名为 "microsoft"——两者均可识别） |
+| TTS 资源文件 | `~/.hermes/tts/`（文件复制） |
+
+### 消息平台
+
+| 平台 | OpenClaw 配置路径 | Hermes `.env` 变量 | 备注 |
+|----------|---------------------|----------------------|-------|
+| Telegram | `channels.telegram.botToken` 或 `.accounts.default.botToken` | `TELEGRAM_BOT_TOKEN` | Token 可为字符串或 [SecretRef](#secretref-handling)，支持扁平和 accounts 两种布局 |
+| Telegram | `credentials/telegram-default-allowFrom.json` | `TELEGRAM_ALLOWED_USERS` | 从 `allowFrom[]` 数组逗号拼接 |
+| Discord | `channels.discord.token` 或 `.accounts.default.token` | `DISCORD_BOT_TOKEN` | |
+| Discord | `channels.discord.allowFrom` 或 `.accounts.default.allowFrom` | `DISCORD_ALLOWED_USERS` | |
+| Slack | `channels.slack.botToken` 或 `.accounts.default.botToken` | `SLACK_BOT_TOKEN` | |
+| Slack | `channels.slack.appToken` 或 `.accounts.default.appToken` | `SLACK_APP_TOKEN` | |
+| Slack | `channels.slack.allowFrom` 或 `.accounts.default.allowFrom` | `SLACK_ALLOWED_USERS` | |
+| WhatsApp | `channels.whatsapp.allowFrom` 或 `.accounts.default.allowFrom` | `WHATSAPP_ALLOWED_USERS` | 通过 Baileys 二维码配对认证——迁移后需重新配对 |
+| Signal | `channels.signal.account` 或 `.accounts.default.account` | `SIGNAL_ACCOUNT` | |
+| Signal | `channels.signal.httpUrl` 或 `.accounts.default.httpUrl` | `SIGNAL_HTTP_URL` | |
+| Signal | `channels.signal.allowFrom` 或 `.accounts.default.allowFrom` | `SIGNAL_ALLOWED_USERS` | |
+| Matrix | `channels.matrix.accessToken` 或 `.accounts.default.accessToken` | `MATRIX_ACCESS_TOKEN` | 使用 `accessToken`（非 `botToken`） |
+| Mattermost | `channels.mattermost.botToken` 或 `.accounts.default.botToken` | `MATTERMOST_BOT_TOKEN` | |
+
+### 其他配置
+
+| 内容 | OpenClaw 路径 | Hermes 路径 | 备注 |
+|------|-------------|-------------|-------|
+| 审批模式 | `approvals.exec.mode` | `config.yaml` → `approvals.mode` | "auto"→"off"，"always"→"manual"，"smart"→"smart" |
+| 命令白名单 | `exec-approvals.json` | `config.yaml` → `command_allowlist` | 模式合并并去重 |
+| 浏览器 CDP URL | `browser.cdpUrl` | `config.yaml` → `browser.cdp_url` | |
+| 浏览器无头模式 | `browser.headless` | `config.yaml` → `browser.headless` | |
+| Brave 搜索密钥 | `tools.web.search.brave.apiKey` | `.env` → `BRAVE_API_KEY` | 需要 `--migrate-secrets` |
+| Gateway 认证 token | `gateway.auth.token` | `.env` → `HERMES_GATEWAY_TOKEN` | 需要 `--migrate-secrets` |
+| 工作目录 | `agents.defaults.workspace` | `.env` → `MESSAGING_CWD` | |
+
+### 已归档（无对应 Hermes 等效项）
+
+以下内容保存至 `~/.hermes/migration/openclaw/<timestamp>/archive/` 供人工审查：
+
+| 内容 | 归档文件 | 在 Hermes 中的重建方式 |
+|------|-------------|--------------------------|
+| `IDENTITY.md` | `archive/workspace/IDENTITY.md` | 合并至 `SOUL.md` |
+| `TOOLS.md` | `archive/workspace/TOOLS.md` | Hermes 内置工具说明 |
+| `HEARTBEAT.md` | `archive/workspace/HEARTBEAT.md` | 使用 cron 作业执行周期性任务 |
+| `BOOTSTRAP.md` | `archive/workspace/BOOTSTRAP.md` | 使用上下文文件或 skills |
+| Cron 作业 | `archive/cron-config.json` | 通过 `hermes cron create` 重建 |
+| 插件 | `archive/plugins-config.json` | 参见 [插件指南](/user-guide/features/hooks) |
+| Hooks/webhooks | `archive/hooks-config.json` | 使用 `hermes webhook` 或 gateway hooks |
+| 记忆后端 | `archive/memory-backend-config.json` | 通过 `hermes honcho` 配置 |
+| Skills 注册表 | `archive/skills-registry-config.json` | 使用 `hermes skills config` |
+| UI/身份 | `archive/ui-identity-config.json` | 使用 `/skin` 命令 |
+| 日志 | `archive/logging-diagnostics-config.json` | 在 `config.yaml` 日志部分设置 |
+| 多 Agent 列表 | `archive/agents-list.json` | 使用 Hermes profiles |
+| 频道绑定 | `archive/bindings.json` | 按平台手动配置 |
+| 复杂频道配置 | `archive/channels-deep-config.json` | 手动配置各平台 |
+
+## API 密钥解析
+
+启用 `--migrate-secrets` 时，API 密钥按以下优先级从**四个来源**收集：
+
+1. **配置值** — `openclaw.json` 中的 `models.providers.*.apiKey` 及 TTS provider 密钥
+2. **环境文件** — `~/.openclaw/.env`（如 `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` 等）
+3. **配置 env 子对象** — `openclaw.json` → `"env"` 或 `"env"."vars"`（部分配置将密钥存于此处而非单独的 `.env` 文件）
+4. **认证档案** — `~/.openclaw/agents/main/agent/auth-profiles.json`（每个 Agent 的凭据）
+
+配置值优先级最高，后续来源依次填补剩余空缺。
+
+### 支持的密钥目标
+
+`OPENROUTER_API_KEY`、`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`DEEPSEEK_API_KEY`、`GEMINI_API_KEY`、`ZAI_API_KEY`、`MINIMAX_API_KEY`、`ELEVENLABS_API_KEY`、`TELEGRAM_BOT_TOKEN`、`VOICE_TOOLS_OPENAI_KEY`
+
+不在此白名单中的密钥一律不会被复制。
+
+## SecretRef 处理
+
+OpenClaw 配置中 token 和 API 密钥的值支持三种格式：
+
+```json
+// 纯字符串
+"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }
+
+// 环境变量模板
+"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }
+
+// SecretRef 对象
+"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }
+```
+
+迁移会解析所有三种格式。对于环境变量模板和 `source: "env"` 的 SecretRef 对象，会从 `~/.openclaw/.env` 和 `openclaw.json` 的 env 子对象中查找值。`source: "file"` 或 `source: "exec"` 的 SecretRef 对象无法自动解析——迁移会对此发出警告，相关值需通过 `hermes config set` 手动添加至 Hermes。
+
+## 迁移后
+
+1. **检查迁移报告** — 完成后打印，包含已迁移、已跳过和冲突项的计数。
+
+2. **审查归档文件** — `~/.hermes/migration/openclaw/<timestamp>/archive/` 中的所有内容需要人工处理。
+
+3. **开启新会话** — 导入的 skills 和记忆条目在新会话中生效，当前会话不受影响。
+
+4. **验证 API 密钥** — 运行 `hermes status` 检查 provider 认证状态。
+
+5. **测试消息平台** — 若迁移了平台 token，重启 gateway：`systemctl --user restart hermes-gateway`
+
+6. **检查会话归档** — 查看已归档的高级设置；空闲和每日重置计时器不会导入。
+
+7. **重新配对 WhatsApp** — WhatsApp 使用二维码配对（Baileys），不支持 token 迁移。运行 `hermes whatsapp` 进行配对。
+
+8. **清理归档** — 确认一切正常后，运行 `hermes claw cleanup` 将残留的 OpenClaw 目录重命名为 `.pre-migration/`（防止状态混淆）。
+
+## 故障排查
+
+### "OpenClaw directory not found"
+
+迁移依次检查 `~/.openclaw/`、`~/.clawdbot/`、`~/.moltbot/`。若你的安装路径不同，请使用 `--source /path/to/your/openclaw`。
+
+### "No provider API keys found"
+
+根据 OpenClaw 版本不同，密钥可能存储在多个位置：`openclaw.json` 中 `models.providers.*.apiKey` 内联、`~/.openclaw/.env`、`openclaw.json` 的 `"env"` 子对象，或 `agents/main/agent/auth-profiles.json`。迁移会检查所有四个位置。若密钥使用 `source: "file"` 或 `source: "exec"` 的 SecretRef，则无法自动解析——请通过 `hermes config set` 手动添加。
+
+### 迁移后 skills 未出现
+
+导入的 skills 位于 `~/.hermes/skills/openclaw-imports/`。开启新会话后生效，或运行 `/skills` 验证是否已加载。
+
+### TTS 语音未迁移
+
+OpenClaw 在两处存储 TTS 设置：`messages.tts.providers.*` 和顶层 `talk` 配置。迁移会检查两处。若你的 voice ID 是通过 OpenClaw UI 设置的（存储路径不同），可能需要手动设置：`hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID`。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/minimax-oauth.md

@@ -0,0 +1,228 @@
+---
+sidebar_position: 15
+title: "MiniMax OAuth"
+description: "通过浏览器 OAuth 登录 MiniMax，在 Hermes Agent 中使用 MiniMax-M2.7 模型——无需 API 密钥"
+---
+
+# MiniMax OAuth
+
+Hermes Agent 通过基于浏览器的 OAuth 登录流程支持 **MiniMax**，使用与 [MiniMax 门户](https://www.minimax.io) 相同的凭据。无需 API 密钥或信用卡——登录一次，Hermes 即可自动刷新您的会话。
+
+该传输层复用了 `anthropic_messages` 适配器（MiniMax 在 `/anthropic` 路径暴露了一个兼容 Anthropic Messages 的端点），因此所有现有的工具调用、流式传输和上下文功能无需任何适配器改动即可正常使用。
+
+## 概览
+
+| 项目 | 值 |
+|------|-------|
+| Provider ID | `minimax-oauth` |
+| 显示名称 | MiniMax (OAuth) |
+| 认证类型 | 浏览器 OAuth（PKCE 设备码流程） |
+| 传输层 | 兼容 Anthropic Messages（`anthropic_messages`） |
+| 模型 | `MiniMax-M2.7`、`MiniMax-M2.7-highspeed` |
+| 全球端点 | `https://api.minimax.io/anthropic` |
+| 中国端点 | `https://api.minimaxi.com/anthropic` |
+| 需要环境变量 | 否（`MINIMAX_API_KEY` **不**用于此 provider） |
+
+## 前提条件
+
+- Python 3.9+
+- 已安装 Hermes Agent
+- 在 [minimax.io](https://www.minimax.io)（全球）或 [minimaxi.com](https://www.minimaxi.com)（中国）注册的 MiniMax 账户
+- 本地机器上可用的浏览器（远程会话请使用 `--no-browser`）
+
+## 快速开始
+
+```bash
+# 启动 provider 和模型选择器
+hermes model
+# → 从 provider 列表中选择 "MiniMax (OAuth)"
+# → Hermes 在浏览器中打开 MiniMax 授权页面
+# → 在浏览器中批准访问
+# → 选择模型（MiniMax-M2.7 或 MiniMax-M2.7-highspeed）
+# → 开始对话
+
+hermes
+```
+
+首次登录后，凭据将存储在 `~/.hermes/auth.json` 下，并在每次会话前自动刷新。
+
+## 手动登录
+
+您可以在不经过模型选择器的情况下触发登录：
+
+```bash
+hermes auth add minimax-oauth
+```
+
+### 中国区域
+
+如果您的账户在中国平台（`minimaxi.com`），请改用中国区域 OAuth provider id `minimax-cn`，或跳过 OAuth 直接配置 `MINIMAX_CN_API_KEY` / `MINIMAX_CN_BASE_URL`。旧版文档中描述的 `--region cn` 标志**未**接入 CLI 的参数解析器；请改用 `minimax-cn` provider：
+
+```bash
+hermes auth add minimax-cn --type oauth   # 如果您的中国账户支持 OAuth
+# 或更简单的方式：
+echo 'MINIMAX_CN_API_KEY=your-key' >> ~/.hermes/.env
+```
+
+### 远程/无头会话
+
+在没有浏览器的服务器或容器上：
+
+```bash
+hermes auth add minimax-oauth --no-browser
+```
+
+Hermes 将打印验证 URL 和用户码——在任意设备上打开该 URL，并在提示时输入用户码。
+
+## OAuth 流程
+
+Hermes 针对 MiniMax OAuth 端点实现了 PKCE 设备码流程：
+
+1. Hermes 生成 PKCE verifier/challenge 对和一个随机 state 值。
+2. 携带 challenge 向 `{base_url}/oauth/code` 发送 POST 请求，获取 `user_code` 和 `verification_uri`。
+3. 浏览器打开 `verification_uri`。如有提示，输入 `user_code`。
+4. Hermes 轮询 `{base_url}/oauth/token`，直到令牌到达（或超过截止时间）。
+5. 令牌（`access_token`、`refresh_token`、过期时间）以 `minimax-oauth` 为键保存到 `~/.hermes/auth.json`。
+
+令牌刷新（标准 OAuth `refresh_token` 授权）在每次会话启动时自动执行，当 access token 距过期不足 60 秒时触发。
+
+## 检查登录状态
+
+```bash
+hermes doctor
+```
+
+`◆ Auth Providers` 部分将显示：
+
+```
+✓ MiniMax OAuth  (logged in, region=global)
+```
+
+或者，如果未登录：
+
+```
+⚠ MiniMax OAuth  (not logged in)
+```
+
+## 切换模型
+
+```bash
+hermes model
+# → 选择 "MiniMax (OAuth)"
+# → 从模型列表中选择
+```
+
+或直接设置模型：
+
+```bash
+hermes config set model MiniMax-M2.7
+hermes config set provider minimax-oauth
+```
+
+## 配置参考
+
+登录后，`~/.hermes/config.yaml` 将包含类似如下的条目：
+
+```yaml
+model:
+  default: MiniMax-M2.7
+  provider: minimax-oauth
+  base_url: https://api.minimax.io/anthropic
+```
+
+### 区域端点
+
+| Provider id | 门户 | 推理端点 |
+|-------------|--------|-------------------|
+| `minimax-oauth`（全球） | `https://api.minimax.io` | `https://api.minimax.io/anthropic` |
+| `minimax-cn`（中国） | `https://api.minimaxi.com` | `https://api.minimaxi.com/anthropic` |
+
+### Provider 别名
+
+以下所有别名均解析为 `minimax-oauth`：
+
+```bash
+hermes --provider minimax-oauth    # 规范名称
+hermes --provider minimax-portal   # 别名
+hermes --provider minimax-global   # 别名
+hermes --provider minimax_oauth    # 别名（下划线形式）
+```
+
+## 环境变量
+
+`minimax-oauth` provider **不**使用 `MINIMAX_API_KEY` 或 `MINIMAX_BASE_URL`。这些变量仅用于基于 API 密钥的 `minimax` 和 `minimax-cn` provider。
+
+| 变量 | 作用 |
+|----------|--------|
+| `MINIMAX_API_KEY` | 仅用于 `minimax` provider——对 `minimax-oauth` 无效 |
+| `MINIMAX_CN_API_KEY` | 仅用于 `minimax-cn` provider——对 `minimax-oauth` 无效 |
+
+要将 `minimax-oauth` 设为活跃 provider，请在 `config.yaml` 中设置 `model.provider: minimax-oauth`（使用 `hermes setup` 进行引导式配置），或在单次调用时传入 `--provider minimax-oauth`：
+
+```bash
+hermes --provider minimax-oauth
+```
+
+## 模型
+
+| 模型 | 最适合 |
+|-------|----------|
+| `MiniMax-M2.7` | 长上下文推理、复杂工具调用 |
+| `MiniMax-M2.7-highspeed` | 低延迟、轻量任务、辅助调用 |
+
+两个模型均支持最多 200,000 个 token 的上下文。
+
+当 `minimax-oauth` 为主 provider 时，`MiniMax-M2.7-highspeed` 也会自动用作视觉和委托任务的辅助模型。
+
+## 故障排查
+
+### 令牌已过期——未自动重新登录
+
+Hermes 在每次会话启动时，若 access token 距过期不足 60 秒则刷新令牌。如果 access token 已经过期（例如长时间离线后），刷新将在下一次请求时自动触发。如果刷新失败并返回 `refresh_token_reused` 或 `invalid_grant`，Hermes 会将会话标记为需要重新登录。
+
+当刷新失败为终态（HTTP 4xx、`invalid_grant`、授权已撤销等）时，Hermes 将 refresh token 标记为失效并在本地隔离，避免持续重放注定失败的交换。Agent 会显示一条"需要重新认证"的消息，并在您再次登录之前保持等待。
+
+**解决方法：** 再次运行 `hermes auth add minimax-oauth` 以开始全新登录。下一次成功交换后隔离状态将自动清除。
+
+### 授权超时
+
+设备码流程有有限的过期窗口。如果您未在规定时间内批准登录，Hermes 将抛出超时错误。
+
+**解决方法：** 重新运行 `hermes auth add minimax-oauth`（或 `hermes model`）。流程将重新开始。
+
+### State 不匹配（可能的 CSRF）
+
+Hermes 检测到授权服务器返回的 `state` 值与其发送的值不匹配。
+
+**解决方法：** 重新运行登录。如果问题持续，请检查是否有代理或重定向正在修改 OAuth 响应。
+
+### 从远程服务器登录
+
+如果 `hermes` 无法打开浏览器窗口，请使用 `--no-browser`：
+
+```bash
+hermes auth add minimax-oauth --no-browser
+```
+
+Hermes 将打印 URL 和用户码。在任意设备上打开该 URL 并在那里完成流程。
+
+### 运行时出现"未登录 MiniMax OAuth"错误
+
+auth 存储中没有 `minimax-oauth` 的凭据。您尚未登录，或凭据文件已被删除。
+
+**解决方法：** 运行 `hermes model` 并选择 MiniMax (OAuth)，或运行 `hermes auth add minimax-oauth`。
+
+## 退出登录
+
+要移除已存储的 MiniMax OAuth 凭据：
+
+```bash
+hermes auth logout minimax-oauth
+```
+
+## 另请参阅
+
+- [AI Providers 参考](../integrations/providers.md)
+- [环境变量](../reference/environment-variables.md)
+- [配置](../user-guide/configuration.md)
+- [hermes doctor](../reference/cli-commands.md)