FAQ

快速解答加实战故障排查（本地开发、VPS、多 Agent、OAuth/API Key、模型故障转移）。运行时诊断见故障排查，完整配置参考见配置。

龙虾养好后如果出了问题，先别慌——大部分"我的龙虾不动了"情况都是本地配置或环境问题，照着这份 FAQ 查一遍通常能解决。

出问题后的前 60 秒

快速状态（第一步）
bash
```
openclaw status
```
本地快速摘要：OS + 更新、Gateway/服务可达性、Agent/会话、提供商配置 + 运行时问题（Gateway 可达时）。
可分享的诊断报告
bash
```
openclaw status --all
```
只读诊断，附带日志尾部（token 已脱敏）。
守护进程 + 端口状态
bash
```
openclaw gateway status
```
显示监管器运行时与 RPC 可达性、探测目标 URL、服务可能使用的配置。
深度探测
bash
```
openclaw status --deep
```
运行 Gateway 健康检查 + 提供商探测（需要 Gateway 可达）。参见健康检查。

跟踪最新日志

bash

openclaw logs --follow

如果 RPC 不可用，回退到：

bash

tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"

运行 doctor（修复工具）
bash
```
openclaw doctor
```
修复/迁移配置/状态 + 运行健康检查。参见 Doctor。

Gateway 快照

bash

openclaw health --json
openclaw health --verbose   # 出错时显示目标 URL + 配置路径

快速开始与首次配置

卡住了，最快的解决方式

使用能看到你机器的本地 AI Agent。这比在 Discord 里求助有效得多，因为大多数"我卡住了"的情况都是本地配置或环境问题，远程帮助者无法检查。

Claude Code：https://www.anthropic.com/claude-code/
OpenAI Codex：https://openai.com/codex/

这些工具可以读取仓库、运行命令、检查日志，并帮助修复机器级别的配置（PATH、服务、权限、认证文件）。给它提供完整源代码克隆（hackable 安装方式）：

bash

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

需要什么运行时？

需要 Node >= 22，推荐使用 pnpm。不推荐使用 Bun 运行 Gateway。

支持树莓派吗？

支持。Gateway 很轻量——文档列出 512MB-1GB RAM、1 核、约 500MB 磁盘即可个人使用，并指出 树莓派 4 可以运行。

推荐额外空间（日志、媒体、其他服务），建议 2GB，但不是硬性要求。

提示：小型树莓派/VPS 可以托管 Gateway，你可以在笔记本/手机上配对节点来使用本地屏幕/摄像头/画布或命令执行。参见节点。

引导向导实际做了什么？

openclaw onboard 是推荐的设置路径，本地模式下会引导你完成：

模型/认证设置（支持提供商 OAuth/setup-token 流程和 API Key，以及 LM Studio 等本地模型选项）
工作区位置 + 引导文件
Gateway 设置（绑定/端口/认证/Tailscale）
提供商（WhatsApp、Telegram、Discord、Mattermost（插件）、Signal、iMessage）
守护进程安装（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元）
健康检查和技能选择

OpenClaw 是什么？

OpenClaw 是你在自己设备上运行的个人 AI 助手。它在你已经使用的消息平台上回复（WhatsApp、Telegram、Slack、Mattermost（插件）、Discord、Google Chat、Signal、iMessage、WebChat），在支持的平台上还可以进行语音 + 实时画布交互。Gateway 是始终在线的控制平面，助手是核心产品。

主要优势：

你的设备，你的数据：在你想要的地方（Mac、Linux、VPS）运行 Gateway，工作区 + 会话历史保存在本地。
真实频道，而非 Web 沙箱：WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等，支持平台上还有移动端语音和画布。
模型无关：使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，支持每 Agent 路由和故障转移。
本地选项：运行本地模型，所有数据都可以保存在你的设备上。
多 Agent 路由：每个频道、账号或任务对应独立 Agent，各有自己的工作区和默认设置。
开源可定制：可检查、扩展和自托管，无供应商锁定。

技能与自动化

如何自定义技能而不弄脏仓库？

使用托管覆盖，而非编辑仓库副本。将你的修改放在 ~/.openclaw/skills/<name>/SKILL.md 中（或通过 skills.load.extraDirs 添加文件夹）。优先级为 <workspace>/skills > ~/.openclaw/skills > 内置，托管覆盖会胜出，无需修改 git。只有值得上游合并的编辑才应放在仓库中并提交 PR。

可以从自定义文件夹加载技能吗？

可以。通过 skills.load.extraDirs 添加额外目录（最低优先级）。默认优先级仍为：<workspace>/skills → ~/.openclaw/skills → 内置 → skills.load.extraDirs。

如何为不同任务使用不同模型？

当前支持的模式：

定时任务：每个独立任务可以设置 model 覆盖。
子 Agent：将任务路由到具有不同默认模型的独立 Agent。
按需切换：使用 /model 随时切换当前会话的模型。

参见定时任务、多 Agent 路由和斜杠命令。

定时任务或提醒不触发，该怎么查？

定时任务在 Gateway 进程内运行，Gateway 不持续运行时不会触发。

检查清单：

确认定时任务已启用（cron.enabled）且未设置 OPENCLAW_SKIP_CRON。
确认 Gateway 24/7 运行（无睡眠/重启）。
验证任务的时区设置（--tz vs 主机时区）。

调试：

bash

openclaw cron run <jobId> --force
openclaw cron runs --id <jobId> --limit 50

参见定时任务。

沙箱与内存

内存如何工作？

OpenClaw 内存就是 Agent 工作区中的 Markdown 文件：

每日记录：memory/YYYY-MM-DD.md
精华长期记录：MEMORY.md（仅主/私有会话）

OpenClaw 还会在自动压缩前运行静默预压缩内存刷新，提醒模型写入持久记录。工作区为只读时（只读沙箱）跳过此步骤。参见内存。

内存一直忘事，怎么让它记住？

让 Bot 写入记忆。长期记录放 MEMORY.md，短期上下文放 memory/YYYY-MM-DD.md。

提示：每次对话中提醒模型存储记忆会有帮助；确认 Gateway 每次运行时使用相同的工作区。

参见内存、Agent 工作区。

语义记忆搜索需要 OpenAI API Key 吗？

只有使用 OpenAI embeddings 时才需要。Codex OAuth 覆盖聊天/补全，不包括 embeddings 访问，所以用 Codex 登录无法进行语义记忆搜索。OpenAI embeddings 仍需要真实 API Key。

如果不设置提供商，OpenClaw 在能解析到 API Key 时会自动选择（按优先级：OpenAI > Gemini > Voyage > Mistral）。如果无远程 Key，记忆搜索保持禁用。

也可以设置为本地：memorySearch.provider = "local" 或 Gemini：memorySearch.provider = "gemini"（需要 GEMINI_API_KEY）。支持 OpenAI、Gemini、Voyage、Mistral、Ollama 或本地嵌入模型。

数据存储位置

OpenClaw 把数据存在哪里？

所有数据存在 $OPENCLAW_STATE_DIR 下（默认：~/.openclaw）：

路径	用途
`$OPENCLAW_STATE_DIR/openclaw.json`	主配置（JSON5）
`$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json`	认证 profiles（OAuth、API Key 等）
`$OPENCLAW_STATE_DIR/credentials/`	提供商状态（如 WhatsApp creds）
`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`	每 Agent 的对话历史和状态

你的工作区（AGENTS.md、内存文件、技能等）是独立的，通过 agents.defaults.workspace 配置（默认：~/.openclaw/workspace）。

AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放哪里？

这些文件放在 Agent 工作区，而不是 ~/.openclaw。

工作区（每 Agent）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md、memory/YYYY-MM-DD.md、可选的 HEARTBEAT.md。
状态目录（~/.openclaw）：配置、凭据、认证 profiles、会话、日志。

如果 Bot 重启后"忘记了一切"，确认 Gateway 每次启动都使用相同工作区。

参见 Agent 工作区和内存。

备份策略建议

把 Agent 工作区放在私有 git 仓库中并备份到私有位置（如 GitHub 私有仓库），这可以保存内存 + AGENTS/SOUL/USER 文件，让你以后恢复助手的"大脑"。

不要提交 ~/.openclaw 下的任何内容（凭据、会话、token 或加密密钥）。

参见 Agent 工作区。

配置基础

非回环地址绑定后 UI 报"unauthorized"

非回环绑定需要认证。配置 gateway.auth.mode + gateway.auth.token（或使用 OPENCLAW_GATEWAY_TOKEN）：

json5

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

注意：gateway.remote.token / .password 本身不能启用本地 Gateway 认证。

为什么本地 localhost 也需要 token？

OpenClaw 默认对所有连接（包括回环）强制 token 认证。如果未配置 token，Gateway 启动时会自动生成一个并保存到 gateway.auth.token，本地 WS 客户端必须认证，这可以阻止其他本地进程调用 Gateway。

如果确实想要开放回环，在配置中显式设置 gateway.auth.mode: "none"。Doctor 随时可以为你生成 token：openclaw doctor --generate-gateway-token。

修改配置后需要重启吗？

Gateway 会监视配置并支持热重载：

gateway.reload.mode: "hybrid"（默认）：安全更改热应用，关键更改需重启。
也支持 hot、restart、off。

如何启用网络搜索（web_search 和 web_fetch）？

web_fetch 无需 API Key。web_search 需要你选择的提供商的 Key（Brave、Gemini、Grok、Kimi 或 Perplexity）。

推荐：运行 openclaw configure --section web 选择提供商。

环境变量方式：

Brave：BRAVE_API_KEY
Gemini：GEMINI_API_KEY
Grok：XAI_API_KEY
Kimi：KIMI_API_KEY 或 MOONSHOT_API_KEY
Perplexity：PERPLEXITY_API_KEY 或 OPENROUTER_API_KEY

参见 Web 工具。

远程 Gateway 与节点

命令如何在 Telegram、Gateway 和节点之间传递？

Telegram 消息由 Gateway 处理。Gateway 运行 Agent，只有在需要节点工具时才通过 Gateway WebSocket 调用节点：

Telegram → Gateway → Agent → node.* → Node → Gateway → Telegram

节点不接收入站提供商流量，只接收节点 RPC 调用。

如果 Gateway 托管在远端，如何让 Agent 访问我的电脑？

简答：把你的电脑配对为节点。Gateway 在其他地方运行，但可以通过 Gateway WebSocket 调用你本地机器上的 node.* 工具（屏幕、摄像头、系统）。

典型配置：

在始终在线的主机（VPS/家庭服务器）上运行 Gateway。
把 Gateway 主机和你的电脑放在同一个 tailnet。
确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。
在本地打开 macOS 应用并以远程 SSH 模式（或直接 tailnet）连接，注册为节点。

在 Gateway 上审批节点：

bash

openclaw devices list
openclaw devices approve <requestId>

参见节点、macOS 远程模式、安全。

多个 Agent 需要独立的 VPS 吗？

不需要。一个 Gateway 可以托管多个 Agent，每个有独立的工作区、模型默认值和路由。这是正常配置，比每个 Agent 一台 VPS 便宜得多也简单得多。

只有在需要硬隔离（安全边界）或非常不同的配置时才考虑独立 VPS。

环境变量和 .env 加载

Gateway 作为服务启动后环境变量消失了

两个常见修复方案：

把缺失的 Key 放入 ~/.openclaw/.env，这样即使服务没有继承你的 shell 环境也能被读取。
启用 shell 导入（便利功能，需手动开启）：

json5

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

这会运行你的 login shell 并仅导入缺失的预期键（不覆盖已有值）。等价环境变量： OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

参见环境变量。

会话与多聊天

如何开始全新对话？

发送独立消息 /new 或 /reset。参见会话管理。

会话会自动重置吗？

会。会话在 session.idleMinutes（默认 60）后过期。下一条消息会为该聊天 key 开启新会话 ID，不会删除历史记录。

json5

{
  session: {
    idleMinutes: 240,
  },
}

上下文被截断了，怎么避免？

会话上下文受模型窗口限制，长对话、大型工具输出或大量文件会触发压缩或截断。

有帮助的操作：

让 Bot 总结当前状态并写入文件。
长任务前使用 /compact，切换主题时使用 /new。
把重要上下文放在工作区里，让 Bot 需要时读回来。
用子 Agent 处理长任务或并行工作，保持主聊天简洁。
频繁发生时，换用上下文窗口更大的模型。

模型：默认、选择、别名、切换

什么是"默认模型"？

OpenClaw 的默认模型是你设置的：

agents.defaults.model.primary

模型引用格式为 provider/model（例如：anthropic/claude-opus-4-6）。

如何实时切换模型（无需重启）？

在聊天中发送独立的 /model 命令：

/model sonnet
/model haiku
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash

用 /model、/model list 或 /model status 列出可用模型。

/model 显示紧凑的编号选择器，按编号选择：

/model 3

也可以强制使用特定认证 profile（每个会话）：

/model opus@anthropic:default
/model opus@anthropic:work

可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？

可以，Ollama 是本地模型的最简单途径：

从 https://ollama.com/download 安装 Ollama
拉取本地模型：ollama pull glm-4.7-flash
如需 Ollama Cloud，运行 ollama signin
运行 openclaw onboard 并选择 Ollama
选择 Local 或 Cloud + Local

安全提示：较小或重度量化的模型更容易受到提示注入。强烈建议对任何可以使用工具的 Bot 使用大模型。

参见 Ollama、本地模型、安全。

为什么看到 "HTTP 429 rate_limit_error" 来自 Anthropic？

这意味着你的 Anthropic 配额/速率限制已耗尽。如果你使用 Claude 订阅（setup-token），等待窗口重置或升级计划；如果使用 Anthropic API Key，在 Anthropic Console 检查用量/账单并提高限制。

如果错误信息是 Extra usage is required for long context requests，请求尝试使用 Anthropic 的 1M 上下文 beta（context1m: true），只有具备长上下文计费资格的凭据才能使用。

提示：设置备用模型，这样即使提供商有速率限制，OpenClaw 也能继续回复。

参见模型、OAuth、故障排查。

认证 Profile：是什么以及如何管理

什么是认证 Profile？

认证 profile 是与提供商绑定的命名凭据记录（OAuth 或 API Key），存储在：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

"No credentials found for profile anthropic:default" 是什么意思？

修复清单：

确认认证 profile 存储位置（新路径 vs 旧路径）
- 当前：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
- 旧版：~/.openclaw/agent/*（由 openclaw doctor 迁移）
确认 Gateway 加载了你的环境变量
- 如果你在 shell 中设置了 ANTHROPIC_API_KEY 但通过 systemd/launchd 运行 Gateway，可能没有继承。把它放入 ~/.openclaw/.env 或启用 env.shellEnv。
使用 setup-token 的方案
- 运行 claude setup-token，然后通过 openclaw models auth paste-token --provider anthropic 粘贴。
确认是否在 Gateway 主机上运行命令
- 远程模式下，认证 profiles 在 Gateway 机器上，不在你的本地笔记本上。

故障转移与多 Profile

故障转移如何工作？

故障转移分两个阶段：

同一提供商内的认证 profile 轮换。
模型备用，切换到 agents.defaults.model.fallbacks 中的下一个模型。

故障 profile 适用冷却时间（指数退避），即使提供商有速率限制或暂时故障，OpenClaw 也能继续响应。

FAQ ​

出问题后的前 60 秒 ​

快速开始与首次配置 ​

卡住了，最快的解决方式 ​

推荐的安装和配置方式 ​

需要什么运行时？ ​

支持树莓派吗？ ​

引导向导实际做了什么？ ​

OpenClaw 是什么？ ​

技能与自动化 ​

如何自定义技能而不弄脏仓库？ ​

可以从自定义文件夹加载技能吗？ ​

如何为不同任务使用不同模型？ ​

定时任务或提醒不触发，该怎么查？ ​

沙箱与内存 ​

内存如何工作？ ​

内存一直忘事，怎么让它记住？ ​

语义记忆搜索需要 OpenAI API Key 吗？ ​

数据存储位置 ​

OpenClaw 把数据存在哪里？ ​

AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放哪里？ ​

备份策略建议 ​

配置基础 ​

非回环地址绑定后 UI 报"unauthorized" ​

为什么本地 localhost 也需要 token？ ​

修改配置后需要重启吗？ ​

如何启用网络搜索（web_search 和 web_fetch）？ ​

远程 Gateway 与节点 ​

命令如何在 Telegram、Gateway 和节点之间传递？ ​

如果 Gateway 托管在远端，如何让 Agent 访问我的电脑？ ​

多个 Agent 需要独立的 VPS 吗？ ​

环境变量和 .env 加载 ​

Gateway 作为服务启动后环境变量消失了 ​

会话与多聊天 ​

如何开始全新对话？ ​

会话会自动重置吗？ ​

上下文被截断了，怎么避免？ ​

模型：默认、选择、别名、切换 ​

什么是"默认模型"？ ​

如何实时切换模型（无需重启）？ ​

可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？ ​

为什么看到 "HTTP 429 rate_limit_error" 来自 Anthropic？ ​

认证 Profile：是什么以及如何管理 ​

什么是认证 Profile？ ​

"No credentials found for profile anthropic:default" 是什么意思？ ​

故障转移与多 Profile ​

故障转移如何工作？ ​

FAQ

出问题后的前 60 秒

快速开始与首次配置

卡住了，最快的解决方式

推荐的安装和配置方式

需要什么运行时？

支持树莓派吗？

引导向导实际做了什么？

OpenClaw 是什么？

技能与自动化

如何自定义技能而不弄脏仓库？

可以从自定义文件夹加载技能吗？

如何为不同任务使用不同模型？

定时任务或提醒不触发，该怎么查？

沙箱与内存

内存如何工作？

内存一直忘事，怎么让它记住？

语义记忆搜索需要 OpenAI API Key 吗？

数据存储位置

OpenClaw 把数据存在哪里？

AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放哪里？

备份策略建议

配置基础

非回环地址绑定后 UI 报"unauthorized"

为什么本地 localhost 也需要 token？

修改配置后需要重启吗？

如何启用网络搜索（web_search 和 web_fetch）？

远程 Gateway 与节点

命令如何在 Telegram、Gateway 和节点之间传递？

如果 Gateway 托管在远端，如何让 Agent 访问我的电脑？

多个 Agent 需要独立的 VPS 吗？

环境变量和 .env 加载

Gateway 作为服务启动后环境变量消失了

会话与多聊天

如何开始全新对话？

会话会自动重置吗？

上下文被截断了，怎么避免？

模型：默认、选择、别名、切换

什么是"默认模型"？

如何实时切换模型（无需重启）？

可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？

为什么看到 "HTTP 429 rate_limit_error" 来自 Anthropic？

认证 Profile：是什么以及如何管理

什么是认证 Profile？

"No credentials found for profile anthropic:default" 是什么意思？

故障转移与多 Profile

故障转移如何工作？