该页面是英文文档的中文占位版本，完整内容请先参考英文版：Agent Bootstrapping。

工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密性并将其视为记忆。 这与 ~/.openclaw/ 是分开的，后者存储配置、凭证和会话。 重要： 工作区是默认 cwd，而不是硬性沙箱。工具会根据工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用 agents.defaults.sandbox（和/或每智能体沙箱配置）。 当启用沙箱隔离且 workspaceAccess 不是 "rw" 时，工具在 ~/.openclaw/sandboxes 下的沙箱工作区内操作，而不是你的主机工作区。 默认位置 默认：~/.openclaw/workspace 如果设置了 OPENCLAW_PROFILE 且不是 "default"，默认值变为 ~/.openclaw/workspace-<profile>。 在 ~/.openclaw/openclaw.json 中覆盖： { agent: { workspace: "~/.openclaw/workspace", }, } openclaw onboard、openclaw configure 或 openclaw setup 将创建工作区并在缺失时填充引导文件。 如果你已经自己管理工作区文件，可以禁用引导文件创建： { agent: { skipBootstrap: true } } 额外的工作区文件夹 旧版安装可能创建了 ~/openclaw。保留多个工作区目录可能会导致混乱的认证或状态漂移，因为同一时间只有一个工作区是活动的。 建议： 保持单个活动工作区。如果你不再使用额外的文件夹，请归档或移至废纸篓（例如 trash ~/openclaw）。 如果你有意保留多个工作区，请确保 agents.defaults.workspace 指向活动的那个。 openclaw doctor 在检测到额外工作区目录时会发出警告。 工作区文件映射（每个文件的含义） 这些是 OpenClaw 在工作区内期望的标准文件： AGENTS.md 智能体的操作指南以及它应该如何使用记忆。 在每个会话开始时加载。 适合放置规则、优先级和"如何行为"的详细信息。 SOUL.md 人设、语气和边界。 每个会话加载。 USER.md ...

OpenClaw 对时间戳进行标准化，使模型看到单一的参考时间。 消息信封（默认为本地时间） 入站消息被包装在如下信封中： [Provider ... 2026-01-05 16:26 PST] message text 信封中的时间戳默认为主机本地时间，精确到分钟。 你可以通过以下配置进行覆盖： { agents: { defaults: { envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区 envelopeTimestamp: "on", // "on" | "off" envelopeElapsed: "on", // "on" | "off" }, }, } envelopeTimezone: "utc" 使用 UTC。 envelopeTimezone: "user" 使用 agents.defaults.userTimezone（回退到主机时区）。 使用显式 IANA 时区（例如 "Europe/Vienna"）可设置固定偏移量。 envelopeTimestamp: "off" 从信封头中移除绝对时间戳。 envelopeElapsed: "off" 移除已用时间后缀（+2m 样式）。 示例 本地时间（默认）： [Signal Alice +1555 2026-01-18 00:19 PST] hello 固定时区： ...

OpenClaw 默认使用主机本地时间作为传输时间戳，并且仅在系统提示词中使用用户时区。 提供商时间戳会被保留，因此工具保持其原生语义（当前时间可通过 session_status 获取）。 消息信封（默认为本地时间） 入站消息会附带一个时间戳（分钟精度）： [Provider ... 2026-01-05 16:26 PST] message text 此信封时间戳默认为主机本地时间，与提供商时区无关。 你可以覆盖此行为： { agents: { defaults: { envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区 envelopeTimestamp: "on", // "on" | "off" envelopeElapsed: "on", // "on" | "off" }, }, } envelopeTimezone: "utc" 使用 UTC。 envelopeTimezone: "local" 使用主机时区。 envelopeTimezone: "user" 使用 agents.defaults.userTimezone（回退到主机时区）。 使用显式 IANA 时区（例如 "America/Chicago"）指定固定时区。 envelopeTimestamp: "off" 从信封头中移除绝对时间戳。 envelopeElapsed: "off" 移除已用时间后缀（+2m 样式）。 示例 本地时间（默认）： ...

滚动诊断文件日志（Debug 面板） OpenClaw 通过 swift-log（默认使用统一日志）路由 macOS 应用日志，并且在需要持久化捕获时可以将本地轮转文件日志写入磁盘。 详细级别：Debug 面板 → Logs → App logging → Verbosity 启用：Debug 面板 → Logs → App logging → “Write rolling diagnostics log (JSONL)” 位置：~/Library/Logs/OpenClaw/diagnostics.jsonl（自动轮转；旧文件以 .1、.2、… 为后缀） 清除：Debug 面板 → Logs → App logging → “Clear” 注意事项： 此功能默认关闭。仅在主动调试时启用。 该文件包含敏感信息；分享前请先审查内容。 macOS 上统一日志的隐私数据 统一日志会屏蔽大部分负载内容，除非子系统选择启用 privacy -off。根据 Peter 关于 macOS 日志隐私机制（2025）的文章，这通过 /Library/Preferences/Logging/Subsystems/ 中以子系统名称为键的 plist 文件来控制。只有新的日志条目才会应用该标志，因此请在复现问题之前启用它。 为 OpenClaw 启用（bot.molt） 先将 plist 写入临时文件，然后以 root 身份原子性地安装： cat <<'EOF' >/tmp/bot.molt.plist <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>DEFAULT-OPTIONS</key> <dict> <key>Enable-Private-Data</key> <true/> </dict> </dict> </plist> EOF sudo install -m 644 -o root -g wheel /tmp/bot.molt.plist /Library/Preferences/Logging/Subsystems/bot.molt.plist 无需重启；logd 会很快检测到该文件，但只有新的日志行才会包含隐私负载。 使用现有的辅助脚本查看更丰富的输出，例如 ./scripts/clawlog.sh --category WebChat --last 5m。 调试后禁用 移除覆盖配置：sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist。 可选择运行 sudo log config --reload 强制 logd 立即丢弃覆盖配置。 请注意此数据可能包含电话号码和消息正文；仅在确实需要额外详细信息时才保留该 plist 文件。

OpenClaw 在两个地方记录日志： 文件日志（JSON 行）由 Gateway 网关写入。 控制台输出显示在终端和控制 UI 中。 本页说明日志存放位置、如何读取日志以及如何配置日志级别和格式。 日志存放位置 默认情况下，Gateway 网关在以下位置写入滚动日志文件： /tmp/openclaw/openclaw-YYYY-MM-DD.log 日期使用 Gateway 网关主机的本地时区。 你可以在 ~/.openclaw/openclaw.json 中覆盖此设置： { "logging": { "file": "/path/to/openclaw.log" } } 如何读取日志 CLI：实时跟踪（推荐） 使用 CLI 通过 RPC 跟踪 Gateway 网关日志文件： openclaw logs --follow 输出模式： TTY 会话：美观、彩色、结构化的日志行。 非 TTY 会话：纯文本。 --json：行分隔的 JSON（每行一个日志事件）。 --plain：在 TTY 会话中强制纯文本。 --no-color：禁用 ANSI 颜色。 在 JSON 模式下，CLI 输出带 type 标签的对象： meta：流元数据（文件、游标、大小） log：解析的日志条目 notice：截断/轮转提示 raw：未解析的日志行 如果 Gateway 网关无法访问，CLI 会打印一个简短提示运行： openclaw doctor 控制 UI（Web） 控制 UI 的日志标签页使用 logs.tail 跟踪相同的文件。 参见 /web/control-ui 了解如何打开它。 ...

面向用户的概览（CLI + Control UI + 配置），请参阅 /logging。 OpenClaw 有两个日志"界面"： 控制台输出（你在终端 / Debug UI 中看到的内容）。 文件日志（JSON 行）由 Gateway 网关日志记录器写入。 基于文件的日志记录器 默认滚动日志文件位于 /tmp/openclaw/ 下（每天一个文件）：openclaw-YYYY-MM-DD.log 日期使用 Gateway 网关主机的本地时区。 日志文件路径和级别可以通过 ~/.openclaw/openclaw.json 配置： logging.file logging.level 文件格式是每行一个 JSON 对象。 Control UI 的 Logs 标签页通过 Gateway 网关（logs.tail）尾随此文件。CLI 也可以这样做： openclaw logs --follow Verbose 与日志级别 文件日志完全由 logging.level 控制。 --verbose 仅影响控制台详细程度（和 WS 日志样式）；它不会提高文件日志级别。 要在文件日志中捕获仅 verbose 的详细信息，请将 logging.level 设置为 debug 或 trace。 控制台捕获 CLI 捕获 console.log/info/warn/error/debug/trace 并将它们写入文件日志，同时仍打印到 stdout/stderr。 你可以独立调整控制台详细程度： logging.consoleLevel（默认 info） logging.consoleStyle（pretty | compact | json） 工具摘要脱敏 详细工具摘要（例如 🛠️ Exec: ...）可以在进入控制台流之前屏蔽敏感令牌。这仅限工具，不会更改文件日志。 ...

新手引导向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。 它可以在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills 和工作区默认值。 主要入口： openclaw onboard 最快开始聊天的方式：打开控制界面（无需设置渠道）。运行 openclaw dashboard 并在浏览器中聊天。文档：控制面板。 后续重新配置： openclaw configure 推荐：设置 Brave Search API 密钥，以便智能体可以使用 web_search（web_fetch 无需密钥即可使用）。最简单的方式：openclaw configure --section web，它会存储 tools.web.search.apiKey。文档：Web 工具。 快速开始 vs 高级 向导从快速开始（默认值）vs 高级（完全控制）开始。 快速开始保持默认值： 本地 Gateway 网关（loopback） 默认工作区（或现有工作区） Gateway 网关端口 18789 Gateway 网关认证 Token（自动生成，即使在 loopback 上） Tailscale 暴露 关闭 Telegram + WhatsApp 私信默认使用允许列表（系统会提示你输入电话号码） 高级暴露每个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。 向导做了什么 **本地模式（默认）**引导你完成： 模型/认证（OpenAI Code (Codex) 订阅 OAuth、Anthropic API 密钥（推荐）或 setup-token（粘贴），以及 MiniMax/GLM/Moonshot/AI Gateway 选项） 工作区位置 + 引导文件 Gateway 网关设置（端口/绑定/认证/tailscale） 提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal） 守护进程安装（LaunchAgent / systemd 用户单元） 健康检查 Skills（推荐） 远程模式仅配置本地客户端连接到其他位置的 Gateway 网关。 它不会在远程主机上安装或更改任何内容。 ...

本文档描述当前的首次运行新手引导流程。目标是流畅的"第 0 天"体验：选择 Gateway 网关运行位置、连接认证、运行向导，然后让智能体自行引导。 页面顺序（当前） 欢迎 + 安全提示 Gateway 网关选择（本地 / 远程 / 稍后配置） 认证（Anthropic OAuth） — 仅限本地 设置向导（Gateway 网关驱动） 权限（TCC 提示） CLI（可选） 新手引导聊天（专用会话） 就绪 1) 欢迎 + 安全提示 阅读显示的安全提示并相应决定。 2) 本地 vs 远程 Gateway 网关在哪里运行？ 本地（此 Mac）： 新手引导可以在本地运行 OAuth 流程并写入凭证。 远程（通过 SSH/Tailnet）： 新手引导不会在本地运行 OAuth；凭证必须存在于 Gateway 网关主机上。 稍后配置： 跳过设置并保持应用未配置状态。 Gateway 网关认证提示： 向导现在即使对于 loopback 也会生成令牌，因此本地 WS 客户端必须认证。 如果你禁用认证，任何本地进程都可以连接；仅在完全受信任的机器上使用。 对于多机器访问或非 loopback 绑定，使用令牌。 3) 仅限本地的认证（Anthropic OAuth） macOS 应用支持 Anthropic OAuth（Claude Pro/Max）。流程： 打开浏览器进行 OAuth（PKCE） 要求用户粘贴 code#state 值 将凭证写入 ~/.openclaw/credentials/oauth.json 其他提供商（OpenAI、自定义 API）目前通过环境变量或配置文件配置。 ...

目的：CLI、macOS 应用和 Web UI 之间共享的新手引导 + 配置界面。 组件 向导引擎（共享会话 + 提示 + 新手引导状态）。 CLI 新手引导使用与 UI 客户端相同的向导流程。 Gateway 网关 RPC 公开向导 + 配置模式端点。 macOS 新手引导使用向导步骤模型。 Web UI 从 JSON Schema + UI 提示渲染配置表单。 Gateway 网关 RPC wizard.start 参数：{ mode?: "local"|"remote", workspace?: string } wizard.next 参数：{ sessionId, answer?: { stepId, value? } } wizard.cancel 参数：{ sessionId } wizard.status 参数：{ sessionId } config.schema 参数：{} 响应（结构） 向导：{ sessionId, done, step?, status?, error? } 配置模式：{ schema, uiHints, version, generatedAt } UI 提示 uiHints 按路径键入；可选元数据（label/help/group/order/advanced/sensitive/placeholder）。 敏感字段渲染为密码输入；无脱敏层。 不支持的模式节点回退到原始 JSON 编辑器。 注意 本文档是跟踪新手引导/配置协议重构的唯一位置。