v2026.8.1: 安装与入门

Warning

存储与降级警告

此版本把会话和转录记录的存储改为使用 SQLite。在降级到旧的基于文件的版本之前，请使用当前 CLI 恢复已归档的旧版转录产物；迁移后创建的会话将不会出现在旧版本中。

升级之前，请创建经过验证的备份以保护 OpenClaw 更广泛的状态，并在回滚前查阅跨会话 SQLite 迁移的降级指南。

OpenClaw 现在为新的 Mac、Linux 和 Windows 安装提供了从下载到首次有效对话的更清晰路径，同时 iPhone、iPad 和 Android 把配对与权限放在用户需要的位置。引导式设置可以复用已有的受支持订阅、API 密钥和本地模型，在保存前验证所选模型确实可用，并在连接就绪后移交给 Web 应用或终端。

安装 OpenClaw

受支持的安装路径现在会在设置完成后让应用或命令保持可用。从“下载”文件夹或磁盘映像打开的 Mac 应用可以主动移入“应用程序”文件夹，在那里更新和登录时启动都能正常工作。在 Linux 和其他 Unix 系统上，安装程序会让 openclaw 在新终端会话中可用，无需手动编辑 shell 启动文件。

任何未经身份验证就暴露 OpenClaw 的网络安装都会在任何更改发生前被阻止。重新安装还会在准备过程被取消或失败时保护现有的可用配置，并在报告是否可访问之前给 OpenClaw 留出启动时间。

来源与完整变更列表

改进

在“应用程序”文件夹中安装临时 macOS 启动项 #104661
feat(docker): 在运行时镜像中安装 openssh-client #131710
以通俗语言阐明入门引导的安全指南 #120172

Bug 修复

防止全新状态下的 Gateway 启动超时 #111701
在模型运行时准备期间保持 Gateway 启动的响应性 #112262
为入门引导添加安全的 Gateway token 恢复 #118051
安装后在全新的 Unix shell 中保持 OpenClaw 可用 #124779
在交互式入门引导中遵循远程标志 #111517
切换到 token 认证时移除过期的远程密码 #112544
让首次启动的 loopback CLI 调用在 Gateway 就绪后能够连接 #114380
避免首次启动时因规范内部钩子产生延迟 #117493
在入门引导期间遵循外部 Gateway 监管设置 #119846
在非交互式设置期间遵循 Gateway 密码设置 #126690
为入门引导添加远程 Gateway 密码认证 #126768
fix: 设置中的重新安装被取消时保留 Gateway #130617
fix: 在设置过程中共享受管 Gateway 的启动就绪状态 #130682
fix(install): 防止低内存环境下安装后出现 OOM #132555
fix(cli): 在 Gateway 重启后完成远程入门引导 #133257
防止通过管道执行的安装程序子进程消耗安装脚本 #87799
阻止未经身份验证的网络 Gateway 服务安装 #98022
将全新的 CLI 安装更新至 Node 22.22.2 #104073
在服务安装前等待 Gateway 的警告 #104173
验证所选运行时镜像中的 Docker 时区 #116153
避免 shell 补全权限错误导致入门引导失败 #125263
在 Gateway 副作用发生前持久化配置更改 #125751
fix(installer): 避免从 Linux 软件包仓库获取预发布版 Node #130369
fix(installer): 避免源码安装后重启 Gateway 两次 #130900
fix: 避免守护进程安装中冷 SecretRef 验证停滞 #132206

文档

修正 README 的设置指南与贡献者头像尺寸 #113547
为首次设置精简 README #118376
新增 ChromeOS 与 Crostini 安装指南 #107663
不再要求托管安装程序用户进行两次入门引导 #125246

连接订阅、API 密钥或本地模型

引导式设置现在会首先查找你可能已有的 AI 访问权限。它可以复用经过验证的 Codex、ChatGPT 或 Claude CLI 登录，接受 API 密钥，运行受支持提供方自己的登录流程，或查找符合条件的 Ollama 和 LM Studio 模型，然后在保留该模型和凭据之前，验证所选的确切选项能够正常作答。机器上已经正常工作的访问方式可以成为设置的一部分，而不是另一项需要配置的内容。

对于 OpenAI 账户，设置会使用已登录账户实际可访问的模型，同时保留您自行配置的路由，管理员可以准备受支持的本地模型并显示实时进度。查找或下载本地模型只是开始，因此受支持的本地模型界面不会显示“开始聊天”，直到该确切选择通过激活。

<details class="release-source-toggle">
<summary>来源和完整变更列表</summary>

**改进**

- 将全新 OpenAI 设置默认设为 GPT-5.6 [#103581](https://github.com/openclaw/openclaw/pull/103581)
- 在入门引导中添加提供商登录 [#104502](https://github.com/openclaw/openclaw/pull/104502)
- 从控制界面配置模型提供商 [#106490](https://github.com/openclaw/openclaw/pull/106490)
- 在入门引导期间发现已安装的本地模型 [#108605](https://github.com/openclaw/openclaw/pull/108605)
- 在控制界面中添加引导式模型设置 [#108868](https://github.com/openclaw/openclaw/pull/108868)
- 从控制界面验证当前模型连接 [#109183](https://github.com/openclaw/openclaw/pull/109183)
- 在引导式入门引导期间优先选择更强的本地模型 [#109250](https://github.com/openclaw/openclaw/pull/109250)
- 添加进程内本地 GGUF 文本推理 [#109444](https://github.com/openclaw/openclaw/pull/109444)
- 使用 Gemma 4 作为受 RAM 限制的 llama.cpp 默认模型 [#109585](https://github.com/openclaw/openclaw/pull/109585)
- 添加统一的 AI 设置建议 [#109681](https://github.com/openclaw/openclaw/pull/109681)
- 在设置界面中流式传输提供商准备进度 [#109764](https://github.com/openclaw/openclaw/pull/109764)
- 为已验证的本地模型自动使用精简工具界面 [#110596](https://github.com/openclaw/openclaw/pull/110596)
- 在 Web 和 macOS 上添加一键本地模型设置 [#113476](https://github.com/openclaw/openclaw/pull/113476)
- 添加已验证的 LM Studio 和本地模型入门引导 [#116606](https://github.com/openclaw/openclaw/pull/116606)
- 用托管的 llama-server 替换 node-llama-cpp [#123105](https://github.com/openclaw/openclaw/pull/123105)
- 改进 macOS 设备代码登录 [#104766](https://github.com/openclaw/openclaw/pull/104766)
- 使 macOS AI 连接选项与 CLI 入门引导保持一致 [#107642](https://github.com/openclaw/openclaw/pull/107642)
- 明确提供商凭据设置和 CLI 登录恢复 [#108739](https://github.com/openclaw/openclaw/pull/108739)
- 在引导式设置期间报告已安装的 Pi 和 OpenCode 工具 [#109624](https://github.com/openclaw/openclaw/pull/109624)
- 更新 DeepSeek、Together 和 Venice 的设置默认值 [#113973](https://github.com/openclaw/openclaw/pull/113973)
- 将全新 Cerebras 设置默认设为 Gemma 4 31B [#114015](https://github.com/openclaw/openclaw/pull/114015)
- 统一设置和发现中的 Ollama 模型检查 [#115879](https://github.com/openclaw/openclaw/pull/115879)
- 在打开聊天前验证 llama.cpp 设置 [#116308](https://github.com/openclaw/openclaw/pull/116308)
- 简化已配置本地模型的恢复 [#117165](https://github.com/openclaw/openclaw/pull/117165)
- 将入门引导中的模型浏览范围限定为所选提供商 [#125373](https://github.com/openclaw/openclaw/pull/125373)
- 在首次运行设置期间跳过已丢弃的工作区加载 [#126967](https://github.com/openclaw/openclaw/pull/126967)
- 更快的首次运行模型检测 [#127053](https://github.com/openclaw/openclaw/pull/127053)

**错误修复**

- 使全新 AI 入门引导可靠且透明 [#103962](https://github.com/openclaw/openclaw/pull/103962)
- 在全新 Mac 设置期间复用 Codex CLI 登录 [#104150](https://github.com/openclaw/openclaw/pull/104150)
- 在引导式入门引导期间恢复分组提供商登录 [#107038](https://github.com/openclaw/openclaw/pull/107038)
- 强化 OpenAI 入门引导和 Crestodian 交接 [#107041](https://github.com/openclaw/openclaw/pull/107041)
- 在设置检测期间保持 Gateway 健康状态响应 [#110625](https://github.com/openclaw/openclaw/pull/110625)
- 解除无配置网关上的模型设置阻塞 [#111841](https://github.com/openclaw/openclaw/pull/111841)
- 在入门引导期间要求可用的导入和本地 AI 路由 [#112028](https://github.com/openclaw/openclaw/pull/112028)
- 防止入门引导崩溃并优先处理订阅登录 [#112378](https://github.com/openclaw/openclaw/pull/112378)
- 在 API 密钥入门引导后显示账户可用的 OpenAI 模型 [#114258](https://github.com/openclaw/openclaw/pull/114258)
- 修复 OpenAI 模型发现和已安装包入门引导 [#114288](https://github.com/openclaw/openclaw/pull/114288)
- 使 Ollama 和 LM Studio 入门引导可靠 [#114405](https://github.com/openclaw/openclaw/pull/114405)
- 保持本地模型发现、重试和云超时正确 [#114582](https://github.com/openclaw/openclaw/pull/114582)
- 引导控制界面用户处理不可用的 AI 设置 [#115716](https://github.com/openclaw/openclaw/pull/115716)
- 当没有可用模型时，将模型设置作为主要恢复操作 [#116079](https://github.com/openclaw/openclaw/pull/116079)
- 选择一个可用的 GitHub Copilot 入门引导模型 [#116590](https://github.com/openclaw/openclaw/pull/116590)
- 通过受支持的认证路由 Google 设置 [#116611](https://github.com/openclaw/openclaw/pull/116611)
- 遵守 Ollama 模型和拉取完成契约 [#117171](https://github.com/openclaw/openclaw/pull/117171)
- 激活在设置期间准备的精确本地模型 [#119050](https://github.com/openclaw/openclaw/pull/119050)
- 在 macOS 上完成 ChatGPT 订阅设置 [#120782](https://github.com/openclaw/openclaw/pull/120782)
- OpenCode 入门引导选择可用模型并保留编码工具 [#121414](https://github.com/openclaw/openclaw/pull/121414)
- 使 Ollama 引导式设置选择并验证一个可用模型 [#123190](https://github.com/openclaw/openclaw/pull/123190)
- 将 llama.cpp 默认上下文提升至 64K [#123701](https://github.com/openclaw/openclaw/pull/123701)
- 完成 macOS Codex 设置和账户模型发现 [#124829](https://github.com/openclaw/openclaw/pull/124829)
- 当设置扫描运行时间过长时检测 CLI 模型登录 [#125114](https://github.com/openclaw/openclaw/pull/125114)
- 在重启后保持 Claude CLI OAuth 可用 [#125471](https://github.com/openclaw/openclaw/pull/125471)
- 将入门引导模型钩子范围限定为所选提供商 [#126427](https://github.com/openclaw/openclaw/pull/126427)
- fix: 保持 Claude CLI 认证为原生 [#129052](https://github.com/openclaw/openclaw/pull/129052)
- fix(anthropic): 原生 Claude 模型显示错误的可用性 [#129346](https://github.com/openclaw/openclaw/pull/129346)
- fix(auth): 使 Codex 登出恢复可操作 [#130866](https://github.com/openclaw/openclaw/pull/130866)
- fix: 在模型设置激活后恢复认证和聊天 [#133106](https://github.com/openclaw/openclaw/pull/133106)
- 保留 GitHub Copilot 设备登录退避 [#103434](https://github.com/openclaw/openclaw/pull/103434)
- 阻止停滞的 GitHub Copilot 令牌交换挂起 [#104488](https://github.com/openclaw/openclaw/pull/104488)
- 查找存储在提供商别名下的模型探测凭据 [#106736](https://github.com/openclaw/openclaw/pull/106736)
- 在入门引导期间完成 Codex OAuth 交接 [#107174](https://github.com/openclaw/openclaw/pull/107174)
- 移除重复的 Codex 提供商设置选项 [#107979](https://github.com/openclaw/openclaw/pull/107979)
- 保留全新安装的 ChatGPT OAuth 凭据 [#108617](https://github.com/openclaw/openclaw/pull/108617)
- 防止 Codex 登录查找挂起 TUI [#109452](https://github.com/openclaw/openclaw/pull/109452)
- 在提供商认证期间忽略空白环境凭据 [#109691](https://github.com/openclaw/openclaw/pull/109691)
- 让 Ollama 设置继续越过损坏的本地模型 [#109895](https://github.com/openclaw/openclaw/pull/109895)
- 阻止损坏的 Ollama 模型声称支持工具 [#109921](https://github.com/openclaw/openclaw/pull/109921)
- fix(onboarding): 停止推荐设置无法激活的工具 [#109951](https://github.com/openclaw/openclaw/pull/109951)
- 当模型检查失败时停止宣传 Ollama 工具 [#109971](https://github.com/openclaw/openclaw/pull/109971)
- 允许在 fake-IP 代理后面进行 OpenAI OAuth 令牌交换 [#110096](https://github.com/openclaw/openclaw/pull/110096)
- 防止失败的入门引导重试覆盖可用设置 [#111558](https://github.com/openclaw/openclaw/pull/111558)
- 让 OpenAI 模型登录在浏览器回调后退出 [#112211](https://github.com/openclaw/openclaw/pull/112211)
- 在发现停滞期间保持控制界面设置响应 [#112338](https://github.com/openclaw/openclaw/pull/112338)
- 阻止停滞的 Microsoft Foundry 设备代码登录挂起入门引导 [#112369](https://github.com/openclaw/openclaw/pull/112369)
- 在入门引导期间复用活动的 Codex API 密钥认证 [#112770](https://github.com/openclaw/openclaw/pull/112770)
- 保持 Web 模型下载进度更新 [#113613](https://github.com/openclaw/openclaw/pull/113613)
- 更新提供商入门引导模型默认值 [#113870](https://github.com/openclaw/openclaw/pull/113870)
- 保持 OpenAI 入门引导选项在账户访问范围内 [#114356](https://github.com/openclaw/openclaw/pull/114356)
- 防止 Doctor 中出现错误的提供商故障 [#114533](https://github.com/openclaw/openclaw/pull/114533)
- 保留入门引导推理探测的内存会话 [#115452](https://github.com/openclaw/openclaw/pull/115452)
- 在入门引导期间保留所选 Ollama 模型能力 [#115467](https://github.com/openclaw/openclaw/pull/115467)
- 保持已验证的 Codex 设置在激活过程中处于活动状态 [#115704](https://github.com/openclaw/openclaw/pull/115704)
- 使 Gemini CLI 设置恢复可操作 [#115835](https://github.com/openclaw/openclaw/pull/115835)
- 在不重启向导的情况下重试 Ollama 设置 [#116210](https://github.com/openclaw/openclaw/pull/116210)
- 协调设置和模型设置写入 [#116940](https://github.com/openclaw/openclaw/pull/116940)
- 停止抓取 Gemini CLI OAuth 凭据 [#117167](https://github.com/openclaw/openclaw/pull/117167)
- 在设置期间仅使用已加载的 LM Studio 模型 [#117919](https://github.com/openclaw/openclaw/pull/117919)
- 在入门引导期间检测可访问的 Ollama 服务 [#118020](https://github.com/openclaw/openclaw/pull/118020)
- 移除不受支持的 Google 认证和配额指导 [#118034](https://github.com/openclaw/openclaw/pull/118034)
- 在引导式设置期间避免加载空闲的 Ollama 模型 [#118183](https://github.com/openclaw/openclaw/pull/118183)
- 在引导式设置期间检测正在运行但没有加载模型的 LM Studio [#119134](https://github.com/openclaw/openclaw/pull/119134)
- 在已安装的本地 TUI 模式中恢复提供商认证 [#119283](https://github.com/openclaw/openclaw/pull/119283)
- 修复 macOS AI 入门引导视觉效果和 Keychain 回退 [#120907](https://github.com/openclaw/openclaw/pull/120907)
- 修复无认证本地模型和提示模板错误处理 [#121790](https://github.com/openclaw/openclaw/pull/121790)
- 使 macOS 入门引导候选行完全可点击 [#121928](https://github.com/openclaw/openclaw/pull/121928)
- 当 AI 访问检测超时时显示可重试错误 [#121940](https://github.com/openclaw/openclaw/pull/121940)
- 移除重复的 GPT-5.6 选择器条目 [#122178](https://github.com/openclaw/openclaw/pull/122178)

在模型设置对话框中保留较长的 OAuth 设置链接 #122892
- fix(openai): 为格式错误的 OAuth token JSON 返回结构化失败 #122962
- 在登录不可用时显示已配置模型 #123130
- 使 Codex 的“测试并使用”操作可从模型设置中完成 #123141
- 在 CLI 设置期间选择最小且满足要求的本地 Ollama 模型 #123382
- 在提供商授权后保持模型设置处于活动状态 #123418
- 在脚本化 macOS 引导流程中读取 Claude CLI 钥匙串身份验证 #123839
- fix(system-agent): 在本地模型设置探测中为推理预留空间 #124405
- 在无效回调后保持 OpenRouter 登录等待状态 #124922
- 将引导流程的提供商元数据限定在所选提供商范围内 #125379
- 准确显示 OpenAI OAuth 恢复状态，而不掩盖提供商故障 #125515
- fix(tui): 当会话提供商由 CLI 支持时，本地 /auth 以退出码 1 退出且没有诊断信息 #125677
- 使 llama-server 身份验证更改可复现 #126498
- 在引导流程中将 OpenRouter API 密钥保留在 OpenRouter 中 #126578
- fix(ui): 对于全新客户端，模型设置卡在“正在检查此 Gateway” #127695
- fix(ollama): 将本地服务查找延迟到流创建时 #128399
- fix(ui): 在检查 AI 访问时保持模型设置可见 #128636
- fix(macos): 允许冷启动 ChatGPT Codex 探测 #128819
- fix(agents): 保留设置 CLI 的模型解析 #129128
- fix(onboarding): OpenAI 设置安装了不匹配的 Codex 插件 #129195
- fix: 将原生 Claude CLI 模型报告为可用 #129332
- fix(ollama): 取消的云设置继续执行并返回凭据 #129541
- fix(onboard): 保留与清单等效的别名验证 #129590
- fix(onboard): 拒绝不可用的必需运行时 #129855
- fix(ollama): 当模型检查不可用时，保留已通告的上下文和工具 #130000
- fix(llama-cpp): 在设置期间停止推荐失败的模型 #130136
- fix(anthropic): 防止已弃用的 Claude CLI 配置文件破坏设置 #130225
- fix(ollama): 当检查返回空结果时，云模型从发现中消失 #130240
- fix: 遵循新的提供商目录发现 #130412
- fix(ollama): 保持本地设置仅本地，并跳过嵌入聊天默认值 #130459
- fix(setup): 将已被取代的目录刷新视为激活成功 #130795
- fix(setup): 在创建第一个代理时保留已验证的推理 #132472
- 清理 OpenAI Codex OAuth 回调和过期提示 #89491
- 接受由辅助程序管理的 Claude CLI 身份验证 #97492
- 在引导流程中省略空的提供商请求设置 aad9974
- 使用 30 秒超时限制 MiniMax OAuth 请求 #102862
- 防止 GitHub Copilot 设备登录无限挂起 #103255
- 抑制已显式启用插件的信任警告 #104097
- 准确显示 OpenRouter OAuth 拒绝错误 #105448
- 清理 GitHub Copilot 登录轮询监听器 #106453
- 从引导式入门候选项中移除占位文本 #110084
- 在响应后释放 Ollama 设置连接 #111802
- 说明如何从 GitHub Copilot 403 错误中恢复 #112025
- 遵循 Azure 设备代码登录窗口 #113741
- 刷新 Qianfan 引导流程默认值，并隔离 OpenAI 实时测试 #113999
- 干净地拒绝格式错误的 OpenAI OAuth token 响应 #120685
- 修复选择 Codex 运行时时的提供商密钥测试 #121500
- 允许用户在 macOS 引导流程中切换 AI 候选项 #121613
- 使 Codex 引导流程能够容忍继承的加载器路径 #122731
- 在输入 API 密钥后停止错误的缺少身份验证警告 #122756
- 保持 OpenAI 设置的身份验证选项一致 #124729
- 重试首次运行时的临时模型检测 #125212
- 停止错误的提供商设置警告 #125523
- 识别已存在的 CLI 登录以判断已配置模型可用性 #125772
- 修复 Web UI 中直接凭据的提供商探测 #125816
- 在非交互式引导流程中停止错误的插件警告 #126734
- fix: 在状态中报告原生 Claude CLI 身份验证 #129364
- fix: 在 Doctor 健康检查前清理已弃用的 Claude 身份验证 #129375
- fix(llama-cpp): 现有服务器设置优先选择就绪模型 #129509
- fix(ollama): 设置尽管明确为非思考能力仍选择超大模型 #129611
- fix(ollama): 允许使用任何已安装的本地模型重置设置 #129934

文档

- docs(onboarding): 在设置指南中保留所选模型 [#128547](https://github.com/openclaw/openclaw/pull/128547)

</details>

开始你的第一次对话

成功设置现在会直接交接给第一次对话。图形化 Mac、Linux 和 Windows 会话可以打开网页应用，而 SSH 和其他无头设置会提供带有端口转发说明的已认证链接，并保持终端聊天可用。

从那里开始，设置对话可以完成受支持的技能和网络搜索配置，然后将外部渠道作为可选的下一步提供，而不是首次使用的另一个先决条件。经典向导仍可在没有 AI 的情况下继续，因为其实时模型检查仍然是可选的。

来源和完整变更列表

改进

引导式 CLI 设置在保存前验证 AI 访问 #101880
根据已安装应用推荐插件和技能 #109668
将引导式入门引导设为本地 Custodian 流程 #109841
在引导式 macOS 入门引导后添加浏览器优先交接 #110054
添加对话式 Custodian 入门引导 #110141
持久化入门引导推荐并缩短首次运行的身份设置 #110173
添加带类型的入门引导问题，并支持实时选项卡片 #110242
将全新设置交接给智能体的首次聊天 #110331
扩展浏览器入门引导并刷新应用推荐 #110484
为 Custodian 聊天添加丰富的设置控件 #114631
在 Ask OpenClaw 中配置技能和网络搜索 #115130
在 Ask OpenClaw 中引导本地 Gateway 配置 #115363
在首次运行模型设置后引导可选渠道设置 #116078
在入门引导期间为第一个智能体命名 #123521
添加可选启用的无密钥 Firecrawl 搜索以及更丰富的搜索控件 #97078
允许用户为新智能体命名 #112009
明确网络搜索设置选项 #112199
在入门引导应用扫描期间显示实时进度 #112414
在生成时约束系统智能体规划器 JSON #113482
提供可选工作区文件，而不产生虚假的缺失警告 #114559

Bug 修复

使 Gateway 入门引导推理优先且路由安全 #102883
使对话式设置在本地模型上实用 #109445
在 macOS 入门引导中显示可操作的选项卡片 #110584
避免 Custodian 健康提醒出现在托管向导答案中 #111430
使首次运行的浏览器入门引导可靠 #111465
按工作区隔离入门引导推荐 #111560
将新智能体 hatch 附加到正在运行的 Gateway #122210
保持引导式智能体凭据与创建一致 #126096
终端渠道设置中的返回导航 #108007
在设置聊天中要求十进制菜单编号 #108140
将设置推理修复返回到聊天 #109938
使设置向导的复制按钮在纯 HTTP 上可用 #110139
统一 Ask OpenClaw 的表述和确认默认值 #111263
保持系统智能体模型更改在已验证路由上 #111431
当设置被跳过时立即退出入门引导 #112165
标记入门引导字段并掩码 Matrix 凭据 #112233
避免在已验证的 TUI 启动期间进行目录准备 #113136
全新安装可发现外部搜索插件并执行首个任务 #114327
在入门引导期间等待真正的新浏览器 #117431
在 Gateway 安装进度中保持渠道设置继续 #117877
在设置期间报告失败的浏览器启动 #117979
在入门引导交接前构建 Control UI #118038
在入门引导和配对期间显示剪贴板失败 #118651
fix(tui): 在退出回退前关闭设置网关 #121183
在开发 Gateway 名册上恢复设置聊天 #121784
拆分系统智能体聊天所有权并保留交接状态 #121884
保持智能体引导在 Gateway 的 OpenClaw CLI 上 #122765
当 Custodian 渠道设置检查失败时添加恢复 #124680
在无显示器的 WSL 中打开浏览器交接 #124704
安全地完成引导式智能体创建 #125768
fix(onboard): 在浏览器启动失败后恢复手动交接 #130272
在插件设置中拒绝无效数值 #107346
在入门引导推荐说明中保留表情符号 #110401
在设置向导中跳过空白区域设置覆盖 #111076
为全新命名智能体保留首轮 hatch #111553
将系统维护保留在设置下 #111686
防止入门引导进度指示器刷屏窄终端 #112413
当适用时仅显示一次设置取消提示 #113731
在引导式入门引导中保留 skip-UI 设置 #118737
在设置期间接受智能体名称 #124740
在引导式入门引导中保留命名智能体 #126365
在引导式入门引导中保留 Token 抑制 #126580
fix(ollama): 为原生聊天启动本地服务 #128034
fix(onboard): 将 hatch 超时限定到初始轮次 #130010
fix(onboard): 终端 hatch 在引导式设置后连接 #130082
fix(onboarding): --skip-bootstrap 仍会创建身份文件 #130153
fix: 为网页和终端用户提供正确的智能体交接指导 #131646
fix(onboard): 在引导式设置中启用默认钩子 #131894

文档

- 记录 Ask OpenClaw Gateway 和内存向导 [#115487](https://github.com/openclaw/openclaw/pull/115487)
- 刷新文档主视觉并完成快速入门网格 [#102880](https://github.com/openclaw/openclaw/pull/102880)
- 统一经典入门文档 [#124712](https://github.com/openclaw/openclaw/pull/124712)
- 更正文档中经典入门的步骤顺序 [#125454](https://github.com/openclaw/openclaw/pull/125454)

</details>

在 Mac、Windows 和 Linux 上设置 OpenClaw

在 Mac 上，主指南直接指向应用，并且你选择的本地或远程 Gateway 会保持选中状态，即使较早的启动或清理工作较晚完成。应用会等待 Local Network 提示和合法的首次运行数据升级，在继续之前先对确切的远程 Gateway 进行身份验证，并且仅在连接就绪时打开仪表盘。

在 Windows 上，指南指向最新的已签名 x64 和 Arm64 Hub 安装程序。PowerShell 安装程序现在能够正确识别受支持的 Node 运行时，并可以在 Winget 安装 Node.js 后在同一会话中继续。Windows Hub 独立更新，因此其独立稳定版构建可能比随 OpenClaw 版本包含的镜像更新。

在 Linux 上，桌面设置可以修复或重新安装 OpenClaw，直接或通过 SSH 连接到本地或远程 Gateway，验证机器上已有的符合条件的 AI 访问，并恢复被中断的激活。桌面应用内仍不支持直接的证书固定连接。

来源和完整变更列表

改进

缩短 macOS 入门流程并移交给 Custodian #117921
在 macOS AI 设置完成后立即打开仪表盘 #120950
feat: 使 Linux 桌面入门达到 macOS 同等水平 #129815
允许 macOS 入门使用更高的窗口 #104004
improve(installer): 减少 Windows Git 克隆下载 #130908

错误修复

使 macOS AI 入门遵循已连接的 Gateway #102637
为已配置的 Gateway 打开 macOS 仪表盘 #102677
使全新的 macOS 本地设置可靠启动并激活 #108764
使 macOS 入门权限在短屏幕上可滚动 #112507
要求 Gateway 身份验证后才能进行 macOS 远程入门 #117904
解除 macOS 首次启动 Gateway 设置的阻塞 #119831
让首次运行的 macOS gateway 迁移完成 #121012
在共享状态迁移期间恢复 macOS 入门 #121313
fix(linux): 在桌面伴侣中提供真实的安装失败、安装后修复和可访问的重新安装 #128614
fix(linux): 首次运行的桌面入门自动连接可用的 AI #129211
fix(state): 在启动检查点表之前规范地初始化全新状态 #129850
fix(desktop): 在模型激活和重启之间保留入门状态 #131757
在 macOS 入门期间启动现有的 CLI Gateway #104051
让 Return 键推进 macOS 入门并澄清缺失 CLI 的恢复 #104705
防止 macOS 入门安装程序输出挂起 #104827
防止 macOS 入门被截断和停滞 #107598
在 macOS 上拒绝公共明文 Gateway 配置文件 #112161
在 Gateway 进度步骤中保持 macOS 设置轮询 #114383
降低 macOS 入门的空闲 CPU 使用 #115896
保持 macOS 入门等待 Local Network 权限 #120859
在 Gateway 启动期间等待并发首次运行迁移 #120959
在 macOS 入门期间显示 Gateway 启动失败原因 #121306
将 macOS 配置文件入门保留在其管理的 CLI 内 #121651
在稳定的 Gateway 端口上隔离命名配置文件 #122751
及时报告 macOS Gateway 启动的最终失败 #126697
在远程 macOS 入门期间自动安装 CLI #126723
隔离 macOS 配置文件并报告直接 Gateway 端点 #127007
在本地 Gateway 失败后恢复 macOS 远程入门 #127033
在 Gateway 更改后保持首次运行的 macOS 入门可见 #127038
fix(macos): 在切换连接模式时保留远程隧道 #127665
fix: macOS 入门等待 Gateway 重启 #127713
fix(mac): 在延迟的本地故障后保持远程 Gateway 连接 #127723
fix(macos): 使 OpenClaw 设置窗格具有响应性 #128177
fix(macos): 当 Gateway 启动失败时保持 CLI 安装完整 #128350
fix(macos): 显示正确首次运行入门进度 #129435
fix(macos): 在 API 密钥验证期间确认关闭入门 #129447
fix(macos): 在入门期间选择受支持的 Node 版本 #129564
fix(macos): 阻止远程入门安装本地 gateway #129572
fix(macos): 显示保存失败而不是无尽的入门加载 #129959
fix(onboard): 为未更改的端点保留远程 gateway TLS 固定 #131042
fix(ui): 在管理的 CLI 缺失时恢复 #131974
保持 Swift 设备配对与旧版 gateway 兼容 #80656
防止 Windows 安装程序错误拒绝 Node #106252
在 winget 安装 Node.js 后继续 Windows 设置 #106862
更正 macOS 入门期间命名配置文件 Gateway 指南 #121614
fix(macos): 防止过时的模式切换停止新的 Gateway #127609
fix(mac): 保持 node 服务与最新连接模式一致 #127732
fix(macos): 当 gateway 已在运行时解决入门安装提示 #128273
fix(macos): 停止将损坏的 Gateway 可执行文件报告为就绪 #129453
fix(linux): 当 gateway 重启时保持首次运行入门存活 #129502
fix(macos): 暂停的 Gateway 设置在 CLI 安装后丢失恢复 #129566
fix: macOS 设置在验证现有 AI 连接时未警告即关闭 #129790
fix: macOS 入门重试静默重新检查失败的 AI 连接 #129863
fix(macos): 入门设置行忽略其空白区域的点击 #130273
fix(onboard): SSH 隧道提示对 TLS gateway 使用 HTTPS #130313
fix(installer): 固定 NodeSource RPM 仓库 #132286
更正 macOS 远程 gateway URL 指南 #98548
在 macOS CLI 中尊重自定义配置路径 #98631
当 macOS 应用在登录时启动时保留自定义 OpenClaw 配置文件 #99752

文档

- 引导 Windows 用户使用最新的独立 Hub 安装程序 [#104774](https://github.com/openclaw/openclaw/pull/104774)
- 将 macOS 入门引导链接到应用下载 [#111361](https://github.com/openclaw/openclaw/pull/111361)
- docs(install)：为普通应用安装显示桌面应用下载链接 [#127991](https://github.com/openclaw/openclaw/pull/127991)

</details>

在 iPhone、iPad 和 Android 上设置 OpenClaw

移动设备设置现在将二维码和设置代码配对放在首位，因为大多数人本来就在寻找这个功能，同时发现的 Gateway 以及手动输入主机和凭据仍然可用。安全的官方配对会显示手机具有完全访问权限还是有限访问权限，并且到另一台机器的未加密连接会自动保持为有限访问。

在 iPhone 和 iPad 上，当连接已被信任或与代码匹配时，有效的设置二维码现在可以一次扫描完成配对并打开主界面，而不可信连接仍会暂停等待批准。OpenClaw 会在请求本地网络访问权限之前解释配对过程，让你逐项决定可选权限，并为符合条件的管理员提供一个专用的设置对话，用于 Gateway 设置和修复，而不会在普通聊天中暴露该特权助手。

在 Android 上，配对在横屏、窄屏和更大的系统文字下仍可使用。公共 Gateway 可以使用常规证书检查，而 LAN 和 IP 连接保持显式固定，并且再次配对会保留已保存的位置和通知选择，而不是悄悄更改同意状态；已撤销的权限保持撤销状态，Google Play 版本仍仅使用前台位置。

来源和完整更改列表

改进

具有显式有限模式的完全访问移动配对 #105928
将 iOS Gateway 二维码配对置于突出位置 #106111
引导 iOS 首次启动完成配对和权限 #106129
在设置中突出显示 Android Gateway 配对 #106211
添加 Android 系统信任和手动 Gateway 固定 #110976
为 iOS 添加 OpenClaw 设置助手 #112420
让 iOS 入门引导的连接状态更清晰 #101921
刷新访问状态屏幕的原生翻译 #106260

错误修复

替换无法使用的 iOS Gateway 连接 #103289
在 TLS 检查期间保留 Android Gateway 主机名 #105072
让 Android 入门引导在横屏和大文字下自适应 #108405
配对后保持新的 iOS 设置连接 #108779
在大文字下保持 Android 入门引导操作可访问 #111747
将 Android 连接到粘贴的 Gateway 主机和端口 #113722
fix(gateway)：防止安全链接创建挂起 #128545
fix(android)：防止不可用的短信重新打开入门引导审批 #129077
fix(android)：在入门引导期间保留后台位置 #129543
fix(android)：保留通知转发同意 #129715
fix(android)：在入门引导期间保留已禁用的位置同意 #129961
fix(android)：序列化旧版 Gateway 发现 #131001
fix(ios)：一步完成二维码配对 #131267
允许 Android 入门引导权限文本换行 #103649
在重连期间保持 iOS Gateway 错误可见 #105875
fix(android)：跳过作用域 IPv6 发现地址 #130165
fix(ios)：停止将不完整的 Gateway 设置归咎于设备存储 #130407
在 iOS 入门引导期间聚焦缺失的 Gateway 凭据 #98189

文档

将手机浏览器恢复与原生节点配对分开 #123767

移动、导入或重置现有设置

从 Claude、Codex 和 Hermes 导入现在发生在临时暂存区域，OpenClaw 会在使新设置生效之前验证或修复模型路由。如果源、导入计划或目标在过程中发生变化，启用流程会停止，而不是将未完成的导入重放到不同的数据上。

重新运行入门引导会保留你已使用的工作区，除非你批准移动，并且命名代理在支持的创建和仅配置重置中保留其拥有的凭据。OpenClaw 会在重置可以将现有数据移动到回收站之前验证提供商、Gateway、迁移和工作区选择，但有效的已确认重置仍然是破坏性的。

来源和完整更改列表

改进

- 在发布引导迁移之前先暂存它们 [#112798](https://github.com/openclaw/openclaw/pull/112798)
- 允许安全地将 main 复用为 agent ID [#123609](https://github.com/openclaw/openclaw/pull/123609)

**Bug 修复**

- 使失败的 Hermes 引导导入可重试 [#103290](https://github.com/openclaw/openclaw/pull/103290)
- 导入当前 Hermes 状态和 provider 契约 [#106758](https://github.com/openclaw/openclaw/pull/106758)
- 在删除状态之前验证引导重置 [#111348](https://github.com/openclaw/openclaw/pull/111348)
- 将引导效果保留在已配置的默认 agent 上 [#112738](https://github.com/openclaw/openclaw/pull/112738)
- 允许在状态初始化之后进行首次运行导入 [#122967](https://github.com/openclaw/openclaw/pull/122967)
- 让多 agent CLI 操作与其所属 agent 保持一致 [#123871](https://github.com/openclaw/openclaw/pull/123871)
- fix(onboard)：保留命名首个 agent 的 provider 凭据 [#127572](https://github.com/openclaw/openclaw/pull/127572)
- 在 Codex 引导期间保留插件所有权 [#103372](https://github.com/openclaw/openclaw/pull/103372)
- 重新运行引导时保留 Gateway 设置 [#111569](https://github.com/openclaw/openclaw/pull/111569)
- 在引导重跑期间保留现有 agent 工作区 [#111787](https://github.com/openclaw/openclaw/pull/111787)
- 在快速入门引导期间遵循显式 Gateway 选项 [#112396](https://github.com/openclaw/openclaw/pull/112396)
- 隔离非默认 gateway 工作区和 skills [#114487](https://github.com/openclaw/openclaw/pull/114487)
- 迁移期间保留旧版模型限制 [#114983](https://github.com/openclaw/openclaw/pull/114983)
- 在无头重置期间保护 OpenClaw 状态 [#116491](https://github.com/openclaw/openclaw/pull/116491)
- 在保留当前模型时遵循显式 provider 身份验证 [#117883](https://github.com/openclaw/openclaw/pull/117883)
- 在手动引导期间遵循 Gateway CLI 设置 [#122961](https://github.com/openclaw/openclaw/pull/122961)
- 让引导导入在运行时状态初始化后仍然有效 [#123106](https://github.com/openclaw/openclaw/pull/123106)
- 为引导式设置迁移旧版 Ollama 配置文件 [#123341](https://github.com/openclaw/openclaw/pull/123341)
- Doctor 处理显式多 agent 配置文件时不会误报失败 [#124010](https://github.com/openclaw/openclaw/pull/124010)
- 在新安装中停止幽灵身份验证迁移通知 [#124929](https://github.com/openclaw/openclaw/pull/124929)
- 在经典引导中对 agent 导入进行分组 [#126515](https://github.com/openclaw/openclaw/pull/126515)
- 当引导内存导入失败时显示可重试错误 [#126738](https://github.com/openclaw/openclaw/pull/126738)
- 在引导期间遵循已配置的系统 agent [#126861](https://github.com/openclaw/openclaw/pull/126861)
- fix(doctor)：迁移后保持 Claude CLI 覆盖项可选 [#126866](https://github.com/openclaw/openclaw/pull/126866)
- 在保留现有模型时遵循 provider 凭据 [#126946](https://github.com/openclaw/openclaw/pull/126946)
- fix：在引导期间保留旧版工作区 [#127059](https://github.com/openclaw/openclaw/pull/127059)
- fix(onboard)：在配置重置期间保留命名 agent 配置文件 [#127716](https://github.com/openclaw/openclaw/pull/127716)
- fix(onboard)：provider 设置会在受管集群中更改错误的 agent 模型 [#128119](https://github.com/openclaw/openclaw/pull/128119)
- fix(migrate-claude)：重新运行 Claude 迁移会重复导入的指令 [#130429](https://github.com/openclaw/openclaw/pull/130429)
- fix：doctor 跳过每个 agent 的旧版模型引用 [#130725](https://github.com/openclaw/openclaw/pull/130725)
- fix(configure)：添加自定义 provider 时保留现有主模型 [#131034](https://github.com/openclaw/openclaw/pull/131034)
- fix(configure)：在 provider 身份验证覆盖中保留主模型 [#131119](https://github.com/openclaw/openclaw/pull/131119)
- 在 Claude CLI 迁移期间保留 Anthropic 模型设置 [#103622](https://github.com/openclaw/openclaw/pull/103622)
- 在迁移配置导入中阻止原型污染 [#106116](https://github.com/openclaw/openclaw/pull/106116)
- 在引导迁移期间处理非目录路径 [#109161](https://github.com/openclaw/openclaw/pull/109161)
- 在引导期间为每个 agent 重置会话历史 [#112610](https://github.com/openclaw/openclaw/pull/112610)
- 当引导配置不可读时保护默认工作区 [#114110](https://github.com/openclaw/openclaw/pull/114110)
- 当缺少 reset 时拒绝 reset 范围 [#115554](https://github.com/openclaw/openclaw/pull/115554)
- 在新安装中隐藏空的 Matrix 迁移噪音 [#122808](https://github.com/openclaw/openclaw/pull/122808)
- 在 Configure 中保留系统 agent 工作区所有权 [#125377](https://github.com/openclaw/openclaw/pull/125377)
- 将旧版模型引用警告指向 Doctor 的迁移命令 [#125660](https://github.com/openclaw/openclaw/pull/125660)
- 将命名引导状态保留在已创建的 agent 上 [#126463](https://github.com/openclaw/openclaw/pull/126463)
- fix(onboard)：当 --import-from 未知时列出可用 provider [#127780](https://github.com/openclaw/openclaw/pull/127780)
- fix(stepfun)：重复引导时保留已选模型 [#129045](https://github.com/openclaw/openclaw/pull/129045)
- fix(onboard)：保留已保存的 skills 包管理器 [#130438](https://github.com/openclaw/openclaw/pull/130438)

</details>

自动化设置与从中断中恢复

非交互式引导现在会在创建 agent 或写入配置之前拒绝无效的 provider、身份验证、Gateway、工作区以及冲突的流程选择。当请求 --json 时，失败会返回一个机器可读的结果，而不是空输出或混合输出；对于同一 profile 的并发设置，如果已知当前持有者，则会快速失败并显示当前持有者，而不是看起来卡住。

已取消或中断的设置会撤销过期工作，而失败的提供商登录或本地模型准备可以在不取消较新尝试的情况下重试。Gateway 健康检查失败会保留在设置流程内，并附带原始诊断信息和恢复提示，但 --json 不会免除风险确认，并且有意跳过服务启动仍可能在没有可访问 Gateway 的情况下完成，因此自动化必须检查报告的健康状态，而不能仅信任退出状态。

<details class="release-source-toggle">
<summary>来源和完整变更列表</summary>

**改进**

- 让设置和 doctor 修复遵循统一的安全顺序 [#114375](https://github.com/openclaw/openclaw/pull/114375)
- 为 Custodian 设置添加一键取消 [#118953](https://github.com/openclaw/openclaw/pull/118953)

**Bug 修复**

- 恢复仪表板和中断的首次设置 [#118388](https://github.com/openclaw/openclaw/pull/118388)
- 让中断的引导可安全取消、重试和恢复 [#121415](https://github.com/openclaw/openclaw/pull/121415)
- 将健康检查失败保留在设置流程内 [#126758](https://github.com/openclaw/openclaw/pull/126758)
- fix(ui): 防止中断的模型设置阻塞重试 [#127657](https://github.com/openclaw/openclaw/pull/127657)
- 在设置写入前拒绝无效的引导选项 [#111680](https://github.com/openclaw/openclaw/pull/111680)
- 在基线设置期间保留无效配置 [#112010](https://github.com/openclaw/openclaw/pull/112010)
- 在 Gateway 重启后恢复过期的设置向导 [#112286](https://github.com/openclaw/openclaw/pull/112286)
- 恢复全新的非交互式引导 [#113601](https://github.com/openclaw/openclaw/pull/113601)
- 在创建设置状态前验证非交互式引导 [#114823](https://github.com/openclaw/openclaw/pull/114823)
- 防止托管设置退出停止 Gateway [#115671](https://github.com/openclaw/openclaw/pull/115671)
- 防止取消后出现重叠的远程设置 [#115856](https://github.com/openclaw/openclaw/pull/115856)
- 在 Gateway 配置重载期间保持托管向导存活 [#120582](https://github.com/openclaw/openclaw/pull/120582)
- 串行化引导和插件安装 [#121482](https://github.com/openclaw/openclaw/pull/121482)
- Gateway 设置在锁释放失败后恢复 [#121915](https://github.com/openclaw/openclaw/pull/121915)
- 在终端向导状态后允许替换设置 [#122054](https://github.com/openclaw/openclaw/pull/122054)
- 当另一个引导会话处于活动状态时快速失败 [#122968](https://github.com/openclaw/openclaw/pull/122968)
- 让有意未启动的 Gateway 完成引导 [#123857](https://github.com/openclaw/openclaw/pull/123857)
- 在 Ctrl-D 或 stdin 关闭时干净地取消引导 [#124780](https://github.com/openclaw/openclaw/pull/124780)
- 在 JSON 摘要中报告引导健康失败 [#126801](https://github.com/openclaw/openclaw/pull/126801)
- 在远程引导中拒绝本地 Gateway 凭据 [#127015](https://github.com/openclaw/openclaw/pull/127015)
- fix(onboard): 停止为单个失败打印两条相互矛盾的 Fix 行 [#127698](https://github.com/openclaw/openclaw/pull/127698)
- fix(onboard): 拒绝没有有效 customBindHost 的 --gateway-bind custom [#127779](https://github.com/openclaw/openclaw/pull/127779)
- fix(onboard): 没有终端时 JSON 命令不返回输出 [#129437](https://github.com/openclaw/openclaw/pull/129437)
- fix(cli): 当现有配置无效时输出 JSON 失败 [#129578](https://github.com/openclaw/openclaw/pull/129578)
- refactor(system-agent): 统一操作员交接和提案生命周期 [#131630](https://github.com/openclaw/openclaw/pull/131630)
- 允许完成后立即替换设置向导 [5c308e0](https://github.com/openclaw/openclaw/commit/5c308e0)
- 在完成向导会话前释放设置准入 [f3e1efe](https://github.com/openclaw/openclaw/commit/f3e1efe)
- 拒绝未知的非交互式引导身份验证选择 [#111409](https://github.com/openclaw/openclaw/pull/111409)
- 在自动化引导期间忽略空白工作区输入 [#115537](https://github.com/openclaw/openclaw/pull/115537)
- 拒绝相互矛盾的非交互式 TUI 引导 [#115573](https://github.com/openclaw/openclaw/pull/115573)
- 拒绝冲突的自定义模型输入标志 [#115595](https://github.com/openclaw/openclaw/pull/115595)
- 在本地引导期间拒绝仅限远程的标志 [#115636](https://github.com/openclaw/openclaw/pull/115636)
- 当请求的守护进程安装失败时使引导失败 [#122845](https://github.com/openclaw/openclaw/pull/122845)
- 防止失败的工作区设置发布引导配置 [#124092](https://github.com/openclaw/openclaw/pull/124092)
- 拒绝来自环境引导的命令样式 API 密钥 [#126776](https://github.com/openclaw/openclaw/pull/126776)
- 拒绝引导推荐操作中被忽略的选项 [#126973](https://github.com/openclaw/openclaw/pull/126973)
- 让引导身份验证选择帮助与接受的值匹配 [#127030](https://github.com/openclaw/openclaw/pull/127030)
- fix(onboard): 在选项验证失败时输出 JSON [#127794](https://github.com/openclaw/openclaw/pull/127794)
- fix(onboard): 为其余非交互式选项拒绝输出 JSON [#127976](https://github.com/openclaw/openclaw/pull/127976)
- fix(onboarding): 为被拒绝的设置选项保留 JSON 输出 [#128542](https://github.com/openclaw/openclaw/pull/128542)
- fix(onboard): 拒绝无效的提供商选择而不静默成功 [#128574](https://github.com/openclaw/openclaw/pull/128574)
- fix(cli): 让受管 Gateway 和 Node 恢复提示可操作 [#129243](https://github.com/openclaw/openclaw/pull/129243)
- fix(node): 损坏的 Node 服务建议修复 Gateway [#129545](https://github.com/openclaw/openclaw/pull/129545)
- fix(onboarding): 恢复提示指向错误的 Gateway [#129577](https://github.com/openclaw/openclaw/pull/129577)
- fix(setup): 为无效基线配置输出 JSON 失败 [#129867](https://github.com/openclaw/openclaw/pull/129867)
- fix(onboarding): 缺少 ESM 包的错误遗漏修复提示 [#130159](https://github.com/openclaw/openclaw/pull/130159)
- fix(onboarding): 远程重试提示遗漏必需的风险确认 [#130174](https://github.com/openclaw/openclaw/pull/130174)
- fix(cli): 为被拒绝的引导推荐选项返回 JSON 错误 [#130245](https://github.com/openclaw/openclaw/pull/130245)
- fix(onboard): 远程设置不再启用本地钩子 [#130292](https://github.com/openclaw/openclaw/pull/130292)
- fix(doctor): 停止将延迟创建的会话目录标记为缺失 [#130704](https://github.com/openclaw/openclaw/pull/130704)
- fix(wizard): 确认要求字面量 true [#131238](https://github.com/openclaw/openclaw/pull/131238)

文档

- 修复非交互式入门命令示例 [#121954](https://github.com/openclaw/openclaw/pull/121954)
- 更正入门命令和 Google Chat 凭据 [#118936](https://github.com/openclaw/openclaw/pull/118936)
- 更正入门设置命令 [#126964](https://github.com/openclaw/openclaw/pull/126964)

</details>

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw