常见问题 FAQ

快速解答及真实场景的深度故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）。

运行时诊断请参阅 故障排除。完整配置参考请参阅 配置。

目录

• 快速开始与首次运行设置
• 什么是 OpenClaw
• 技能与自动化
• 沙箱与记忆
• 磁盘存储位置
• 配置基础
• 远程网关与节点
• 会话与多聊天
• 模型：默认、选择、别名、切换
• 网关：端口、"already running"、远程模式
• 日志与调试
• 安全与访问控制

---

快速开始与首次运行设置

我被卡住了，最快的解决方法是什么？

使用能查看你机器的本地 AI 代理。这比在 Discord 上提问更有效，因为大多数"卡住"的情况是本地配置或环境问题，远程帮助者无法检查。

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

给他们完整的源码检出（通过 hackable git 安装）：

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

从这些命令开始（求助时分享输出）：

openclaw status
openclaw models status
openclaw doctor

推荐的安装和设置方式是什么？

推荐从源码运行并使用入门向导：

curl -fsSL https://openclaw.bot/install.sh | bash
openclaw onboard --install-daemon

入门后如何打开控制台？

向导现在会在入门后直接打开带有 token 的控制台 URL，并在摘要中打印完整链接。

需要什么运行时？

Node >= 22 是必需的。推荐使用 pnpm。不推荐 Bun 用于网关。

能在树莓派上运行吗？

可以。网关很轻量 - 文档列出 512MB-1GB RAM、1 核心、约 500MB 磁盘足够个人使用。树莓派 4 可以运行。

我需要 Claude 或 OpenAI 订阅才能运行吗？

不需要。你可以用 API 密钥（Anthropic/OpenAI/其他）或 纯本地模型 运行 OpenClaw，这样数据完全留在你的设备上。

可以使用 Claude Max 订阅而不用 API 密钥吗？

可以。你可以用 setup-token 而不是 API 密钥进行认证。

AWS Bedrock 支持吗？

支持 - 通过 pi-ai 的 Amazon Bedrock (Converse) provider，需要手动配置。

我必须买 Mac Mini 才能安装吗？

不需要。OpenClaw 在 macOS 或 Linux（Windows 通过 WSL2）上运行。Mac mini 是可选的。

---

什么是 OpenClaw

一段话描述 OpenClaw

OpenClaw 是你在自己设备上运行的个人 AI 助手。它在你已经使用的消息平台（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat）上回复，支持的平台还可以语音和实时 Canvas。Gateway 是常驻控制面板；助手是产品。

价值主张是什么？

OpenClaw 不是"只是一个 Claude 包装器"。它是一个本地优先的控制面板，让你在自己的硬件上运行强大的助手，从你已经使用的聊天应用访问，具有状态会话、记忆和工具 - 无需将工作流控制权交给托管 SaaS。

---

技能与自动化

如何自定义技能而不污染仓库？

使用托管覆盖而不是编辑仓库副本。把更改放在 ~/.openclaw/skills/<<name>>/SKILL.md，或通过 skills.load.extraDirs 添加文件夹。

Cron 或提醒不触发，该检查什么？

Cron 在 Gateway 进程内运行。如果 Gateway 没有持续运行，计划任务不会执行。

检查清单：

• 确认 cron 已启用 (cron.enabled) 且 OPENCLAW_SKIP_CRON 未设置
• 检查 Gateway 是否 24/7 运行
• 验证任务的时区设置

调试：

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

---

沙箱与记忆

有专门的沙箱文档吗？

有。参见 沙箱。Docker 特定设置参见 Docker。

记忆如何工作？

记忆存储在 MEMORY.md 和 memory/*.md 中。支持向量语义搜索。

openclaw memory status   # 查看索引状态
openclaw memory index    # 重建索引
openclaw memory search "<query>"  # 语义搜索

---

磁盘存储位置

OpenClaw 在哪里存储数据？

• 配置: ~/.openclaw/openclaw.json
• 状态目录: ~/.openclaw/
• 工作区: ~/.openclaw/workspace（默认）
• 会话: ~/.openclaw/agents/<<agentId>>/sessions/
• 认证配置: ~/.openclaw/auth/

推荐的备份策略是什么？

备份 ~/.openclaw/ 目录。如果你把工作区 git 提交/推送到 GitHub，你在备份 记忆 + 引导文件，但不包括会话历史或认证。

---

配置基础

配置是什么格式？在哪里？

配置文件是 ~/.openclaw/openclaw.json，格式为 JSON5（允许注释）。

更改配置后必须重启吗？

大多数更改需要 Gateway 重启。你可以用：

openclaw gateway restart

---

远程网关与节点

如何在远程模式下运行 OpenClaw？

SSH 隧道：

ssh -N -L 18789:127.0.0.1:18789 user@host

然后在本地打开 http://127.0.0.1:18789/?token=...

或使用 Tailscale。

节点会运行网关服务吗？

不会。节点不运行网关 - 它们连接到网关并提供额外能力（屏幕/摄像头/Canvas/命令执行）。

---

会话与多聊天

如何开始新对话？

发送 /new 命令。

会话会自动重置吗？

不会自动重置。使用 /new 手动重置。

---

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

默认模型是什么？

默认模型在配置中设置，或由 openclaw models set <model> 设定。

推荐什么模型？

对于编程任务，Claude Sonnet 或 Opus 表现最好。日常聊天可以用更快的模型。

如何动态切换模型？

使用 /model 命令在聊天中切换当前会话的模型。

---

网关：端口、"already running"、远程模式

网关使用什么端口？

默认 18789。Canvas 主机默认 18793。

"another gateway instance is already listening" 是什么意思？

端口已被占用。检查是否有其他网关实例在运行：

openclaw gateway status

强制启动（会杀死现有监听器）：

openclaw gateway --force

---

日志与调试

日志在哪里？

openclaw logs --follow

文件日志在 /tmp/openclaw/openclaw-*.log。

如何启动/停止/重启网关服务？

openclaw gateway start
openclaw gateway stop
openclaw gateway restart

---

安全与访问控制

暴露 OpenClaw 给入站 DM 安全吗？

配置 allowFrom 限制谁可以与你的 bot 交互。对于公开 bot，需要额外的安全措施。

WhatsApp 会消息我的联系人吗？

不会主动。OpenClaw 只回复发给它的消息。配对是通过 WhatsApp Web 二维码完成的。

---

更多问题？请查阅 故障排除 或提交 GitHub Issue。