FAQ: first-run setup | Fivey Can Read OpenClaw

先讲这一页到底在解决什么

FAQ: first-run setup：第一次启动卡住时的急救盒

这页把第一次安装、dashboard 打不开、Gateway 认证、wake up my friend 没回应、Raspberry Pi 和换新机器等常见问题压成可执行检查。先看 openclaw status、openclaw models status、openclaw doctor 和 logs，再小步修复。

原文共 3 节，先看 Start Here 路径：/help/faq-first-run 查看官方原文

第一站

🩺 卡住的前一分钟，先做三次小体检

官方反复让你分享这些输出，因为很多问题其实是本机环境、权限、服务或认证没接好。

openclaw status

像看仪表盘：Gateway 和 agent 有没有活着，基本配置是不是看起来正常。

openclaw models status

像检查电话卡：模型 provider 有没有登录、模型能不能用。

openclaw doctor

像请医生来修常见小毛病，配置、状态、迁移细节都能帮你查一遍。

openclaw logs --follow

像盯着机器说话的纸带。求助时带上日志，别人才能知道它在哪一步摔倒。

第二站

🧑‍🏫 最快求助方式，是让能看本机的 AI 助手当陪跑老师

远处的人常常看不到你的 PATH、服务、权限和 auth 文件；本地助手能读代码、跑命令、看日志。

适合的助手

Claude Code 或 OpenAI Codex 这类能操作本地 repo 的工具，更适合排查“我这台机器为什么不行”。

--install-method git

用 git checkout 安装时，助手能看到完整源码和文档，判断会更准。

怎么请它帮忙

让它先计划并监督修复，再只执行必要命令。这样改动小，也更容易回头检查。

真的发现 bug

如果最后确认是 OpenClaw 自己的问题，就去 GitHub issue 或 PR 留下线索，帮助后面的人少踩坑。

第三站

🚪 Dashboard 打不开时，先分清“本机门”和“远程门”

同一台机器访问和远程访问，认证方式不一样。混起来最容易迷路。

🏠

本机 localhost

打开 http://127.0.0.1:18789/。如果要求 shared secret，就粘贴 token 或 password。

🔑

没有 token

用 openclaw doctor --generate-gateway-token 生成，或检查 gateway.auth.token / 环境变量。

🛣️

远程访问

优先 Tailscale Serve、SSH tunnel 或可信反向代理。远程时共享密钥和身份头要按模式配对。

📍

看准 Gateway

UI 必须指向真正运行 Gateway 的机器。远程模式里，session 和 workspace 在 Gateway 主机上。

第四站

🥚 “wake up my friend” 没回音，多半是 agent 没真正跑起来

这不是一句神秘咒语，它只是第一次 hatch 时发出的测试消息。

openclaw gateway restart

先让 Gateway 重新站好。

openclaw status / openclaw models status

再看服务和模型认证是不是都在线。tokens 一直是 0，通常说明 agent 根本没开始回复。

openclaw logs --follow

边重试边看日志，能看到卡在认证、模型、网络还是权限。

openclaw doctor

如果还不行，让 doctor 做一次完整检查。

第五站

📦 换新机器时，别只搬 workspace，也要搬状态目录

这条和迁移页互相呼应：workspace 像书桌，state dir 像抽屉和钥匙盒。

要搬两样

$OPENCLAW_STATE_DIR 默认是 ~/.openclaw；workspace 默认在 ~/.openclaw/workspace。两边都要看。

GitHub 备份不够

只提交 workspace 只保住记忆和引导文件，不会保住 session history 或 auth。

openclaw doctor

搬到新机器后跑一次 doctor，再重启 Gateway。

小机器也能跑

Raspberry Pi 4 可以跑 Gateway；Node 要 >= 22，64-bit OS 更稳，先少开插件和通道。

最后记住

🎈 第一次启动卡住时，不要乱改一大片，先拿诊断结果说话

最可靠的小路线是：status、models status、doctor、logs。看清楚哪里红了，再动手修哪里。