配置放家外
~/.openclaw/openclaw.json 像你的私人收纳盒，别塞进仓库里。这样你更新代码的时候，不会顺手把自己的习惯一起冲掉。
Start 导读
安装前先搞清两件事：配置放哪里、Gateway 怎么跑
你的个性化配置（skills、prompts）必须放在 `~/.openclaw/workspace`，全局配置在 `~/.openclaw/openclaw.json`，这样更新代码才不会覆盖你的定制。初次跑 `openclaw setup` 一键初始化；想自己控制 Gateway 就用 `pnpm gateway:watch` 启动，macOS 应用切到 Local 模式连它。
先讲这一页到底在解决什么
安装前先搞清两件事：配置放哪里、Gateway 怎么跑
你的个性化配置（skills、prompts）必须放在 `~/.openclaw/workspace`，全局配置在 `~/.openclaw/openclaw.json`，这样更新代码才不会覆盖你的定制。初次跑 `openclaw setup` 一键初始化；想自己控制 Gateway 就用 `pnpm gateway:watch` 启动，macOS 应用切到 Local 模式连它。
第一步
🧳 开家门前，先记住两件最要紧的事
官方一开头就把边界讲得很清楚：有些东西放在仓库外面，有些东西放在家里门口。这样以后改起来不会互相踩脚。
工作区也放家外
~/.openclaw/workspace 像助理自己的小房间，里面放技能、提示词、记忆。它最好是你自己的私有小仓库。
不要把“你的东西”塞回主仓库
官方特地提醒：个人配置、工作区和代码仓库最好分开。这样升级时，房子不会把你的家具一起搬丢。
一句话
先把家和行李分开，后面改起来才不会乱。
门槛
🔧 这页先告诉你，开门前要带哪几样工具
不是很多，但每样都很实在。少一样，后面就会卡。
🟢 Node
像发动机。官方推荐 Node 24，Node 22.14 以上也还能开。没有发动机，车就不会走。
📦 pnpm
像一只靠谱的小搬运车。它把依赖和脚本一件件拉进来。
🐳 Docker
它是可选工具。只有你想走容器化路线，或者要做某些测试时，才需要把它搬上来。
🔑 凭证
这页虽然不是专讲钥匙，但它默认你后面会接模型和通道，所以钥匙和登录最终都躲不开。
先搭骨架
🛠 openclaw setup 像“一键把抽屉架搭好”
这是整页最像“开荒”的那一步。它不替你决定一切，但会把最容易漏掉的骨架先立住。
openclaw setup像叫来一位收纳老师，把助理的大抽屉、小抽屉、身份卡和工具格先排好。
为什么先跑它
因为它会把“该有的基础结构”先放稳，后面你再接聊天通道、模型、技能时，就不会从空地开始搭。
从仓库里跑一次也行
如果你还没全局安装，也可以用 pnpm openclaw setup。意思就是先借搬运车，把这位老师请进来干活。
🎈 记一句
Setup 的任务不是炫技，是先把能住人的骨架搭好。
两种住法
🏠 官方其实给了你两条很清楚的路
一条稳，一条新。两条都能走，但它们的性格不一样。
macOS app + bundled Gateway
像住进官方替你打包好的大屋子。门窗、电线、值班表都先给你配齐了，最省心。
自己跑 Gateway
像你亲自接管总机房。自由度更高，也更适合开发和调试。
Stable workflow
先装 macOS app，再让它带着 bundled Gateway 跑。这是最像“拿来就住”的方式。
Bleeding edge workflow
你自己在终端里跑 Gateway，app 只是贴上来。更像自己修房子，动得也更深。
稳定路线
📱 稳定路线像“先把门牌挂好，再让 app 帮你守门”
官方这条路很实用，适合第一次真正上手。
1. 装并打开 OpenClaw.app
像把现成的门卫房打开。菜单栏里那个小入口，是它的前台。
2. 走完 onboarding 和权限
像让老师带你去把所有需要的钥匙和许可都签好。TCC 提示出现时，别慌，那是在让系统知道你真的同意它去做事。
3. 确认 Gateway 是 Local
像确认总机房就在家里， app 正在接管它的值班。
4. 登录通道，再检查健康
openclaw channels login 像去门口扫一次通行证，openclaw health 像摸摸门卫额头，看看它是不是精神。
命令翻译
🛠 这几个命令，在现场到底像什么动作？
不要把它们当成口令，想成动作会更顺。
openclaw setup
像把抽屉架先搭好，告诉系统“我准备住进来了”。
openclaw channels login
像给助理去门口领一张正式通行证，让它开始连聊天通道。
openclaw health
像对着房子做一次体检，看看有没有哪盏灯没亮。
node openclaw.mjs gateway --port 18789 --verbose
像自己在终端里把总机房叫醒，还特地打开“多说几句”模式，好观察它每一步在做什么。
开发路线
🧪 Bleeding edge 像“自己站到机房里修电路”
这条路更自由，也更像开发者的工作方式。
pnpm install像先把所有零件搬进来，免得你修到一半发现少了一颗螺丝。
pnpm gateway:watch像让总机房装上眼睛。代码、配置、插件元数据一变，它就会自己刷新。
./scripts/restart-mac.sh像把 macOS app 也拉进同一条新鲜轨道上，方便一起追最新代码。
✅ 验证方式
app 里看到 “Using existing gateway …”，或者跑 openclaw health。这说明它真的连上了你手里的那台总机房。
常见坑
⚠️ 这页最后那几条提醒，都是在帮你少踩坑
看起来像小字，实际都是血泪提醒。
端口要一致
app 和 CLI 如果盯着不同门牌号，就像你站在 18789 门口，而门卫却在 18790 值班。
状态放哪要分清
凭证、会话、日志各自有家。知道它们住哪，排查问题才不乱翻。
Linux 要考虑 lingering
不然你一登出，系统就把守门人叫走了。官方这句是在提醒：别让值班服务下班太早。
更新时别把“你的东西”带坏
仓库更新了，别把家里的收纳盒也一起打翻。官方反复强调的就是这件事。
最后总结
🎈 把这页压成一句最好记的话
Setup 就是在教你怎么把 OpenClaw 安稳地安进家里：配置和工作区放家外，先搭骨架，再选稳定住法或开发住法，最后让它真正开始值班。
如果你下一页只想继续看一页，我建议先看 /start/docs-directory。因为家已经搭好了，下一步最需要的就是找路图。