diff --git a/docs/zh-CN/providers/ollama.md b/docs/zh-CN/providers/ollama.md index b6fe4361d..00b96d748 100644 --- a/docs/zh-CN/providers/ollama.md +++ b/docs/zh-CN/providers/ollama.md @@ -1,24 +1,24 @@ --- read_when: - 你想通过 Ollama 使用云端或本地模型运行 OpenClaw - - 你需要 Ollama 的设置和配置指南 -summary: 使用 Ollama 运行 OpenClaw（云端和本地模型） + - 你需要 Ollama 的设置和配置指导 +summary: 使用 Ollama（云端和本地模型）运行 OpenClaw title: Ollama x-i18n: - generated_at: "2026-04-12T11:08:21Z" + generated_at: "2026-04-15T13:38:11Z" model: gpt-5.4 provider: openai - source_hash: ec796241b884ca16ec7077df4f3f1910e2850487bb3ea94f8fdb37c77e02b219 + source_hash: 098e083e0fc484bddb5270eb630c55d7832039b462d1710372b6afece5cefcdf source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），支持流式传输和工具调用，并且当你通过 `OLLAMA_API_KEY`（或认证配置）启用时，且未显式定义 `models.providers.ollama` 条目，它可以自动发现本地 Ollama 模型。 +OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、直接连接 `https://ollama.com` 的 `Cloud only`，或连接可访问的 Ollama 主机的 `Local only`。 -**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` 的 OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要带 `/v1`）。 +**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` 的 OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要加 `/v1`）。 ## 入门指南 @@ -27,7 +27,7 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 - **最适合：** 以最快路径完成可用的 Ollama 设置，并自动发现模型。 + **最适合：** 以最快路径完成可用的 Ollama 云端或本地设置。 @@ -35,18 +35,17 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 openclaw onboard ``` - 从提供商列表中选择 **Ollama**。 + 在提供商列表中选择 **Ollama**。 - - **Cloud + Local** — 同时使用云端托管模型和本地模型 - - **Local** — 仅使用本地模型 - - 如果你选择 **Cloud + Local**，但尚未登录 ollama.com，新手引导会打开浏览器登录流程。 + - **Cloud + Local** — 本地 Ollama 主机加上通过该主机路由的云模型 + - **Cloud only** — 通过 `https://ollama.com` 使用托管的 Ollama 模型 + - **Local only** — 仅使用本地模型 - 新手引导会发现可用模型并推荐默认选项。如果所选模型尚未在本地可用，它会自动拉取该模型。 + `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云模型的默认值。`Cloud + Local` 和 `Local only` 会要求提供 Ollama 基础 URL、发现可用模型，并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。 - + ```bash openclaw models list --provider ollama ``` @@ -61,7 +60,7 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 --accept-risk ``` - 你也可以选择性指定自定义 base URL 或模型： + 也可以选择指定自定义基础 URL 或模型： ```bash openclaw onboard --non-interactive \ @@ -74,13 +73,15 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 - **最适合：** 完全控制安装、模型拉取和配置。 + **最适合：** 完全控制云端或本地设置。 - - 从 [ollama.com/download](https://ollama.com/download) 下载。 + + - **Cloud + Local**：安装 Ollama，使用 `ollama signin` 登录，并通过该主机路由云请求 + - **Cloud only**：使用 `https://ollama.com` 并提供 `OLLAMA_API_KEY` + - **Local only**：从 [ollama.com/download](https://ollama.com/download) 安装 Ollama - + ```bash ollama pull gemma4 # 或 @@ -89,31 +90,27 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 ollama pull llama3.3 ``` - - 如果你也想使用云端模型： - - ```bash - ollama signin - ``` - - 为 API 密钥设置任意值即可（Ollama 不需要真实密钥）： + 对于 `Cloud only`，请使用真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以： ```bash - # 设置环境变量 + # 云端 + export OLLAMA_API_KEY="your-ollama-api-key" + + # 仅本地 export OLLAMA_API_KEY="ollama-local" # 或在你的配置文件中设置 - openclaw config set models.providers.ollama.apiKey "ollama-local" + openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 ``` - 或者在配置中设置默认值： + 或在配置中设置默认值： ```json5 { @@ -130,22 +127,27 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 -## 云端模型 +## 云模型 - 云端模型让你可以将云端托管模型与本地模型一起使用。示例包括 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud` —— 这些**不**需要本地执行 `ollama pull`。 + `Cloud + Local` 使用可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 推荐的混合流程。 - 在设置期间选择 **Cloud + Local** 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退到本地模型默认值。 + 在设置时使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama 基础 URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云模型默认值，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。 - 你也可以直接在 [ollama.com/signin](https://ollama.com/signin) 登录。 - - OpenClaw 当前推荐以下云端默认模型：`kimi-k2.5:cloud`、`minimax-m2.7:cloud`、`glm-5.1:cloud`。 + 如果该主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。 - - 在仅本地模式下，OpenClaw 会从本地 Ollama 实例发现模型。不需要登录云端。 + + `Cloud only` 通过 Ollama 的托管 API `https://ollama.com` 运行。 + + 在设置时使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。 + + + + + 在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例中发现模型。此路径适用于本地或自托管的 Ollama 服务器。 OpenClaw 当前推荐 `gemma4` 作为本地默认模型。 @@ -154,26 +156,26 @@ Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上 ## 模型发现（隐式 provider） -当你设置了 `OLLAMA_API_KEY`（或认证配置），并且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从 `http://127.0.0.1:11434` 上的本地 Ollama 实例发现模型。 +当你设置了 `OLLAMA_API_KEY`（或身份验证配置）且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例中发现模型。 -| 行为 | 详情 | +| 行为 | 详细信息 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 目录查询 | 查询 `/api/tags` | | 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow` 并检测能力（包括视觉） | -| 视觉模型 | 对于 `/api/show` 报告具有 `vision` 能力的模型，会将其标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入到提示中 | +| 视觉模型 | 由 `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像输入（`input: ["text", "image"]`），因此 OpenClaw 会自动将图片注入到提示中 | | 推理检测 | 使用模型名称启发式规则（`r1`、`reasoning`、`think`）标记 `reasoning` | -| token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 | -| 成本 | 将所有成本设置为 `0` | +| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 | +| 费用 | 将所有费用设置为 `0` | -这样可以避免手动填写模型条目，同时使目录与本地 Ollama 实例保持一致。 +这样可以避免手动录入模型，同时让目录与本地 Ollama 实例保持一致。 ```bash -# 查看有哪些可用模型 +# 查看有哪些模型可用 ollama list openclaw models list ``` -要添加新模型，只需通过 Ollama 拉取它： +要添加新模型，只需使用 Ollama 拉取它： ```bash ollama pull mistral @@ -182,45 +184,45 @@ ollama pull mistral 新模型会被自动发现并可立即使用。 -如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。请参阅下方的显式配置部分。 +如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。参见下面的显式配置部分。 ## 配置 - 启用 Ollama 的最简单方式是使用环境变量： + 最简单的仅本地启用方式是通过环境变量： ```bash export OLLAMA_API_KEY="ollama-local" ``` - 如果已设置 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会自动填充它以进行可用性检查。 + 如果设置了 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动补齐它。 - 当 Ollama 运行在其他主机或端口上、你希望强制指定特定上下文窗口或模型列表，或者你希望完全手动定义模型时，请使用显式配置。 + 当你想使用托管云端设置、Ollama 运行在其他主机/端口、你想强制指定特定上下文窗口或模型列表，或你希望完全手动定义模型时，请使用显式配置。 ```json5 { models: { providers: { ollama: { - baseUrl: "http://ollama-host:11434", - apiKey: "ollama-local", + baseUrl: "https://ollama.com", + apiKey: "OLLAMA_API_KEY", api: "ollama", models: [ { - id: "gpt-oss:20b", - name: "GPT-OSS 20B", + id: "kimi-k2.5:cloud", + name: "kimi-k2.5:cloud", reasoning: false, - input: ["text"], + input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, - contextWindow: 8192, - maxTokens: 8192 * 10 + contextWindow: 128000, + maxTokens: 8192 } ] } @@ -231,7 +233,7 @@ ollama pull mistral - + 如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）： ```json5 @@ -240,7 +242,7 @@ ollama pull mistral providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // 不要带 /v1 - 使用原生 Ollama API URL + baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL api: "ollama", // 显式设置以确保使用原生工具调用行为 }, }, @@ -249,7 +251,7 @@ ollama pull mistral ``` - 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 + 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，而该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 @@ -257,7 +259,7 @@ ollama pull mistral ### 模型选择 -配置完成后，你的所有 Ollama 模型都可用： +完成配置后，你的所有 Ollama 模型都可用： ```json5 { @@ -274,15 +276,15 @@ ollama pull mistral ## Ollama Web 搜索 -OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供商提供。 +OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider 使用。 -| 属性 | 详情 | +| 属性 | 详细信息 | | ----------- | ----------------------------------------------------------------------------------------------------------------- | -| 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用其值，否则为 `http://127.0.0.1:11434`） | +| 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用该值，否则为 `http://127.0.0.1:11434`） | | 认证 | 无需密钥 | | 要求 | Ollama 必须正在运行，并且已通过 `ollama signin` 登录 | -在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或者设置： +在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 **Ollama Web 搜索**，或设置： ```json5 { @@ -297,7 +299,7 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 ``` -有关完整设置和行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 +完整的设置和行为细节，请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 ## 高级配置 @@ -305,10 +307,10 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 - **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才使用此模式。 + **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要通过代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才应使用此模式。 - 如果你需要改用 OpenAI 兼容端点（例如在仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`： + 如果你需要改用 OpenAI 兼容端点（例如位于仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`： ```json5 { @@ -326,9 +328,9 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 } ``` - 此模式可能不支持同时进行流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。 + 在此模式下，可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。 - 当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会悄悄回退到 4096 的上下文窗口。如果你的代理或上游拒绝未知的 `options` 字段，请禁用此行为： + 当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，以避免 Ollama 静默回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为： ```json5 { @@ -349,7 +351,7 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 - 对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 + 对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口；否则，会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`： @@ -374,32 +376,29 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 - 默认情况下，OpenClaw 会将名称包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。 + OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。 ```bash ollama pull deepseek-r1:32b ``` - 不需要额外配置——OpenClaw 会自动标记它们。 + 无需额外配置——OpenClaw 会自动标记它们。 - - Ollama 可免费使用并在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。 + + Ollama 可免费使用并在本地运行，因此所有模型费用都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。 - - 内置的 Ollama 插件为 - [记忆搜索](/zh-CN/concepts/memory) - 注册了一个记忆嵌入提供商。它使用已配置的 Ollama base URL - 和 API 密钥。 + + 内置的 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个 memory embedding provider。它使用已配置的 Ollama 基础 URL 和 API 密钥。 | 属性 | 值 | | ------------- | ------------------- | | 默认模型 | `nomic-embed-text` | - | 自动拉取 | 是——如果嵌入模型尚未在本地存在，将自动拉取 | + | 自动拉取 | 是——如果 embedding 模型在本地不存在，则会自动拉取 | - 要将 Ollama 选为记忆搜索的嵌入提供商： + 要将 Ollama 选为 memory search 的 embedding provider： ```json5 { @@ -414,10 +413,10 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 - OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。不需要特殊配置。 + OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。无需任何特殊配置。 - 如果你需要使用 OpenAI 兼容端点，请参阅上方“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 + 如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 @@ -427,13 +426,13 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 - 请确认 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或认证配置），且你**没有**定义显式的 `models.providers.ollama` 条目： + 请确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或身份验证配置），同时**没有**定义显式的 `models.providers.ollama` 条目： ```bash ollama serve ``` - 验证 API 是否可访问： + 验证 API 可访问： ```bash curl http://localhost:11434/api/tags @@ -442,7 +441,7 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 - 如果你的模型未列出，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。 + 如果列表中没有你的模型，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。 ```bash ollama list # 查看已安装的模型 @@ -481,9 +480,9 @@ OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供 如何选择和配置模型。 - 由 Ollama 提供支持的 Web 搜索的完整设置和行为细节。 + 了解 Ollama 驱动的网页搜索的完整设置和行为细节。 - 完整配置参考。 + 完整的配置参考。 diff --git a/docs/zh-CN/reference/wizard.md b/docs/zh-CN/reference/wizard.md index 23246f52f..dd33ec38c 100644 --- a/docs/zh-CN/reference/wizard.md +++ b/docs/zh-CN/reference/wizard.md @@ -7,10 +7,10 @@ sidebarTitle: Onboarding Reference summary: CLI 新手引导的完整参考：每一步、每个标志和每个配置字段 title: 新手引导参考 x-i18n: - generated_at: "2026-04-06T15:31:48Z" + generated_at: "2026-04-15T13:38:05Z" model: gpt-5.4 provider: openai - source_hash: a142b9ec4323fabb9982d05b64375d2b4a4007dffc910acbee3a38ff871a7236 + source_hash: 1db3ff789422617634e6624f9d12c18b6a6c573721226b9c0fa6f6b7956ef33d source_path: reference/wizard.md workflow: 15 --- @@ -18,133 +18,133 @@ x-i18n: # 新手引导参考 这是 `openclaw onboard` 的完整参考。 -如需高层概览，请参见 [新手引导（CLI）](/zh-CN/start/wizard)。 +如需高层概览，请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。 -## 流程详情（本地模式） +## 流程细节（本地模式） - - 如果 `~/.openclaw/openclaw.json` 存在，可选择 **保留 / 修改 / 重置**。 + - 如果 `~/.openclaw/openclaw.json` 已存在，选择 **保留 / 修改 / 重置**。 - 重新运行新手引导**不会**清除任何内容，除非你明确选择 **重置** （或传入 `--reset`）。 - - CLI `--reset` 默认范围是 `config+creds+sessions`；使用 `--reset-scope full` - 还会删除工作区。 + - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` + 还会移除工作区。 - 如果配置无效或包含旧版键名，向导会停止并要求 - 你先运行 `openclaw doctor` 再继续。 + 你先运行 `openclaw doctor`，然后再继续。 - 重置使用 `trash`（绝不使用 `rm`），并提供以下范围： - 仅配置 - 配置 + 凭证 + 会话 - - 完全重置（也会删除工作区） + - 完全重置（还会移除工作区） - - **Anthropic API 密钥**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入密钥，然后保存以供守护进程使用。 - - **Anthropic API 密钥**：在新手引导/配置中是 Anthropic 助手的首选选项。 - - **Anthropic setup-token**：在新手引导/配置中仍然可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。 - - **OpenAI Code（Codex）订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，新手引导可以复用它。被复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw 会先重新读取该来源，并在提供商能够刷新时，将刷新后的凭证写回 Codex 存储，而不是自行接管。 + - **Anthropic API 密钥**：如果存在 `ANTHROPIC_API_KEY` 就使用它，否则提示输入密钥，然后保存以供守护进程使用。 + - **Anthropic API 密钥**：是新手引导/配置中首选的 Anthropic 助手选项。 + - **Anthropic setup-token**：在新手引导/配置中仍可用，不过当可用时，OpenClaw 现在更倾向于复用 Claude CLI。 + - **OpenAI Code（Codex）订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，新手引导可以复用它。被复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw 会先重新读取该来源，并且当提供商可以刷新它时，会把刷新的凭证写回 Codex 存储，而不是自行接管。 - **OpenAI Code（Codex）订阅（OAuth）**：浏览器流程；粘贴 `code#state`。 - - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。 - - **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入密钥，然后将其存储到凭证配置文件中。 - - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。 - - **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY` 并将 xAI 配置为模型提供商。 + - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设为 `openai-codex/gpt-5.4`。 + - **OpenAI API 密钥**：如果存在 `OPENAI_API_KEY` 就使用它，否则提示输入密钥，然后将其存储到凭证配置中。 + - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设为 `openai/gpt-5.4`。 + - **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。 - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。 - - **Ollama**：提示输入 Ollama base URL，提供 **Cloud + Local** 或 **Local** 模式，发现可用模型，并在需要时自动拉取所选本地模型。 - - 更多细节：[Ollama](/zh-CN/providers/ollama) - - **API 密钥**：为你存储该密钥。 + - **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；依赖主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云端。 + - 更多详情：[Ollama](/zh-CN/providers/ollama) + - **API 密钥**：会为你存储该密钥。 - **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。 - - 更多细节：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) + - 更多详情：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**：提示输入 Account ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 - - 更多细节：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) - - **MiniMax**：会自动写入配置；托管默认模型是 `MiniMax-M2.7`。 - API 密钥设置使用 `minimax/...`，而 OAuth 设置使用 + - 更多详情：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) + - **MiniMax**：会自动写入配置；托管默认值是 `MiniMax-M2.7`。 + API 密钥设置使用 `minimax/...`，OAuth 设置使用 `minimax-portal/...`。 - - 更多细节：[MiniMax](/zh-CN/providers/minimax) - - **StepFun**：会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。 - - 标准版当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。 - - 更多细节：[StepFun](/zh-CN/providers/stepfun) - - **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。 - - 更多细节：[Synthetic](/zh-CN/providers/synthetic) + - 更多详情：[MiniMax](/zh-CN/providers/minimax) + - **StepFun**：会为中国区或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。 + - Standard 当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。 + - 更多详情：[StepFun](/zh-CN/providers/stepfun) + - **Synthetic（兼容 Anthropic）**：提示输入 `SYNTHETIC_API_KEY`。 + - 更多详情：[Synthetic](/zh-CN/providers/synthetic) - **Moonshot（Kimi K2）**：会自动写入配置。 - **Kimi Coding**：会自动写入配置。 - - 更多细节：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot) + - 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot) - **跳过**：暂不配置凭证。 - - 从检测到的选项中选择一个默认模型（或手动输入 provider/model）。为了获得最佳质量并降低提示注入风险，请选择你提供商栈中可用的最强最新一代模型。 - - 新手引导会执行模型检查，并在配置的模型未知或缺少凭证时发出警告。 - - API 密钥存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。 - - 凭证配置文件位于 `~/.openclaw/agents//agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。 - - 更多细节：[/concepts/oauth](/zh-CN/concepts/oauth) + - 从检测到的选项中选择默认模型（或手动输入 provider/model）。为了获得最佳质量并降低提示注入风险，请选择你当前提供商栈中可用的最强最新一代模型。 + - 新手引导会运行模型检查，并在配置的模型未知或缺少凭证时发出警告。 + - API 密钥存储模式默认使用明文凭证配置值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。 + - 凭证配置位于 `~/.openclaw/agents//agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。 + - 更多详情：[/concepts/oauth](/zh-CN/concepts/oauth) - 无头/服务器提示：可先在有浏览器的机器上完成 OAuth，然后复制 + 无头/服务器提示：先在有浏览器的机器上完成 OAuth，然后复制 该智能体的 `auth-profiles.json`（例如 `~/.openclaw/agents//agent/auth-profiles.json`，或对应的 - `$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机上。`credentials/oauth.json` - 只是旧版导入来源。 + `$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json` + 仅是旧版导入来源。 - 默认是 `~/.openclaw/workspace`（可配置）。 - - 会初始化智能体 bootstrap ritual 所需的工作区文件。 - - 完整工作区布局和备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace) + - 初始化智能体引导仪式所需的工作区文件。 + - 完整工作区布局 + 备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace) - - 端口、绑定、凭证模式、Tailscale 暴露。 - - 凭证建议：即使是 loopback，也请保留 **Token**，这样本地 WS 客户端仍必须进行身份验证。 + - 端口、绑定、认证模式、Tailscale 暴露。 + - 认证建议：即使是 loopback，也请保持 **Token**，这样本地 WS 客户端也必须认证。 - 在 token 模式下，交互式设置提供： - **生成/存储明文 token**（默认） - **使用 SecretRef**（可选启用） - - 快速开始会在新手引导探测/仪表板 bootstrap 过程中复用现有的 `gateway.auth.token` SecretRef，支持 `env`、`file` 和 `exec` 提供商。 - - 如果已配置该 SecretRef 但无法解析，新手引导会尽早失败并给出清晰的修复信息，而不是静默降级运行时凭证。 + - 快速开始会复用现有的 `gateway.auth.token` SecretRef，包括 `env`、`file` 和 `exec` 提供商，用于新手引导探测/仪表板引导。 + - 如果已配置该 SecretRef 但无法解析，新手引导会尽早失败并给出明确修复信息，而不是静默降低运行时认证。 - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。 - 非交互 token SecretRef 路径：`--gateway-token-ref-env `。 - - 要求新手引导进程环境中存在非空环境变量。 - - 不能与 `--gateway-token` 一起使用。 - - 仅当你完全信任所有本地进程时才禁用凭证。 - - 非 loopback 绑定仍然需要凭证。 + - 要求新手引导进程环境中存在一个非空环境变量。 + - 不能与 `--gateway-token` 组合使用。 + - 仅当你完全信任每一个本地进程时才禁用认证。 + - 非 loopback 绑定仍然需要认证。 - [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录。 - - [Telegram](/zh-CN/channels/telegram)：机器人令牌。 - - [Discord](/zh-CN/channels/discord)：机器人令牌。 + - [Telegram](/zh-CN/channels/telegram)：机器人 token。 + - [Discord](/zh-CN/channels/discord)：机器人 token。 - [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience。 - - [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人令牌 + base URL。 - - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账户配置。 + - [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人 token + 基础 URL。 + - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账号配置。 - [BlueBubbles](/zh-CN/channels/bluebubbles)：**推荐用于 iMessage**；服务器 URL + 密码 + webhook。 - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问。 - - 私信安全：默认启用配对。首次私信会发送一个代码；通过 `openclaw pairing approve ` 批准，或使用允许列表。 + - 私信安全：默认采用配对。首次私信会发送一个代码；通过 `openclaw pairing approve ` 批准，或使用允许列表。 - - 选择一个受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（也可以跳过）。 - - 基于 API 的提供商可以使用环境变量或现有配置快速设置；无需密钥的提供商则使用其各自的前置条件。 + - 选择一个受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。 + - 基于 API 的提供商可使用环境变量或现有配置进行快速设置；无密钥提供商则使用各自提供商特定的前置条件。 - 使用 `--skip-search` 跳过。 - - 稍后配置：`openclaw configure --section web`。 + - 之后再配置：`openclaw configure --section web`。 - + - macOS：LaunchAgent - - 需要已登录的用户会话；对于无头场景，请使用自定义 LaunchDaemon（未内置）。 + - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未内置提供）。 - Linux（以及通过 WSL2 的 Windows）：systemd 用户单元 - - 新手引导会尝试通过 `loginctl enable-linger ` 启用 lingering，这样 Gateway 网关在登出后仍能保持运行。 - - 可能会提示 sudo（会写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。 + - 新手引导会尝试启用 lingering：`loginctl enable-linger `，以便 Gateway 网关在注销后继续运行。 + - 可能会提示 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。 - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。 - - 如果 token 凭证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会把解析后的明文 token 值持久化到 supervisor 服务环境元数据中。 - - 如果 token 凭证需要 token 且配置的 token SecretRef 未解析，守护进程安装会被阻止，并给出可操作的指导。 - - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，则会阻止守护进程安装，直到明确设置 mode。 + - 如果 token 认证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到 supervisor 服务环境元数据中。 + - 如果 token 认证需要 token 且已配置的 token SecretRef 无法解析，守护进程安装会被阻止，并给出可执行的指引。 + - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，则守护进程安装会被阻止，直到显式设置 mode。 - - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。 - - 提示：`openclaw status --deep` 会将 live Gateway 网关健康探测添加到状态输出中，在支持时也包括渠道探测（需要能访问到 Gateway 网关）。 + - 启动 Gateway 网关（如有需要），然后运行 `openclaw health`。 + - 提示：`openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测（需要 Gateway 网关可达）。 - 读取可用的 Skills 并检查要求。 - 让你选择一个 node 管理器：**npm / pnpm**（不推荐 bun）。 - - 安装可选依赖（有些会在 macOS 上使用 Homebrew）。 + - 安装可选依赖（其中一些在 macOS 上使用 Homebrew）。 - - 显示摘要和后续步骤，包括 iOS/Android/macOS 应用以启用更多功能。 + - 摘要 + 后续步骤，包括 iOS/Android/macOS 应用以获得额外功能。 如果未检测到 GUI，新手引导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 -如果缺少 Control UI 资源，新手引导会尝试构建它们；回退命令是 `pnpm ui:build`（会自动安装 UI 依赖）。 +如果缺少 Control UI 资源，新手引导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。 ## 非交互模式 @@ -199,36 +199,36 @@ openclaw agents add work \ ## Gateway 网关向导 RPC Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。 -客户端（macOS 应用、Control UI）可以渲染步骤，而无需重新实现新手引导逻辑。 +客户端（macOS 应用、Control UI）可以渲染各步骤，而无需重新实现新手引导逻辑。 ## Signal 设置（signal-cli） 新手引导可以从 GitHub releases 安装 `signal-cli`： -- 下载合适的发布资源。 -- 将其存储到 `~/.openclaw/tools/signal-cli//`。 +- 下载适当的发布资源。 +- 将其存储在 `~/.openclaw/tools/signal-cli//` 下。 - 将 `channels.signal.cliPath` 写入你的配置。 -说明： +注意： - JVM 构建需要 **Java 21**。 -- 在可用时会使用原生构建。 -- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内遵循 Linux 流程。 +- 若可用，则使用原生构建。 +- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内按照 Linux 流程进行。 -## 向导会写入什么 +## 向导会写入什么内容 `~/.openclaw/openclaw.json` 中的典型字段： - `agents.defaults.workspace` -- `agents.defaults.model` / `models.providers`（如果选择了 Minimax） +- `agents.defaults.model` / `models.providers`（如果选择了 MiniMax） - `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留） - `gateway.*`（mode、bind、auth、tailscale） - `session.dmScope`（行为细节：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)） - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*` -- 当你在提示中选择启用时，会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（在可能时会将名称解析为 ID）。 +- 当你在提示中选择启用时，会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（名称会在可能时解析为 ID）。 - `skills.install.nodeManager` - `setup --node-manager` 接受 `npm`、`pnpm` 或 `bun`。 - - 手动配置仍可通过直接设置 `skills.install.nodeManager` 使用 `yarn`。 + - 手动配置仍可通过直接设置 `skills.install.nodeManager` 来使用 `yarn`。 - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -237,15 +237,15 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex `openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。 -WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//`。 +WhatsApp 凭证存放在 `~/.openclaw/credentials/whatsapp//` 下。 会话存储在 `~/.openclaw/agents//sessions/` 下。 -某些渠道以插件形式交付。当你在设置期间选择其中一个时，新手引导 +某些渠道以插件形式提供。当你在设置过程中选择其中一个时，新手引导 会先提示安装它（npm 或本地路径），然后才能进行配置。 ## 相关文档 -- 新手引导概览：[新手引导（CLI）](/zh-CN/start/wizard) +- 新手引导概览：[设置向导（CLI）](/zh-CN/start/wizard) - macOS 应用新手引导：[新手引导](/zh-CN/start/onboarding) - 配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration) - 提供商：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)、[Google Chat](/zh-CN/channels/googlechat)、[Signal](/zh-CN/channels/signal)、[BlueBubbles](/zh-CN/channels/bluebubbles)（iMessage）、[iMessage](/zh-CN/channels/imessage)（旧版） diff --git a/docs/zh-CN/start/wizard-cli-reference.md b/docs/zh-CN/start/wizard-cli-reference.md index 7564d2916..6c664fbf1 100644 --- a/docs/zh-CN/start/wizard-cli-reference.md +++ b/docs/zh-CN/start/wizard-cli-reference.md @@ -1,15 +1,15 @@ --- read_when: - - 你需要了解 `openclaw onboard` 的详细行为 + - 你需要 `openclaw onboard` 的详细行为说明 - 你正在调试新手引导结果或集成新手引导客户端 sidebarTitle: CLI reference -summary: '`CLI 设置参考` 的完整参考，包括 CLI 设置流程、认证/模型设置、输出和内部机制' +summary: CLI 设置流程、凭证/模型设置、输出和内部机制的完整参考 title: CLI 设置参考 x-i18n: - generated_at: "2026-04-05T17:49:57Z" + generated_at: "2026-04-15T13:39:08Z" model: gpt-5.4 provider: openai - source_hash: 92f379b34a2b48c68335dae4f759117c770f018ec51b275f4f40421c6b3abb23 + source_hash: 61ca679caca3b43fa02388294007f89db22d343e49e10b61d8d118cd8fbb7369 source_path: start/wizard-cli-reference.md workflow: 15 --- @@ -17,21 +17,21 @@ x-i18n: # CLI 设置参考 本页是 `openclaw onboard` 的完整参考。 -如需简短指南，请参见 [新手引导（CLI）](/zh-CN/start/wizard)。 +如需简短指南，请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。 -## 向导会做什么 +## 向导的作用 -本地模式（默认）会引导你完成以下设置： +本地模式（默认）会引导你完成： -- 模型和认证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot AI、StepFun 和 AI Gateway 网关选项） +- 模型和凭证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 选项） - 工作区位置和引导文件 -- Gateway 网关设置（端口、绑定、认证、tailscale） +- Gateway 网关设置（端口、绑定、认证、Tailscale） - 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles，以及其他内置渠道插件） -- 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows 计划任务，并在失败时回退到启动文件夹） +- 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows Scheduled Task，并在失败时回退到 Startup 文件夹） - 健康检查 - Skills 设置 -远程模式会将这台机器配置为连接到其他地方的一个 Gateway 网关。 +远程模式会将此机器配置为连接到其他地方的 Gateway 网关。 它不会在远程主机上安装或修改任何内容。 ## 本地流程详情 @@ -40,32 +40,32 @@ x-i18n: - 如果 `~/.openclaw/openclaw.json` 已存在，可选择保留、修改或重置。 - 重新运行向导不会清除任何内容，除非你明确选择“重置”（或传入 `--reset`）。 - - CLI `--reset` 默认为 `config+creds+sessions`；使用 `--reset-scope full` 可同时移除工作区。 - - 如果配置无效或包含旧版键，向导会停止并要求你先运行 `openclaw doctor`，然后再继续。 + - CLI `--reset` 默认是 `config+creds+sessions`；使用 `--reset-scope full` 还会移除工作区。 + - 如果配置无效或包含旧版键名，向导会停止并要求你先运行 `openclaw doctor` 再继续。 - 重置使用 `trash`，并提供以下范围： - 仅配置 - 配置 + 凭证 + 会话 - - 完整重置（也会移除工作区） + - 完全重置（还会移除工作区） - - - 完整选项矩阵见 [认证和模型选项](#auth-and-model-options)。 + + - 完整选项矩阵见 [凭证和模型选项](#auth-and-model-options)。 - - 默认是 `~/.openclaw/workspace`（可配置）。 - - 写入首次运行引导所需的工作区文件。 - - 工作区布局：[智能体工作区](/zh-CN/concepts/agent-workspace)。 + - 默认 `~/.openclaw/workspace`（可配置）。 + - 生成首次运行引导流程所需的工作区文件。 + - 工作区布局： [智能体工作区](/zh-CN/concepts/agent-workspace)。 - - 会提示输入端口、绑定、认证模式和 tailscale 暴露方式。 - - 推荐：即使是 loopback，也保持启用令牌认证，这样本地 WS 客户端也必须先认证。 + - 提示设置端口、绑定、认证模式和 Tailscale 暴露方式。 + - 推荐：即使只绑定到 loopback，也保持启用令牌认证，这样本地 WS 客户端仍必须进行认证。 - 在令牌模式下，交互式设置提供： - **生成/存储明文令牌**（默认） - - **使用 SecretRef**（按需启用） - - 在密码模式下，交互式设置同样支持明文或 SecretRef 存储。 + - **使用 SecretRef**（可选） + - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。 - 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env `。 - 要求新手引导进程环境中存在一个非空环境变量。 - - 不能与 `--gateway-token` 组合使用。 - - 仅当你完全信任每一个本地进程时，才禁用认证。 + - 不能与 `--gateway-token` 同时使用。 + - 仅当你完全信任每个本地进程时才禁用认证。 - 非 loopback 绑定仍然需要认证。 @@ -75,30 +75,30 @@ x-i18n: - [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience - [Mattermost](/zh-CN/channels/mattermost)：机器人令牌 + 基础 URL - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账号配置 - - [BlueBubbles](/zh-CN/channels/bluebubbles)：推荐用于 iMessage；需要服务器 URL + 密码 + webhook + - [BlueBubbles](/zh-CN/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问 - - 私信安全：默认使用配对。第一次私信会发送一个代码；通过 - `openclaw pairing approve ` 进行批准，或使用允许名单。 + - 私信安全：默认使用配对。首次私信会发送一个代码；通过 + `openclaw pairing approve ` 批准，或使用 allowlist。 - macOS：LaunchAgent - - 需要已登录的用户会话；如需无头模式，请使用自定义 LaunchDaemon（未随产品提供）。 + - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。 - Linux 和通过 WSL2 的 Windows：systemd 用户单元 - - 向导会尝试运行 `loginctl enable-linger `，以便 Gateway 网关在注销后继续运行。 - - 可能会提示 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。 - - 原生 Windows：优先使用计划任务 - - 如果创建任务被拒绝，OpenClaw 会回退到每用户启动文件夹登录项，并立即启动 Gateway 网关。 - - 仍然更推荐计划任务，因为它们提供更好的 supervisor 状态。 + - 向导会尝试执行 `loginctl enable-linger `，使 Gateway 网关在注销后仍保持运行。 + - 可能会提示 sudo（写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。 + - 原生 Windows：优先使用 Scheduled Task + - 如果任务创建被拒绝，OpenClaw 会回退到按用户设置的 Startup 文件夹登录项，并立即启动 Gateway 网关。 + - 仍然优先推荐 Scheduled Task，因为它们提供更好的监督状态。 - 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不推荐 Bun。 - - 启动 Gateway 网关（如需要）并运行 `openclaw health`。 - - `openclaw status --deep` 会把实时 Gateway 网关健康探针加入状态输出，包括支持时的渠道探针。 + - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。 + - `openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测。 - 读取可用 Skills 并检查要求。 - 让你选择 Node 管理器：npm、pnpm 或 bun。 - - 安装可选依赖（有些在 macOS 上使用 Homebrew）。 + - 安装可选依赖（其中一些在 macOS 上使用 Homebrew）。 - 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。 @@ -106,42 +106,41 @@ x-i18n: -如果未检测到 GUI，向导会打印用于访问 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 -如果缺少 Control UI 资源，向导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。 +如果未检测到 GUI，向导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 +如果缺少 Control UI 资源，向导会尝试构建它们；回退命令是 `pnpm ui:build`（会自动安装 UI 依赖）。 ## 远程模式详情 -远程模式会将这台机器配置为连接到其他地方的一个 Gateway 网关。 +远程模式会将此机器配置为连接到其他地方的 Gateway 网关。 远程模式不会在远程主机上安装或修改任何内容。 -你要设置的内容： +你需要设置： - 远程 Gateway 网关 URL（`ws://...`） -- 如果远程 Gateway 网关要求认证，则设置令牌（推荐） +- 如果远程 Gateway 网关需要认证，则设置令牌（推荐） -- 如果 Gateway 网关仅绑定 loopback，请使用 SSH 隧道或 tailnet。 -- 发现提示： +- 如果 Gateway 网关仅限 loopback，请使用 SSH 隧道或 tailnet。 +- 设备发现提示： - macOS：Bonjour（`dns-sd`） - Linux：Avahi（`avahi-browse`） -## 认证和模型选项 +## 凭证和模型选项 - 如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后保存以供守护进程使用。 + 如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示你输入密钥，然后将其保存供守护进程使用。 - 如果存在 `~/.codex/auth.json`，向导可以复用它。 + 如果 `~/.codex/auth.json` 存在，向导可以复用它。 复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw - 会优先重新读取该来源，并且当提供商可以刷新它时，会将 - 刷新后的凭证写回 Codex 存储，而不是自行接管 - 该凭证。 + 会先重新读取该来源，并且在提供商支持刷新的情况下，将 + 刷新后的凭证写回 Codex 存储，而不是自行接管其管理。 浏览器流程；粘贴 `code#state`。 @@ -150,13 +149,13 @@ x-i18n: - 如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将凭证存储到认证 profiles 中。 + 如果存在 `OPENAI_API_KEY` 则使用它，否则提示你输入密钥，然后将凭证存储到凭证配置文件中。 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。 - 提示输入 `XAI_API_KEY`，并将 xAI 配置为一个模型提供商。 + 提示输入 `XAI_API_KEY` 并将 xAI 配置为模型提供商。 提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并让你选择 Zen 或 Go 目录。 @@ -165,43 +164,45 @@ x-i18n: 为你存储该密钥。 - + 提示输入 `AI_GATEWAY_API_KEY`。 - 更多详情：[Vercel AI Gateway 网关](/zh-CN/providers/vercel-ai-gateway)。 + 更多细节： [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。 - + 提示输入账号 ID、Gateway 网关 ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 - 更多详情：[Cloudflare AI Gateway 网关](/zh-CN/providers/cloudflare-ai-gateway)。 + 更多细节： [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。 - 配置会自动写入。托管默认值为 `MiniMax-M2.7`；API 密钥设置使用 + 配置会自动写入。托管默认值是 `MiniMax-M2.7`；API 密钥设置使用 `minimax/...`，OAuth 设置使用 `minimax-portal/...`。 - 更多详情：[MiniMax](/zh-CN/providers/minimax)。 + 更多细节： [MiniMax](/zh-CN/providers/minimax)。 - 会为中国区或全球端点的 StepFun 标准版或 Step Plan 自动写入配置。 - 标准版当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。 - 更多详情：[StepFun](/zh-CN/providers/stepfun)。 + 会为中国区或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。 + Standard 当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。 + 更多细节： [StepFun](/zh-CN/providers/stepfun)。 提示输入 `SYNTHETIC_API_KEY`。 - 更多详情：[Synthetic](/zh-CN/providers/synthetic)。 + 更多细节： [Synthetic](/zh-CN/providers/synthetic)。 - - 提示输入基础 URL（默认 `http://127.0.0.1:11434`），然后提供 Cloud + Local 或仅 Local 模式。 - 发现可用模型并建议默认值。 - 更多详情：[Ollama](/zh-CN/providers/ollama)。 + + 首先提示你选择 `Cloud + Local`、`Cloud only` 或 `Local only`。 + `Cloud only` 使用 `OLLAMA_API_KEY` 和 `https://ollama.com`。 + 基于主机的模式会提示输入基础 URL（默认 `http://127.0.0.1:11434`）、发现可用模型并建议默认值。 + `Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云端。 + 更多细节： [Ollama](/zh-CN/providers/ollama)。 - - Moonshot AI（Kimi K2）和 Kimi Coding 配置会自动写入。 - 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。 + + Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。 + 更多细节： [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。 - 可用于兼容 OpenAI 和兼容 Anthropic 的端点。 + 适用于兼容 OpenAI 和兼容 Anthropic 的端点。 交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项： - **立即粘贴 API 密钥**（明文） - - **使用 secret reference**（环境变量引用或已配置提供商引用，带预检验证） + - **使用 secret reference**（环境变量引用或已配置的提供商引用，并带有预检校验） 非交互式参数： - `--auth-choice custom-api-key` @@ -213,53 +214,53 @@ x-i18n: - 保持认证未配置状态。 + 保持凭证未配置状态。 模型行为： - 从检测到的选项中选择默认模型，或手动输入提供商和模型。 -- 当新手引导从某个提供商认证选项开始时，模型选择器会自动优先显示 - 该提供商。对于 Volcengine 和 BytePlus（国际版），同样的优先级 +- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先显示 + 该提供商。对于 Volcengine 和 BytePlus，这种优先级 也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、 `byteplus-plan/*`）。 -- 如果该“优先提供商”过滤结果为空，选择器会回退到 - 完整目录，而不是显示空模型列表。 -- 向导会运行模型检查；如果配置的模型未知或缺少认证，会给出警告。 +- 如果该首选提供商筛选结果为空，选择器会回退到 + 完整目录，而不是显示没有模型。 +- 向导会执行模型检查，并在配置的模型未知或缺少凭证时发出警告。 -凭证和 profile 路径： +凭证和配置文件路径： -- 认证 profiles（API 密钥 + OAuth）：`~/.openclaw/agents//agent/auth-profiles.json` +- 凭证配置文件（API 密钥 + OAuth）：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版 OAuth 导入：`~/.openclaw/credentials/oauth.json` 凭证存储模式： -- 默认新手引导行为会将 API 密钥作为明文值持久化到认证 profiles 中。 +- 默认的新手引导行为会将 API 密钥作为明文值持久化到凭证配置文件中。 - `--secret-input-mode ref` 会启用引用模式，而不是明文密钥存储。 - 在交互式设置中，你可以选择： + 在交互式设置中，你可以选择以下任一方式： - 环境变量引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`） - - 已配置提供商引用（`file` 或 `exec`），包含提供商别名 + id -- 交互式引用模式会在保存前运行快速预检验证。 - - Env 引用：验证变量名，以及当前新手引导环境中该变量具有非空值。 - - 提供商引用：验证提供商配置并解析请求的 id。 + - 已配置的提供商引用（`file` 或 `exec`），包含提供商别名 + id +- 交互式引用模式会在保存前执行快速预检校验。 + - 环境变量引用：校验变量名以及当前新手引导环境中的非空值。 + - 提供商引用：校验提供商配置并解析请求的 id。 - 如果预检失败，新手引导会显示错误并允许你重试。 -- 在非交互模式下，`--secret-input-mode ref` 仅支持基于环境变量。 +- 在非交互式模式下，`--secret-input-mode ref` 仅支持基于环境变量。 - 在新手引导进程环境中设置提供商环境变量。 - - 内联密钥参数（例如 `--openai-api-key`）要求该环境变量已设置；否则新手引导会快速失败。 - - 对于自定义提供商，非交互 `ref` 模式会将 `models.providers..apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 - - 在该自定义提供商场景下，`--custom-api-key` 要求设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。 + - 内联密钥参数（例如 `--openai-api-key`）要求必须设置该环境变量；否则新手引导会快速失败。 + - 对于自定义提供商，非交互式 `ref` 模式会将 `models.providers..apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 + - 在该自定义提供商场景中，`--custom-api-key` 要求必须设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。 - Gateway 网关认证凭证在交互式设置中支持明文和 SecretRef 选项： - 令牌模式：**生成/存储明文令牌**（默认）或 **使用 SecretRef**。 - 密码模式：明文或 SecretRef。 - 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env `。 -- 现有的明文设置将继续照常工作。 +- 现有的明文设置将继续保持不变并正常工作。 -无头环境和服务器提示：可先在有浏览器的机器上完成 OAuth，然后复制 +无头环境和服务器提示：在有浏览器的机器上完成 OAuth，然后复制 该智能体的 `auth-profiles.json`（例如 `~/.openclaw/agents//agent/auth-profiles.json`，或对应的 -`$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机上。`credentials/oauth.json` +`$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json` 仅是旧版导入来源。 @@ -268,15 +269,15 @@ x-i18n: `~/.openclaw/openclaw.json` 中的典型字段： - `agents.defaults.workspace` -- `agents.defaults.model` / `models.providers`（如果选择了 Minimax） -- `tools.profile`（本地新手引导在未设置时默认设为 `"coding"`；现有显式值会被保留） -- `gateway.*`（mode、bind、auth、tailscale） -- `session.dmScope`（本地新手引导在未设置时默认设为 `per-channel-peer`；现有显式值会被保留） +- `agents.defaults.model` / `models.providers`（如果选择了 MiniMax） +- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留） +- `gateway.*`（模式、绑定、认证、Tailscale） +- `session.dmScope`（本地新手引导在未设置时默认将其设为 `per-channel-peer`；现有的显式值会被保留） - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*` -- 当你在提示中选择启用时，渠道允许名单（Slack、Discord、Matrix、Microsoft Teams）（如有可能，名称会解析为 ID） +- 当你在提示中选择启用时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（名称会在可能时解析为 ID） - `skills.install.nodeManager` - `setup --node-manager` 参数接受 `npm`、`pnpm` 或 `bun`。 - - 稍后手动配置时仍可将 `skills.install.nodeManager: "yarn"` 设为 `"yarn"`。 + - 后续手动配置仍可将 `skills.install.nodeManager: "yarn"` 设为 `"yarn"`。 - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -285,12 +286,11 @@ x-i18n: `openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。 -WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//` 下。 +WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//`。 会话存储在 `~/.openclaw/agents//sessions/` 下。 -某些渠道以插件形式提供。在设置过程中选中它们时，向导会 -先提示安装插件（npm 或本地路径），再进行渠道配置。 +某些渠道以插件形式提供。在设置期间选择这些渠道时，向导会先提示你安装该插件（npm 或本地路径），然后再进行渠道配置。 Gateway 网关向导 RPC： @@ -300,16 +300,16 @@ Gateway 网关向导 RPC： - `wizard.cancel` - `wizard.status` -客户端（macOS 应用和 Control UI）可以渲染步骤，而无需重新实现新手引导逻辑。 +客户端（macOS 应用和 Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。 Signal 设置行为： -- 下载适合的发布资源 +- 下载对应的发布资源 - 将其存储到 `~/.openclaw/tools/signal-cli//` - 在配置中写入 `channels.signal.cliPath` - JVM 构建需要 Java 21 -- 在可用时优先使用原生构建 -- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 signal-cli 流程 +- 可用时使用原生构建 +- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 `signal-cli` 流程 ## 相关文档