FAQ：首次运行与安装

首次安装、onboarding 和初始配置的常见问题解答。

快速解困

遇到问题时，优先使用能看到你机器的本地 AI Agent（Claude Code 或 OpenAI Codex），比在 Discord 求助更有效。

openclaw status          # 快速状态快照
openclaw models status   # 检查 Provider 认证和模型可用性
openclaw doctor          # 验证并修复常见配置/状态问题

安装与运行时

推荐安装方式：

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

从源码安装（贡献者/开发）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm build && pnpm ui:build
openclaw onboard

运行时要求： Node >= 22，推荐 pnpm。不推荐 Bun（Gateway 有运行时 bug）。

版本渠道

渠道	npm dist-tag	说明
stable	latest	稳定版
beta	beta	测试版（可能与 latest 相同）
dev	dev	main 分支最新

openclaw update --channel stable|beta|dev

认证与订阅

是否需要 Claude 或 OpenAI 订阅？ 不需要。可以使用 API Key 或本地模型。

支持的认证方式：

• Anthropic API Key（推荐生产环境）
• Claude CLI / Claude 订阅认证（Anthropic 已允许此用法）
• OpenAI Codex OAuth（OpenAI 明确支持外部工具使用）
• 其他：Qwen Cloud、MiniMax、Z.AI 等订阅式选项

常见问题

Heartbeat 一直跳过？ 常见原因：

• quiet-hours：在配置的活跃时间窗口之外
• empty-heartbeat-file：HEARTBEAT.md 只有空行/标题
• no-tasks-due：任务模式下没有到期任务

onboarding 卡住（“Wake up my friend”）？

openclaw gateway restart
openclaw status && openclaw models status && openclaw logs --follow
openclaw doctor

迁移到新机器？

1. 安装 OpenClaw
2. 复制 ~/.openclaw（状态目录）
3. 复制工作区（默认 ~/.openclaw/workspace）
4. 运行 openclaw doctor 并重启 Gateway 服务

VPS 最低配置： 1 vCPU、1GB RAM、500MB 磁盘；推荐 2GB RAM。

Raspberry Pi 支持？ 支持，使用 64 位 OS，Node >= 22，推荐 hackable git 安装。

相关链接

• help-troubleshooting — 故障排查
• help-faq-models — 模型与认证 FAQ