夜雨聆风
openclaw onboard初始化操作，成功部署 OpenClaw 基础服务键值对结构：必须遵循 "key": value格式， 键名必须用双引号 （不能用单引号），冒号后面需加空格，区分键和值；
数据类型：支持5种常用类型——字符串（需用双引号包裹）、数字（直接写，无需引号）、布尔值（true/false，小写，无引号）、数组（用 [] 包裹，元素用逗号分隔）、对象（用 {} 包裹，内部是键值对）；
格式规范：多个键值对/元素之间用逗号分隔， 最后一个元素不能加逗号 （否则会报语法错误），缩进建议用2个空格（适配公众号代码显示，避免错乱）。
{ "name": "OpenClaw", // 字符串类型：服务名称 "version": "2026.3.13", // 字符串类型：OpenClaw 版本 "enabled": true, // 布尔值类型：是否启用该服务（true=启用，false=禁用） "port": 18789, // 数字类型：监听端口 "features": ["agent", "tools", "plugins"] // 数组类型：启用的功能模块}
数据类型 | 格式要求 | 示例 | 适用场景 |
|---|---|---|---|
字符串 | 双引号包裹 |
| 地址、名称、密钥等文本信息 |
数字 | 无引号，直接填写 |
| 端口、数量、大小等数值信息 |
布尔值 | 小写 true/false，无引号 |
| 功能启用/禁用、开关控制 |
数组 | [] 包裹，元素用逗号分隔 |
| 多个同类型值的集合（如模型列表） |
对象 | {} 包裹，内部是键值对 |
| 复杂配置（如认证、模型、渠道配置） |
{ "meta": {}, // 版本信息（系统自动生成和维护，无需手动修改） "wizard": {}, // 向导运行记录（初始化时自动生成，记录配置过程，无需修改） "auth": {}, // 认证配置（存储模型提供商、平台的API Key等认证信息，重点） "models": {}, // 模型提供商和默认模型配置（决定Agent用哪个模型运行，核心重点） "agents": {}, // Agent 核心配置（工作区路径、默认模型、会话优化等，核心重点） "tools": {}, // 工具配置（控制Agent可使用的工具，如网页搜索、命令执行，重点） "commands": {}, // 斜杠命令配置（控制 /reset、/help 等命令的启用状态） "session": {}, // 会话管理配置（会话生命周期、超时时间、重置规则等） "hooks": {}, // 钩子配置（自动化触发器，如定时执行任务、事件触发操作） "channels": {}, // 通道配置（对接飞书、企业微信等平台，重点） "gateway": {}, // 网关设置（监听端口、访问权限、认证令牌等，核心重点） "skills": {}, // 技能配置（可插拔技能，如搜索、日历、翻译等） "plugins": {}, // 插件配置（扩展OpenClaw功能，如自定义工具、模板等） "env": {}, // 环境变量配置（安全存储敏感信息，进阶配置） "messages": {}, // 消息行为配置（回复前缀、消息队列、ACK反应等） "bindings": {}, // 多Agent路由配置（一个网关管理多个Agent，团队适用） "logging": {} // 日志配置（日志级别、输出路径，方便排查故障）}
{ "meta": { "lastTouchedVersion": "2026.3.13", // 最后修改的OpenClaw版本 "lastTouchedAt": "2026-03-18T14:11:59.484Z" // 最后修改时间（自动生成） }, "auth": { "profiles": { "zai:default": { "provider": "zai", // 模型提供商（这里是智谱AI） "mode": "api_key" // 认证方式（api_key 方式，最常用） }, "openrouter:default": { "provider": "openrouter", // 另一模型提供商（OpenRouter） "mode": "api_key" // 认证方式 } } }, "models": { "mode": "merge", // 模型加载模式（merge=合并内置和自定义模型，默认推荐） "providers": { "zai": { "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", // 智谱API地址（固定） "api": "openai-completions", // API兼容类型（适配OpenAI格式） "models": [{"id": "glm-5", "name": "GLM-5", "reasoning": true}] // 可用模型列表 } } }, "agents": { "defaults": { "model": {"primary": "zai/glm-5"}, // Agent默认使用的主模型（格式：提供商/模型ID） "workspace": "~/.openclaw/workspace" // Agent工作区路径（存储会话、日志等，默认即可） } }, "channels": { "feishu": { "enabled": true, // 启用飞书渠道（true=启用，false=禁用） "appId": "cli_xxxxxxxxxx", // 飞书开发者平台获取的App ID "appSecret": "xxxxxxxxxxxxxxxxxxxxxx", // 飞书开发者平台获取的App Secret "connectionMode": "websocket" // 连接方式（websocket=长连接，推荐，实时接收消息） } }, "gateway": { "port": 18789, // 网关监听端口（默认18789，可修改，避免端口冲突） "mode": "local", // 运行模式（local=本地运行，适合个人使用） "bind": "loopback" // 访问权限（loopback=仅本机可访问，安全） }}
配置字段 | 核心用途 | 是否需要手动修改 | 新手优先级 |
|---|---|---|---|
| 记录版本和修改时间 | 否（自动生成） | 低 |
| 存储API Key等认证信息 | 是（需配置对应提供商） | 高 |
| 配置模型提供商和可用模型 | 是（核心配置） | 最高 |
| 设置Agent默认行为 | 是（至少修改默认模型） | 最高 |
| 控制Agent可用工具 | 按需修改 | 中 |
| 对接飞书等外部平台 | 按需修改（不用则不改） | 中 |
| 配置网关端口和访问权限 | 按需修改（默认即可） | 中 |
| 安全存储敏感信息 | 进阶修改（新手可后期优化） | 低 |
{ "meta": { "lastTouchedVersion": "2026.3.13", // 最后修改对应的OpenClaw版本 "lastTouchedAt": "2026-03-18T14:11:59.484Z" // 最后修改时间（UTC时间，自动生成） }}
子字段 | 含义 | 是否可修改 |
|---|---|---|
| 最后修改配置时使用的OpenClaw版本 | 否 |
| 配置文件最后修改的时间（UTC格式） | 否 |
{ "auth": { "profiles": { // 智谱AI 认证配置（示例） "zai:default": {"provider": "zai", "mode": "api_key", "apiKey": "${ZAI_API_KEY}"}, // OpenRouter 认证配置（示例） "openrouter:default": {"provider": "openrouter", "mode": "api_key", "apiKey": "${OPENROUTER_API_KEY}"} } }}
子字段 | 含义 | 可选值/格式 | 注意事项 |
|---|---|---|---|
| 存储所有认证配置的集合 | 对象（{}） | 每个认证配置对应一个子对象，键名格式为「提供商:别名」 |
| 认证对应的提供商名称 | zai、openrouter 等 | 必须与 models 字段中的提供商名称一致 |
| 认证方式 | api_key（最常用） | 目前主流认证方式，其他方式暂不推荐新手使用 |
| 提供商的API Key | 字符串，推荐用环境变量引用 | 严禁明文填写，避免泄露 |
{ "models": { "mode": "merge", // 模型加载模式（merge=合并内置和自定义模型，默认推荐） "providers": { // 智谱AI 提供商配置（示例） "zai": { "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", // 智谱API地址（固定不变） "api": "openai-completions", // API兼容类型（适配OpenAI格式，无需修改） "models": [ { "id": "glm-5", // 模型ID（唯一标识，引用时用「提供商/模型ID」，如 zai/glm-5） "name": "GLM-5", // 模型名称（自定义，方便识别） "contextWindow": 204800, // 上下文窗口大小（单位：token，越大支持长对话越强） "maxTokens": 131072, // 单次最大输出token数（控制单次回复长度） "reasoning": true // 是否启用推理能力（true=启用，推荐开启） } ] } } }}
子字段 | 含义 | 可选值/默认值 | 新手建议 |
|---|---|---|---|
| 模型加载模式 | merge（默认）、custom（仅自定义模型） | 保持默认 merge 即可，无需修改 |
| 模型提供商集合 | 对象（{}） | 每个提供商对应一个子对象，键名是提供商名称（如 zai） |
| 提供商的API地址 | 不同提供商地址不同（固定） | 按提供商官方文档填写，不要随意修改 |
| API兼容类型 | openai-completions（默认） | 保持默认即可，适配大部分提供商 |
| 该提供商下的可用模型列表 | 数组（[]），每个元素是模型对象 | 只添加自己需要的模型，避免冗余 |
model.primary{"agents": {"defaults": {"model": {"primary": "zai/glm-5", // 主模型（格式：提供商/模型ID，必须与models字段中的模型ID一致）"fallbacks": ["openrouter/xiaomi/mimo-v2-pro"] // 备用模型（主模型故障时自动切换）},"workspace": "~/.openclaw/workspace", // Agent工作区路径（存储会话、日志、临时文件等）"compaction": {"mode": "safeguard"}, // 长对话优化模式（safeguard=安全模式，默认推荐）"heartbeat": 300 // 心跳检测时间（单位：秒，300=5分钟，用于检测Agent运行状态）}}}
子字段 | 含义 | 默认值/可选值 | 新手建议 |
|---|---|---|---|
| 所有Agent的默认配置 | 对象（{}） | 新手只修改 model.primary 即可 |
| Agent默认使用的主模型 | 格式：提供商/模型ID | 必须与 models 字段中的模型配置一致，否则会报错 |
| 备用模型列表 | 数组（[]），格式同主模型 | 按需添加，没有备用模型可删除该字段 |
| Agent工作区路径 | ~/.openclaw/workspace（默认） | 保持默认即可，修改后需手动创建对应文件夹 |
profile: "full"{"tools": {"profile": "full", // 工具预设模板（full=启用全部工具，新手推荐；basic=仅启用基础工具）"deny": ["browser", "canvas"], // 禁止使用的工具名单（数组形式，填写工具ID）"allow": [], // 允许使用的工具名单（优先级高于deny，空数组表示允许所有未被禁止的工具）"web": {"search": {"enabled": true}, // 启用网页搜索工具（true=启用，false=禁用）"timeout": 10 // 网页搜索超时时间（单位：秒，默认10秒）}}}
子字段 | 含义 | 可选值/默认值 | 新手建议 |
|---|---|---|---|
| 工具预设模板 | full（默认）、basic | 新手保持 full 即可，无需修改 |
| 禁止使用的工具名单 | 数组（[]），如 ["browser", "canvas"] | 不需要禁止工具时，可删除该字段 |
| 是否启用网页搜索工具 | true（默认）、false | 建议启用，方便Agent获取实时信息 |
{ "channels": { "feishu": { // 渠道名称（飞书，固定为feishu） "enabled": true, // 启用飞书渠道（true=启用，false=禁用） "appId": "cli_xxxxxxxxxx", // 飞书开发者平台获取的App ID（必填） "appSecret": "xxxxxxxxxxxxxxxxxxxxxx", // 飞书开发者平台获取的App Secret（必填） "connectionMode": "websocket", // 连接方式（websocket=长连接，推荐；webhook=回调方式） "streaming": true, // 消息流式输出（true=实时分段回复，false=一次性回复） "timeout": 30 // 消息响应超时时间（单位：秒，默认30秒） } }}
子字段 | 含义 | 必填/可选 | 获取方式 |
|---|---|---|---|
| 是否启用该渠道 | 必填 | 手动设置 true/false |
| 飞书应用的唯一标识 | 必填 | 飞书开发者平台 → 应用管理 → 应用详情中获取 |
| 飞书应用的密钥 | 必填 | 同 appId 获取路径，注意保密 |
| 消息连接方式 | 必填 | 新手推荐 websocket（长连接，实时性强） |
openclaw gateway restart），新手建议保持默认配置，避免端口冲突。
{ "gateway": { "port": 18789, // 网关监听端口（默认18789，可修改，需避免与其他服务端口冲突） "mode": "local", // 运行模式（local=本地运行，public=公网可访问） "bind": "loopback", // 绑定地址（loopback=仅本机可访问，0.0.0.0=所有地址可访问） "auth": { "mode": "token", // 认证方式（token=令牌认证，none=无认证） "token": "${GATEWAY_TOKEN}" // 认证令牌（推荐用环境变量引用，避免明文） }, "timeout": 60 // 网关请求超时时间（单位：秒，默认60秒） }}
子字段 | 含义 | 默认值/可选值 | 注意事项 |
|---|---|---|---|
| 网关监听端口 | 18789（默认） | 修改后需确保该端口未被其他服务占用 |
| 运行模式 | local（默认）、public | 个人使用保持 local 即可，公网访问需配置安全策略 |
| 绑定地址 | loopback（默认）、0.0.0.0 | loopback 更安全，仅本机可访问网关 |
| 网关认证令牌 | 字符串，推荐用环境变量引用 | 开启 token 认证后，访问网关需携带该令牌 |
commands：控制斜杠命令（如/reset重置会话、/help查看帮助）的启用状态，默认全部启用，无需修改；
session：管理会话生命周期，可设置会话超时时间、每天定时重置会话等，默认配置即可满足日常使用；
plugins：配置扩展插件，如自定义工具、消息模板等，新手可先不配置，进阶后再添加；
skills：配置可插拔技能，如搜索、日历、翻译等，与 tools 字段配合使用，默认启用基础技能。
配置字段 | 核心用途 | 新手是否需要修改 | 修改后是否需重启网关 |
|---|---|---|---|
| 控制斜杠命令启用状态 | 否（默认全部启用） | 否 |
| 管理会话生命周期 | 否（默认即可） | 否 |
| 配置扩展插件 | 否（新手后期优化） | 是 |
| 配置可插拔技能 | 否（默认启用基础技能） | 否 |
{ "env": { // 直接定义环境变量（键名大写，值为敏感信息） "ZAI_API_KEY": "xxxxx", "OPENROUTER_API_KEY": "gsk-xxxxx", // 批量定义环境变量（vars 是对象，可添加多个键值对） "vars": { "GATEWAY_TOKEN": "xxxxxxxxxxxx", "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxxxx" } }}
子字段 | 含义 | 使用方式 | 注意事项 |
|---|---|---|---|
直接定义的变量（如 ZAI_API_KEY） | 单个环境变量 | 配置文件中用 ${变量名} 引用，如 ${ZAI_API_KEY} | 键名建议大写，区分不同类型的敏感信息 |
| 批量环境变量集合 | 同单个变量，引用格式 ${vars.变量名}，如 ${vars.GATEWAY_TOKEN} | 适合存储多个敏感信息，便于分类管理 |
{ "messages": { "prefix": "[OpenClaw 回复] ", // 回复消息前缀（自定义，方便区分Agent回复） "queue": {"enabled": true, "maxSize": 10}, // 消息队列（启用后可处理并发消息） "ack": {"enabled": true, "reaction": "✅"}, // ACK反应（飞书消息已读回执，显示✅） "format": "markdown" // 消息格式（markdown=富文本，plain=纯文本） }}
子字段 | 含义 | 默认值/可选值 | 优化建议 |
|---|---|---|---|
| 回复消息前缀 | 空字符串（默认） | 可添加自定义前缀，如 "[小龙虾回复] "，方便区分 |
| 是否启用消息队列 | false（默认） | 多用户使用时建议启用，避免消息丢失 |
| 消息格式 | markdown（默认）、plain | 保持 markdown 即可，支持富文本显示（如代码、标题） |
{ "bindings": { "rules": [ { "channel": "feishu", // 匹配渠道（飞书） "user": ["user1@feishu.com", "user2@feishu.com"], // 匹配用户 "agent": "agent1" // 路由到的Agent名称 }, { "keyword": ["技术", "开发"], // 匹配消息关键词 "agent": "agent2" // 路由到的Agent名称 } ] }}
{ "logging": { "level": "info", // 日志级别（debug=详细日志，info=普通日志，error=仅错误日志） "path": "~/.openclaw/logs", // 日志输出路径（默认） "maxSize": 100, // 单个日志文件最大大小（单位：MB，默认100MB） "maxDays": 7 // 日志保留天数（默认7天，自动清理过期日志） }}
子字段 | 含义 | 默认值/可选值 | 使用建议 |
|---|---|---|---|
| 日志级别 | info（默认）、debug、error | 排查故障时设为 debug，正常运行时保持 info |
| 日志输出路径 | ~/.openclaw/logs（默认） | 保持默认即可，方便查找日志文件 |
配置修改后，这些操作需重启网关：修改 gateway、plugins、channels 配置后，必须执行 openclaw gateway restart命令，配置才能生效，其他字段修改无需重启；敏感信息安全：API Key、AppSecret、认证令牌等敏感信息，优先用环境变量引用（如 ${ZAIAPIKEY}），严禁明文写入配置文件，避免泄露； 新手避坑：先修改核心字段（models、agents、channels），确保Agent能正常运行，进阶字段（env、bindings、logging）后期按需优化，不要盲目修改不熟悉的字段； 配置报错排查：若修改后服务无法运行，大概率是JSON语法错误（如少逗号、单引号代替双引号），可检查配置文件的语法格式，或恢复默认配置后重新修改。 OpenClaw 官方文档：https://docs.openclaw.ai
Claude Code 最佳实践：一套可以每天照着走的默认工作流
不微调、不改参数！让 Agent 部署后持续进化的核心方案
.claude 文件夹剖析：关于CLAUDE.md等文件的完整指南
50个Claude Code日常使用技巧与最佳实践
OpenAI 开源维护工作流：Skills+AGENTS.md+CI 实战
Anthropic 工程师分享 让Agent 稳定复用团队经验
OpenClaw 问题排障核心：理清渠道、账号、Agent、会话和记忆
Claude 官方架构师认证来了！免费考，AI 从业者的硬核加分项
编程Agent重构软件团队：PRD未死，判断力成核心竞争力
AI 写满 90% 代码后，架构师的核心价值在哪？
OpenClaw工作原理解析：三道闸门
终身学习 专注AI分享
深耕AI领域，探索・实践
欢迎关注，期待同行
