跳转至

openclaw setup

OpenClaw 内置了一个系统代理——它以“OpenClaw”的身份发言——用于本地设置、修复和配置（以前称为 Crestodian）。只有当生效的默认模型完成一次真实回合后，它才会启动。 全新安装会先建立推理；配置格式错误时仍走经典 doctor 路径。

何时启动

不带子命令运行 openclaw 时，会根据配置状态进行路由：

  • 配置缺失，或存在但没有用户编写的设置（为空，或只有 $schema/meta 键）：启动带实时 AI 验证的引导式入门。
  • 配置存在但验证失败：启动经典入门流程，它会报告问题并引导你使用 openclaw doctor。
  • 配置存在且有效：打开常规代理 TUI。如果可访问的已配置 Gateway 的默认代理具有模型，则直接打开该 UI，而不经过入门或 OpenClaw。在 TUI 内使用 /openclaw，或直接运行 openclaw setup，之后可访问 OpenClaw。

运行 openclaw setup 会先对已配置的默认模型进行实时测试。通过测试的回合会启动 OpenClaw。交互式失败会打开引导式推理设置，并在候选模型通过后移交给 OpenClaw。一次性、JSON 以及其他非交互式请求在推理不可用时失败，并提示运行 openclaw onboard。openclaw --help 和 openclaw --version 保持其常规快速路径。

如果推理插件加载或所有者验证失败，错误会在应用 OpenClaw 的错误脱敏后包含根本原因。一次性文本和 JSON 输出会保留该详细信息，并与入门指导一起显示。

非交互式裸 openclaw（无 TTY）会输出一条简短消息后退出，而不是打印根帮助：在全新安装或无效安装时，它指向非交互式入门；在配置有效时，指向 openclaw agent --local ...。

openclaw onboard --modern 仍然是 OpenClaw 的兼容性别名，但使用相同的推理门控：推理可用时打开聊天，交互式失败会启动引导式推理设置，非交互式失败会带着入门指导退出。openclaw onboard --classic 打开完整的逐步向导。

OpenClaw 显示的内容

交互式 OpenClaw 会打开与 openclaw tui 相同的 TUI shell，并带有 OpenClaw 聊天后端。启动问候涵盖：

  • 配置有效性和默认代理
  • OpenClaw 正在使用的已验证模型
  • 首次启动探测得到的 Gateway 可达性
  • 下一个推荐的调试操作

它不会为了启动而转储机密或加载插件 CLI 命令。

使用 status 查看详细清单：配置路径、文档/源码路径、本地 CLI 探测、密钥/Token 存在情况、代理、模型和 Gateway 详情。

OpenClaw 使用与常规代理相同的参考发现机制：在 Git checkout 中，它指向本地 docs/ 和源码树；在 npm 安装中，它使用捆绑的文档并链接到 https://github.com/openclaw/openclaw，并指导在文档不够时查看源码。

示例

openclaw
openclaw setup
openclaw setup --json
openclaw setup --message "models"
openclaw setup --message "validate config"
openclaw setup --message "setup workspace ~/path/to/work" --yes
openclaw setup --message "set default model openai/gpt-5.6" --yes
openclaw onboard --modern

在 OpenClaw TUI 内：

status
health
doctor
validate config
setup
setup workspace ~/path/to/work
config set gateway.port 19001
config unset agents.defaults.fastModeDefault
config set-ref gateway.auth.token env OPENCLAW_GATEWAY_TOKEN
gateway status
configure gateway
open gateway wizard
restart gateway
agents
create agent work workspace ~/path/to/work
models
configure model provider
set default model openai/gpt-5.6
channels
channel info slack
connect slack
open channel wizard for slack
configure skills
configure web search
open search wizard
import memory
plugins list
plugins search slack
plugin install clawhub:openclaw-codex-app-server
talk to work agent
talk to agent for ~/path/to/work
audit
quit

操作与审批

OpenClaw 使用类型化操作，而不是临时编辑配置。

对于 config get，请为包含点或括号的记录键加引号，例如 config get channels.modelByChannel.telegram["team.ops[west]"]。 配置读取会在选择请求路径之前对敏感值进行脱敏。

只读操作会立即运行：显示概览、列出代理、列出已安装插件、搜索 ClawHub 插件、显示模型/后端状态、运行状态/健康检查、检查 Gateway 可达性、运行不带交互式修复的 doctor、验证配置、显示审计日志路径。

启动引导式设置流程也会立即运行：频道设置（connect telegram）、工作区技能设置（configure skills）、网络搜索提供商设置（configure web search）以及本地 Gateway 设置（configure gateway）。每个由配置支持的托管向导都会收集明确答案并负责相应的写入；完成时会追加审计条目并重新验证配置。需要安装插件的网络搜索提供商只会在安装成功后写入配置——安装失败或超时会停止设置并报告，而不是声称该提供商已配置。

configure gateway 会引导你完成本地 Gateway 的端口、绑定地址、Token 或密码认证，以及 Tailscale 暴露。它会保存配置，但不会将其应用到正在运行的 Gateway，因为更改活动地址或凭据可能会断开设置聊天。在聊天设置后说 restart gateway，或在终端向导交接后运行 openclaw gateway restart。远程模式仅提供指导：全新设置请使用 openclaw onboard，更改模式请使用 openclaw configure。

import memory 仅执行复制，而不是配置写入。它会检测受支持的本地代理主目录，让你选择可用来源，并将新的记忆文件复制到现有默认代理工作区，而不导入配置、凭据或技能。它要求已完成入门，并报告已确认的导入、无可导入结果、提供商失败，以及部分文件可能已被复制的失败情况。无需重启 Gateway。当需要针对另一个代理或替换现有导入时，请使用 Control UI 的 Import Memory 页面。

在 OpenClaw 直接聊天中，持久化操作需要会话审批（或使用 --yes 执行一次性命令）：写入配置、config set、config unset、config set-ref、设置/引导初始化、更改默认模型、启动/停止/重启 Gateway、创建代理以及安装插件。

由普通代理委托的变更，包括来自消息渠道的请求， 遵循请求运行生效的会话权限策略。 Full Access 会自动应用确切的拟议操作，包括当 Full Access 来自配置的默认值而非显式会话 模式时。来自消息渠道的受限运行会在发起请求的聊天中 请求审批：具有原生审批卡片的渠道会显示 Allow once 和 Deny 按钮，其他消息聊天会收到带有 /approve <id> allow-once|deny 回复的变更摘要。Webchat 和终端运行在 Control UI 或 OpenClaw 应用中决定， 它们也可以决定任何聊天的审批。 在委托聊天中回复 "yes" 无法授权变更；按钮或 /approve 命令可以。 具有自身审批人设置的渠道决定谁可以审批；其他情况下，只有 当前所有者（commands.ownerAllowFrom）才能审批 OpenClaw 变更。 独立的文件系统和沙箱边界、 工具策略以及下文中的操作限制仍然适用。主机还会检查 请求运行和已验证推理路由是否仍然有效。交互式 设置和代理交接仍然需要直接操作员会话；委托聊天 无法启动向导，即使模型建议这样做。

在人工审查提案期间，请求工具保持打开状态。Allow once 应用确切的提案并返回其应用结果；Deny 或过期 会返回未应用结果，而不是让代理报告一个待处理 变更。停止请求运行会取消它的审批。迟到的审批无法 重启已关闭的运行：如果仍需要，请从活动运行再次请求该变更。

已配置的代理可以通过其 openclaw 工具请求 OpenClaw 创建另一个代理。该请求进入相同的类型化创建代理操作和 主机授权流程；任何审批摘要都会指明请求代理。 OpenClaw 仍然是执行者，并且已授权的创建会将该请求 代理记录为新代理的创建者。

委托创建始终与请求运行绑定。如果该运行在准备期间结束或失去 权限，OpenClaw 会在开始下一个持久化 写入之前停止。已经进行中的写入可能会完成，并且之前创建的工作区文件 不会被自动删除。在从活动运行重试之前，请检查 openclaw agents list；如果某个代理的创建已经完成，则当其 请求运行结束时不会被删除。

Doctor 修复在 OpenClaw 内部不可用，因为它们可能会重写为会话提供支持的提供商、身份验证或默认代理推理路由。退出 OpenClaw 并在终端中运行 openclaw doctor --fix。只读 doctor 在 OpenClaw 内部仍然可用。

新代理继承经过实时验证的默认推理路由。代理 ID openclaw 和 crestodian 为系统代理保留，不能作为普通代理创建。已弃用的 ID 仍被阻止，因此旧配置无法占用它。

config set、config unset 和 config set-ref 会提出配置变更以供审批。 使用 config unset <path> 删除手工设置的设置，并让其继承值或 运行时默认值生效。设置代理使用带有 path 的 config_unset 执行相同 操作；将值设置为 null 不会删除它。已批准的 写入使用现有的配置验证器和写入器。验证或写入错误 会返回给助手，以进行一次更正提案，这需要新的审批。 保存后发生的失败会按此报告。配置写入不会测试模型 路由或 API 密钥是否可用。掩码设置流程会将密钥排除在模型 上下文之外。如果您仍然在聊天中粘贴 API 密钥或 Token，OpenClaw 会将其保存在 共享密钥存储中， 使用 store SecretRef 将配置键指向它，并且不会回显它。 粘贴的消息本身已经到达模型提供商和转录记录； 从那时起，OpenClaw 会在后续日志和输出中对该值进行掩码处理。每次保存 都会创建一个以配置键加随机后缀命名的新条目（例如 GATEWAY_REMOTE_TOKEN_3F9A0C1B7D2E4A68），因此它永远不会占用另一个配置键、身份验证配置或对已删除条目的过期引用 仍在使用的名称。OpenClaw 从不覆盖或删除现有条目：替换 密钥会将其先前条目保留在存储中。如果配置写入在密钥 保存后失败，错误会指明已保存的条目，并说明配置键 是否指向它。无论如何都会保留该条目，因为另一个配置键或身份验证 配置可能已经在使用它：请修复错误并复用该条目，而不是 再次粘贴密钥，并且仅当没有任何内容使用时，才使用 openclaw secrets store rm <NAME> 删除条目。对于环境存储，请使用 config set-ref <path> env <ENV_VAR>。 set default model <provider/model> 在保存前仍会实时测试该路由。

插件安装保留其来源限制。插件卸载会拒绝 支持活动推理路由的插件；退出 OpenClaw 并从终端运行 openclaw plugins uninstall <id>。

审批以您自己的措辞给出：明确的回复（"yes"、"sure"、"go ahead"、"not now"）会根据一个封闭的确定性列表进行判定。当配置的路由支持单独的完成调用时，其他回复可以仅根据您的消息和待处理提案进行分类——绝不能由对话模型本身进行分类，因为它不能自我审批。未分类或含糊的回复会使提案保持待处理状态，并且对话会再次询问。

变更历史

Ask OpenClaw 页面可以显示最近已应用的系统代理操作、Doctor 迁移、Settings 和 CLI 配置写入，以及对 openclaw.json 的手动编辑。配置日志会在 Gateway 正在监视时、OpenClaw 拥有的写入期间，或离线编辑后的 下次启动时检测外部编辑。

历史记录存储在共享 ~/.openclaw/state/openclaw.sqlite 数据库的 diagnostic_events 表中，位于 system-agent-audit 和 config-audit 作用域下。每个作用域保留其最新的 50,000 条记录。 发现操作和只读操作不包括在内。机密绝不会出现在变更历史中；配置日志记录包含已更改的路径，而不是配置值，并且值比较使用受保护的指纹。

配置写入记录在提供时保留写入者的 origin 标签。自动启动配置修复会记录 origin: "doctor"，即使控制台输出和运行时快照刷新被抑制。现有未标记记录不会回填。

频道、网络搜索和本地 Gateway 设置可以作为托管对话运行，直到遇到机密。本地 OpenClaw TUI 不接受敏感的向导答案，因为终端聊天输入可见。它会立即提供 open channel wizard（携带所选频道）、open search wizard 或 open gateway wizard，并交接给掩码终端向导；你也可以稍后运行 openclaw channels add --channel <channel> 或 openclaw configure --section web 或 openclaw configure --section gateway。

切换到掩码终端向导

本地聊天可以将控制权交给掩码终端向导：

open channel wizard for slack
channel info slack
open search wizard
open gateway wizard

open channel wizard for <channel> 在聊天 TUI 关闭后打开掩码频道设置。先使用 channel info <channel> 获取频道标签、设置状态、先决条件摘要和文档链接。open search wizard 对网络搜索提供商设置采用相同方式，在聊天 TUI 关闭后打开掩码搜索向导。open gateway wizard 打开掩码本地 Gateway 设置；完成后，运行 openclaw gateway restart 以应用已保存的设置。

configure model provider 会引导你前往 设置 → 模型 → 连接提供商，而不会启动向导或更改配置。在登录之前，请在设置中检查已连接的 Gateway 以及所选的 系统 或代理作用域，并使用那里的控件登录。连接另一个提供商不会将其选为活动模型，也不需要停止主机。模型选择是独立的；替换已在使用的提供商的凭据可能会影响工作。

设置引导

setup 在引导式入门已经建立推理之后，配置剩余的 workspace 和 Gateway 状态。它仅通过类型化配置操作写入，并首先请求批准。

setup
setup workspace ~/path/to/work

setup 保留已验证的有效模型。它不会配置或替换推理。

委托设置通过配置、workspace 和会话准备与请求方运行保持绑定。如果该运行结束或失去权限，OpenClaw 会在开始下一个持久化效果之前停止。先前已完成的效果仍然保留，包括创建已完成的代理；设置可能仍不完整。检查 openclaw agents list 和 status，然后从活动运行再次请求设置并批准新请求，或者直接在 Gateway 主机上使用 openclaw setup 完成。如果取消延迟了为新命名代理的旧版历史迁移，下次 Gateway 启动时会重试；在同一 state/config 上使用 openclaw doctor --fix 可更快完成。

如果推理缺失或其实时检查失败，请离开 OpenClaw 并运行 openclaw onboard。引导式入门会先尝试已配置的模型，然后尝试已认证的订阅 CLI、API 密钥以及其余受支持的 CLI；它会要求每个候选项给出真实回复，并仅持久化通过的路由。OpenClaw 在该边界之后立即启动，然后可以配置 workspace、Gateway、频道、代理、插件和其他可选功能。

当 macOS 应用到达一个已配置的 Gateway，且其默认代理已有已配置模型时，它会完全跳过此阶梯；它会打开常规代理 UI。 对于全新或不完整的 Gateway，应用通过 openclaw.setup.detect 和 openclaw.setup.activate Gateway 方法驱动推理阶梯： detect 列出它发现的每个候选后端，activate 实时测试一个候选项（一个真实的“回复 OK”完成），并且仅在测试通过后持久化该路由所需的模型、凭据和提供商/运行时状态。Workspace 和 Gateway 默认值仍保留给 OpenClaw。失败的候选项绝不会更改配置；应用会自动向下遍历阶梯，最后提供一个手动密钥/令牌步骤，该步骤由 Gateway 的活动文本推理提供商插件填充。所选提供商拥有其初始模型和配置，并且凭据在保存前以相同方式验证。

Codex 监督和其他可选插件功能保持在此推理激活事务之外。仅在推理正常工作且 OpenClaw 已启动后配置它们；在推理设置期间，现有插件策略和显式监督退出选项保持不变。

AI 对话

交互式 OpenClaw 的自由形式对话通过与普通 OpenClaw 代理相同的代理循环运行，限制为一个 ring-zero OpenClaw 权限工具 openclaw，它封装了类型化操作。读取操作可自由运行，变更操作需要你对该确切操作进行对话式批准（参见“操作和批准”），并且每个已应用的写入都会经过审计和重新验证。代理会话会持久化，因此 OpenClaw 具有真正的多轮记忆。如果已验证的推理路由后来停止工作，请返回 openclaw onboard 并在继续之前修复它。

失败或超时的回合会以可见错误结束该设置对话。 重试会开始新的对话，并再次实时检查推理路由。

系统代理回合使用 agents.defaults.timeoutSeconds，包括 0 以禁用截止时间，与普通代理回合一样。默认值为 48 小时；设置和修复没有单独的 2 分钟上限。

当普通代理调用其 openclaw 工具时，它通过正在运行的 Gateway 委托给此系统代理，而不是启动 CLI。这会添加一个单独的模型回合，因此常规会话和 workspace 检查应直接使用代理可用的工具。嵌入式系统助手不会加载 workspace 技能目录，因为它只能通过其内置系统工具操作。

主机不会将自然语言请求解析为操作。自由格式消息——包括看似命令的文本以及诸如“为什么我的 Gateway 停止了？”之类的问题——都会交给 AI，AI 可以通过 openclaw 工具将该请求映射为类型化操作。

当存在待处理的变更时，只有来自封闭列表的、无歧义的批准或拒绝短语才会被直接解析，而无需推断。含糊的同意会交给单独配置的补全调用处理，否则默认拒绝。结构化向导字段和精确的主机导航属于 UI 控件，而不是自然语言操作解析。一个密钥安全例外尤为重要：针对敏感路径（tokens、keys、passwords）的精确 config set 永远不会到达模型。主机会创建一个脱敏提案，并且该值在 AI 可见的历史记录中会被掩码处理。对于密钥，请优先使用 config set-ref <path> env <ENV_VAR>。

消息通道救援模式从不使用模型辅助的规划器。远程救援保持确定性，以便损坏或被入侵的正常代理路径不能被用作配置编辑器。

CLI 运行框架信任模型

嵌入式运行时和 Codex app-server 运行框架直接强制零环限制：该运行携带一个 OpenClaw 工具允许列表，其中只包含 openclaw 工具。对于 Codex，OpenClaw 还会在该运行中禁用 environments、native execution、multi-agent、goal、app/plugin、skill/MCP、web-search、request_user_input 以及其原生规划工具。CLI 运行框架不会使用 OpenClaw 的允许列表，因此 OpenClaw 只接受其自身工具选择契约能够证明相同限制的后端：

  • 可选择后端（包括 Claude Code）以空的 native-tool 选择和单个 MCP 工具 openclaw 启动。Claude 生成的 MCP 配置通过 --strict-mcp-config 应用，因此不会加载其他 MCP 服务器。
  • 声明没有原生工具的后端会获得同一个专用 OpenClaw MCP 服务器。
  • 始终开启或未知的原生工具后端会在推理前默认拒绝；它们无法承载 OpenClaw 会话。

只有 OpenClaw 会话会获得 openclaw MCP 服务器；正常代理运行永远不会看到此工具。因此，可选择/无原生 CLI 后端和 API-key 模型会强制字面上的单工具循环。Codex app-server 模型会强制单个 OpenClaw 权威工具加上无操作的原生规划工具。在这三种情况下，设置写入始终限制在 OpenClaw 的可审计审批契约内。

Gemini CLI 仍可作为正常代理的显式配置运行时使用，但 Gemini CLI 和 Antigravity 不是推理门设置路径。请使用 AI Studio API-key 或 Vertex AI 作为推理门。可选的 Gemini CLI 运行时特别要求一个 AI Studio API-key 配置文件。

切换到代理

使用自然语言选择器离开 OpenClaw 并打开正常 TUI：

talk to agent
talk to work agent
switch to main agent

openclaw tui、openclaw chat 和 openclaw terminal 会直接打开正常代理 TUI；它们不会启动 OpenClaw。切换到正常 TUI 后，/openclaw 会返回 OpenClaw，并可选择附带后续请求：

/openclaw
/openclaw restart gateway

消息救援模式

消息救援模式是 OpenClaw 的消息通道入口点：当你的正常代理已失效，但受信任的通道（例如 WhatsApp）仍能接收命令时，请使用它。

这是一个确定性的紧急命令处理器，而不是对话式 OpenClaw 代理。它不会引导全新设置，也不会放宽 OpenClaw 聊天的推理门。

支持的命令：/openclaw <request>。救援只接受精确的类型化命令语法——自然语言会被拒绝并给出提示，绝不会被猜测为操作，也绝不会咨询模型。

You, in a trusted owner DM: /openclaw status
OpenClaw: OpenClaw rescue mode. Gateway reachable: no. Config valid: no.
You: /openclaw restart gateway
OpenClaw: Plan: restart the Gateway. Reply /openclaw yes to apply.
You: /openclaw yes
OpenClaw: Applied. Audit entry written.

代理创建也可以在本地或通过救援排队：

create agent work workspace ~/path/to/work model openai/gpt-6-astra
/openclaw create agent work workspace ~/path/to/work

代理创建只能指定当前实时验证的默认模型。省略 model 以继承该路由。

救援审批会保留可选的代理详情，例如 create agent work purpose "Write release notes" workspace ~/path/to/work。 对于 set default model <provider/model> for agent work，审批会保留所选代理，而不是将该变更应用到全局默认。

远程救援是管理界面，必须将其视为远程配置修复，而不是正常聊天。

远程救援的安全契约：

  • 当代理/会话的沙箱处于激活状态时禁用；OpenClaw 会拒绝远程救援并指向本地 CLI 修复。
  • 默认生效状态为 auto：仅在受信任的 YOLO 操作中允许远程救援，此时运行时已经拥有无沙箱的本地权限（tools.exec.security 解析为 full，tools.exec.ask 解析为 off，且沙箱模式为 off）。
  • 要求显式的 owner 身份；不允许通配符发送者规则、开放群组策略、未认证 webhooks 或匿名通道。
  • 救援仅限于所有者 DM。
  • 插件搜索和列表为只读。插件安装始终仅限本地（在救援中被阻止，即使其他情况下已启用），因为它会下载可执行代码。插件卸载在本地 OpenClaw 和救援中均被拒绝；请从终端运行 openclaw plugins uninstall <id>。
  • 远程救援无法打开本地 TUI 或切换到交互式代理会话；请使用本地 openclaw 进行代理交接。
  • config unset 在远程救援中不可用，因为该路径无法在最终写入时重新验证所有者策略。请让你的常规代理通过设置助手移除该设置，或在本地运行 openclaw config unset <path>。
  • 持久化写入即使在救援模式下也需要审批。
  • 待处理审批为一次性。针对同一账户、通道和发送者的任何较新救援命令都会撤销旧计划；执行失败也会消耗审批，因此请重新发送命令以重试。
  • 每个已应用的救援操作都会被审计。消息通道救援会记录通道、账户、发送者和源地址元数据；配置变更操作还会记录变更前后的配置哈希。
  • 密钥永远不会被回显。SecretRef 检查报告可用性，而不是值。
  • 如果 Gateway 存活，救援会优先使用 Gateway 类型化操作；如果 Gateway 已失效，救援只使用不依赖正常代理循环的最小本地修复界面。

救援策略已内置：仅当有效运行时为 YOLO、沙箱已关闭且请求来自所有者私信时可用。待处理的写入审批在 15 分钟后过期。openclaw doctor --fix 会移除已弃用的 systemAgent 和 crestodian 配置块。

远程救援由 Docker 通道覆盖：

pnpm test:docker:system-agent-rescue

可选的实时通道命令表面冒烟测试会检查 /openclaw status，并通过救援处理器执行一次持久化审批往返：

pnpm test:live:system-agent-rescue-channel

推理门控的打包一次性设置由以下命令覆盖：

pnpm test:docker:system-agent-first-run

该打包 CLI 通道从空状态目录开始，并证明 OpenClaw 在没有推理时会失败关闭。随后，它通过打包激活模块测试并激活假 Claude。只有在此之后，模糊请求才会到达规划器并解析为类型化设置，接着执行一次性命令：创建额外代理、通过插件启用加 token SecretRef 配置 Discord、验证配置并检查审计日志。该通道用于提供门控/操作支持证据；它不会覆盖交互式入门或 OpenClaw 代理/工具/审批对话。下面的 QA Lab 场景重定向到同一 Docker 通道：

pnpm openclaw qa suite --scenario system-agent-ring-zero-setup

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