夜雨聆风
OpenClaw-Onboard引导与配置全解
本节目标:把
openclaw onboard这个魔法盒子打开,搞清楚它生成的openclaw.json每个字段是干啥的。读完你就脱离向导,手动改任何配置——这是从”按钮用户”升级到”配置玩家”的关键一步。
一、为什么要懂配置文件
onboard 像一个开盒按钮——按一下,所有东西帮你装好。但它有三个限制:
-
1. 它问的问题有限——很多高级配置(沙箱细节、Skill 策略、模型路由)它不问 -
2. 改配置每次都重跑向导?太累——比如想换个 API Key,要重新走一遍 -
3. 没法版本控制——团队/多机器同步配置全靠手动复制
懂 openclaw.json 之后:
你能干的事 ❌ 不懂配置时 ✅ 懂配置后───────────── ─────────────── ───────────────换个模型 重跑 onboard 改一行加个工作空间 重跑 onboard 写 5 行 JSON迁到新机器 重新装一遍 scp 一个文件团队共享配置 没法 git 提交配置临时禁用一个 Skill UI 点击或重跑 改一个字段二、Onboard 到底做了什么
让我们解剖这个命令:
openclaw onboard它干了 6 件事:
┌───────────────────────────────────────────────┐│ 1. 检测系统(macOS/Linux/Windows、Node 版本) ││ 2. 让你选模型 + 输 API Key ││ 3. 启动并(可选)装为 daemon 系统服务 ││ 4. 创建第一个 Workspace ││ 5. 引导你绑第一个 Channel ││ 6. 把以上全部写入 ~/.openclaw/openclaw.json │└───────────────────────────────────────────────┘第 6 步是关键——所有的引导结果最终落到一个 JSON 文件。
三、openclaw.json 在哪儿
macOS / Linux: ~/.openclaw/openclaw.jsonWindows (WSL2): ~/.openclaw/openclaw.json (在 Linux 子系统里)Windows (原生): %USERPROFILE%\.openclaw\openclaw.jsonDocker: /data/openclaw.json (你挂载的卷里)# 看一眼cat ~/.openclaw/openclaw.json | head -50四、openclaw.json 全字段拆解
下面是一个完整示例(标注每个字段的作用):
{ // ─── 1. 顶层元数据 ─── "version": "2026.4.14", // 配置文件 schema 版本,自动写入 "instance_id": "ic_8f3a...", // 这台 OpenClaw 实例的唯一 ID // ─── 2. Gateway 网关配置 ─── "gateway": { "host": "127.0.0.1", // 监听地址。改 0.0.0.0 才能远程访问 "port": 7777, // 端口 "daemon":true, // 是否作为系统服务运行 "log_level": "info", // debug / info / warn / error "data_dir": "~/.openclaw/data", // 数据目录(SQLite 库、缓存等) "rpc": { "auth_required":true, // 远程调用是否需鉴权 "tokens": ["rpc_xxxxxx"] // RPC 访问 Token 列表 } }, // ─── 3. 模型配置 ─── "providers": { "anthropic": { "api_key": "sk-ant-xxxxxx", // ⚠️ 别推到 git "base_url": "https://api.anthropic.com", "models": ["claude-sonnet-4-6", "claude-opus-4-7", "claude-haiku-4-5"] }, "openai": { "api_key": "sk-xxxxxx", "base_url": "https://api.openai.com/v1" }, "moonshot": { "api_key": "sk-xxxxxx", "base_url": "https://api.moonshot.cn/v1", "models": ["kimi-k2.5", "kimi-k2"] } }, // ─── 4. Workspaces 工作空间 ─── "workspaces": { "personal": { "description": "个人助理", "model": { "provider": "anthropic", "name": "claude-sonnet-4-6", "temperature": 0.7, "max_tokens": 4096 }, "system_prompt": "你是 Molty,一只生活在用户电脑里的友善 AI 助手……", "memory": { "scope": "channel", // channel / workspace / global "ttl_days": 30, // 短期记忆保留天数 "long_term_max": 1000 // 长期记忆条目上限 }, "skills": { "filesystem": { "policy": "approve" }, "shell": { "policy": "approve" }, "http": { "policy": "trust" }, "web": { "policy": "trust" }, "memory": { "policy": "trust" }, "cron": { "policy": "approve" } }, "channels": ["telegram-personal", "whatsapp-personal"], "sandbox": { "type": "docker", // docker / ssh / openshell / none "image": "openclaw/sandbox:latest", "timeout_seconds": 300, "memory_limit_mb": 512, "cpu_quota": "1.0", "network": "restricted" // restricted / open / none } }, "coder": { "description": "编程助手", "model": { "provider": "anthropic", "name": "claude-opus-4-7", "temperature": 0.2, "max_tokens": 8192 }, "system_prompt": "你是一个资深工程师助手……", "memory": { "scope": "workspace", "ttl_days": 90 }, "skills": { "filesystem": { "policy": "approve" }, "shell": { "policy": "approve" }, "git": { "policy": "trust" }, "github": { "policy": "approve" }, "docker": { "policy": "approve" } }, "channels": ["slack-team", "webchat"], "sandbox": { "type": "docker", "image": "openclaw/sandbox-coder:latest", "mounts": [ { "source": "~/code", "target": "/workspace", "readonly":false } ] } } }, // ─── 5. Channels 渠道 ─── "channels": { "telegram-personal": { "type": "telegram", "bot_token": "1234567890:AAH-xxxxxx", "allowed_user_ids": [87654321, 12345678], "default_workspace": "personal" }, "whatsapp-personal": { "type": "whatsapp", "auth_method": "qr", "session_path": "~/.openclaw/wa-session", "allowed_phones": ["+1xxxxxxxxxx"], "default_workspace": "personal" }, "slack-team": { "type": "slack", "bot_token": "xoxb-xxxxxxxx", "app_token": "xapp-xxxxxxxx", "allowed_user_ids": ["U12345678"], "default_workspace": "coder" }, "webchat": { "type": "webchat", "url_prefix": "/chat", "auth": "basic", "username": "you", "password_hash": "$2b$10$xxxxxxxx", "default_workspace": "coder" } }, // ─── 6. Cron 任务 ─── "cron": { "tasks": [ { "id": "crn_001", "name": "water-and-sleep", "schedule": "0 23 * * *", // cron 表达式 "workspace": "personal", "channel": "telegram-personal", "prompt": "现在 23 点了,提醒用户喝水睡觉。", "enabled":true } ] }, // ─── 7. 全局选项 ─── "global": { "default_workspace": "personal", "default_channel": "telegram-personal", "telemetry":false, // 不向官方上报使用数据 "auto_update": "stable", // stable / beta / dev / off "notifications": { "approval_pending": "desktop", // 桌面 / 邮件 / 自家渠道 "errors": "telegram-personal" } }}五、核心字段深挖
5.1 model 部分
"model": { "provider": "anthropic", "name": "claude-sonnet-4-6", "temperature": 0.7, "max_tokens": 4096}|
|
|
|
|---|---|---|
provider |
providers 里的 key) |
anthropic
|
name |
|
|
temperature |
|
|
max_tokens |
|
|
模型选型速查:
┌──────────────────────┬─────────────────────────┐│ 场景 │ 推荐模型 │├──────────────────────┼─────────────────────────┤│ 日常助理 │ claude-sonnet-4-6 ││ 深度思考 / 写代码 │ claude-opus-4-7 ││ 量大、便宜、快 │ claude-haiku-4-5 ││ 国内、长上下文 │ kimi-k2.5 ││ 国内、最便宜 │ deepseek-chat ││ 完全本地、隐私敏感 │ ollama/qwen2.5:32b │└──────────────────────┴─────────────────────────┘5.2 memory 部分
"memory": { "scope": "channel", "ttl_days": 30, "long_term_max": 1000}scope 是关键:
channel │ 每个渠道独立记忆(默认) │ 你 Telegram 跟 Slack 互不知道 │workspace │ 同一个工作空间下所有渠道共享 │ 适合"个人统一助理" │global │ 所有工作空间所有渠道共享 │ 一般不推荐,容易串味5.3 skills 部分
"skills": { "filesystem": { "policy": "approve" }, "filesystem.read": { "policy": "trust" }, // 子动作覆盖 "filesystem.delete": { "policy": "approve" }}policy 的三种值:
approve │ 每次执行前发批准请求(Telegram 推一条按钮)trust │ 自动执行,事后通知block │ 完全禁止执行子动作可以覆盖:filesystem 整体设 trust,但 filesystem.delete 单独设 approve。
5.4 sandbox 部分
"sandbox": { "type": "docker", "image": "openclaw/sandbox:latest", "timeout_seconds": 300, "memory_limit_mb": 512, "cpu_quota": "1.0", "network": "restricted", "mounts": [ { "source": "~/code", "target": "/workspace", "readonly":false } ]}type: docker │ 最强隔离,要装 Docker ssh │ 在另一台机器跑(用户名/host 配在另一处) openshell │ 用户态隔离,起得快但弱 none │ ❌ 不要选,Skill 直接在主系统跑network: open │ 完全联网 restricted │ 只允许白名单域名 none │ 完全离线六、改配置的常见场景
场景 1:换 API Key
❌ 重跑 onboard。
✅ 直接改:
$EDITOR ~/.openclaw/openclaw.json# 找到 providers.anthropic.api_key, 改掉openclaw daemon restart或:
openclaw config set providers.anthropic.api_key "sk-ant-newkey"场景 2:同时支持 Claude 和 Kimi(灵活切换)
加一段:
"providers": { "anthropic": { "api_key": "sk-ant-..." }, "moonshot": { "api_key": "sk-...", "base_url": "https://api.moonshot.cn/v1" }}然后给某个 Workspace 用 Kimi:
"workspaces": { "family": { "model": { "provider": "moonshot", "name": "kimi-k2.5" } }}场景 3:把 Gateway 暴露到公网(谨慎)
"gateway": { "host": "0.0.0.0", // 监听所有网卡 "port": 7777, "rpc": { "auth_required":true, // ⚠️ 绝对要 true "tokens": ["rpc_xxxxx"] }}至少同时要做:防火墙限 IP、用 Cloudflare Tunnel / Tailscale,而不是裸暴露(详见主线 4)。
场景 4:临时禁用某个 Channel
不想删,只是暂时不用:
"channels": { "slack-team": { "type": "slack", "enabled":false, // 加这一行 ... }}或:
openclaw channel disable slack-team场景 5:多机同步配置
最佳实践:配置和秘密分离。
~/.openclaw/openclaw.json ← 配置主体,可放 git~/.openclaw/secrets.env ← API Key 等秘密,只本地openclaw.json 用 ${ENV_VAR} 占位:
"providers": { "anthropic": { "api_key": "${ANTHROPIC_API_KEY}" }}secrets.env:
ANTHROPIC_API_KEY=sk-ant-xxxxTELEGRAM_BOT_TOKEN=12345:AAH-xxxxopenclaw daemon 启动前 source 一下 secrets.env,或者写到 systemd unit / launchd plist 的 EnvironmentFile。
这样:
git add openclaw.json ✅ 安全git add secrets.env ❌ 千万别echo "secrets.env" >> .gitignore七、配置版本管理
把 openclaw.json 提交到一个私有 git 仓库:
cd ~/.openclawgit initgit add openclaw.jsonecho "secrets.env" > .gitignoreecho "data/" >> .gitignore # 别提交数据echo "*.session" >> .gitignore # 别提交 WhatsApp 会话git commit -m "init"好处:
-
• 你改坏了能回滚 -
• 多机用同一份配置 -
• 看 diff 知道你改了啥
🦞 强烈建议:每次大改前先 commit 一次。OpenClaw 自身没有”配置回滚”,git 是你最后的安全网。
八、命令行 vs 直接改文件 vs Web UI
┌───────────────┬────────────┬────────────────────┐│ 方式 │ 优点 │ 缺点 │├───────────────┼────────────┼────────────────────┤│openclaw config│ 安全、自带 │ 复杂结构没法改 ││ set/get │ 校验 │ │├───────────────┼────────────┼────────────────────┤│ 直接改 json │ 灵活,看 diff│ 容易写错,要懂结构 │├───────────────┼────────────┼────────────────────┤│ Web 控制台 │ 友好、可视化 │ 不支持所有字段 │└───────────────┴────────────┴────────────────────┘推荐组合:
-
• 日常小改 → CLI -
• 大动结构(加 Workspace、Sandbox)→ 直接改 JSON -
• 看运行状态 → Web UI
九、改完配置后,什么时候要重启?
不同字段对重启的要求不一样:
不需要重启(改了立刻生效): cron.tasks workspaces.*.system_prompt workspaces.*.memory.long_term_max channels.*.allowed_user_ids需要重启 daemon: gateway.* providers.* workspaces.*.model sandbox.*需要 channel reload: channels.* (除 allowed_user_ids 外)# 通用做法openclaw daemon reload # 软重载,不断连接openclaw daemon restart # 硬重启,所有连接重连十、本课知识地图
┌────────────────────────────────────────────────┐│ 第 03 课·配置全解 知识地图 ││ ││ 路径: ││ ~/.openclaw/openclaw.json (主配置) ││ ~/.openclaw/secrets.env (秘密,不进 git) ││ ││ 七大顶层字段: ││ 1. version + instance_id ││ 2. gateway (host/port/daemon) ││ 3. providers (各家 API Key) ││ 4. workspaces (脑子 + 提示词 + 技能) ││ 5. channels (嘴和耳朵) ││ 6. cron (定时任务) ││ 7. global (默认值 / telemetry) ││ ││ 三种配置方式: ││ ├── openclaw config set/get(日常小改) ││ ├── 直接改 JSON(大改) ││ └── Web UI(可视化、查状态) ││ ││ 改完的处理: ││ 立刻生效 / daemon reload / daemon restart ││ ││ 最佳实践: ││ ├── 配置和秘密分离 ││ ├── 用 git 管理配置 ││ ├── 大改前先 commit ││ └── 千万别把 secrets 推到公开仓库 │└────────────────────────────────────────────────┘十一、扩展学习资源
必读
-
• OpenClaw 官方·配置参考[1] — 字段权威定义 -
• 本教程·附录·配置文件参考[2] — 字段速查表 -
• 本教程·第 13 课·沙箱与安全[3] — sandbox 字段深挖
推荐
-
• Apifox·配置图文[4] — 截图详细 -
• awesome-openclaw-tutorial · 配置实战[5]
动手实践
-
• 把你的 openclaw.json提交到一个私有 git 仓库 -
• 把 API Key 抽到 secrets.env,跑通 ${ENV_VAR}替换 -
• 创建第二个 Workspace,用不同模型 + 不同 system prompt -
• 改一次 sandbox.network 为 restricted,试试 web skill 还能不能爬
下一篇章预告:[渠道接入] — 微信、QQ、钉钉、企业微信、飞书五个国内主战场,每个的合规注意事项和实操步骤。
引用链接
[1] OpenClaw 官方·配置参考: https://docs.openclaw.ai/zh-CN[2] 本教程·附录·配置文件参考: ../附录/配置文件参考.md[3] 本教程·第 13 课·沙箱与安全: ./13-沙箱与安全.md[4] Apifox·配置图文: https://apifox.com/apiskills/openclaw-installation-and-usage-guide/[5] awesome-openclaw-tutorial · 配置实战: https://github.com/xianyu110/awesome-openclaw-tutorial