OpenClaw 深度解析：Gateway、Agent 与 Skills 的配置骨架与验证路径

1. OpenClaw 本地部署为什么总卡在 Gateway 与 Agent 之间OpenClaw 是一个自托管的多渠道 AI 智能体网关它把飞书、Telegram、Discord 这类聊天入口接到 LLM 上让 Agent 能主动巡查、执行任务、持久记忆。适合谁适合想把 AI 助手跑在自己机器上、数据不出本地、又需要 24 小时在线的开发者。它的核心由三块骨架组成Gateway 负责守护进程与消息路由Agent 负责推理与工具调用循环Skills 负责把基础工具组合成专业能力。很多人第一次跑 OpenClaw装完发现 Gateway 起来了但 Agent 不响应或者 Agent 响应了但 Skills 加载不到问题基本都出在这三块的配置衔接上。我试过在本地把这三块拆开逐项验证发现最有效的路径不是一次性写完整配置而是先让 Gateway 单独跑通再挂 Agent最后加 Skills。下面这份骨架就是按这个顺序组织的你可以直接复制改参数。2. TaoToken 统一 Key 与 API 通道的前置准备OpenClaw 的 Agent 最终要调用 LLM而 LLM 的接入点集中在auth-profiles.json和model-registry.json两个文件里。与其在每个 Agent 里分别填不同厂商的 Key不如用一个统一通道收敛。TaoToken 提供的就是这样一个入口一个 Key 走通多家模型OpenClaw 侧只需要改 base URL 和 model 名。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你需要先去控制台建一个 Key然后把它写进 OpenClaw 的认证配置。这一步不做后面 Agent 的 LLM 调用会直接 401。注意Key 只存在本地auth-profiles.json不要提交到任何仓库。OpenClaw 的 Local-First 设计里这个文件默认不上传。3. 可复制的 config.toml 与 settings.json 骨架OpenClaw 主配置是~/.openclaw/openclaw.jsonJSON5 格式但很多教程里也会用config.toml做等价表达。下面给一份能直接跑的最小骨架重点覆盖 Gateway、Agent、Skills 三段。3.1 Gateway 守护进程配置{ gateway: { daemon: { enabled: true, heartbeatInterval: 300000, autoRestart: true, maxRestartAttempts: 3 }, heartbeat: { enabled: true, interval: 300000, checks: [ { type: messages, interval: 300000 }, { type: cron, interval: 60000 }, { type: system, interval: 1800000 } ] }, queue: { rateLimit: { qpm: 60, tpm: 100000 } } } }这段的作用是让 Gateway 以守护进程方式常驻每 5 分钟做一次心跳巡查消息队列限速防止打爆 API。3.2 Agent 与模型通道配置{ agents: { defaults: { workspace: ~/.openclaw/workspace, model: { primary: anthropic/claude-sonnet-4-6, fallbacks: [openai/gpt-5.4] } }, list: [ { id: main, workspace: ~/.openclaw/workspace, skills: [github, weather, feishu-doc] } ] }, bindings: [ { agentId: main, match: { channel: feishu, peer: { kind: direct, id: ou_xxx } } } ] }bindings决定哪个渠道的消息路由到哪个 Agent。没有这条消息进来会找不到归属。3.3 TaoToken 认证与模型注册~/.openclaw/agents/main/agent/auth-profiles.json{ profiles: [ { id: taotoken, provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, models: [claude-sonnet-4-6, gpt-5.4] } ] }model-registry.json里把模型名映射到上面的 profile{ models: { anthropic/claude-sonnet-4-6: { profile: taotoken, model: claude-sonnet-4-6 }, openai/gpt-5.4: { profile: taotoken, model: gpt-5.4 } } }3.4 Skills 目录骨架Skills 加载优先级从高到低是工作区skills/、项目.agents/skills、个人~/.agents/skills、托管~/.openclaw/skills、内置。一个最小 SKILL.md--- name: github description: GitHub 操作技能 metadata: openclaw: requires: bins: [gh] env: [GITHUB_TOKEN] --- # GitHub 操作技能 使用 gh CLI 进行 GitHub 操作。 ## 工作流程 1. 确认 Issue 标题和描述 2. 执行 gh issue create --title ... --body ... 3. 解析返回的 Issue URL4. 逐项验证请求与成功结果配置写完不代表跑通必须逐项验证。下面是我实测下来最省时间的验证顺序。4.1 验证 Gateway 状态openclaw gateway status --deep期望输出里能看到 WebSocket 连接、Channel Provider 状态、Agent 实例、内存占用。如果 Channel 显示 Disconnected先别急着调 Agent先把渠道 Token 修好。4.2 验证 LLM 通道openclaw models test --profile taotoken --model claude-sonnet-4-6这条会实际发一次请求到 TaoToken 的 API 基址。返回 200 且带 assistant 文本说明 Key 和 base URL 都对。如果 401检查auth-profiles.json里的 apiKey如果 404检查 baseUrl 是否漏了/api。4.3 验证 Agent 推理循环openclaw agent run --agent main --message 帮我查一下今天的日程期望看到 Agent 加载历史记忆、构建 System Prompt、加载 Skills、调用 LLM、返回结果。如果卡在加载 Skills说明 SKILL.md 的 frontmatter 格式有问题。4.4 验证 Skills 加载openclaw skills list --agent main输出里应该列出 github、weather、feishu-doc 三个技能。如果某个技能缺失检查它的requires.bins和requires.env是否满足。4.5 验证渠道消息闭环在飞书里 机器人发一条消息然后openclaw logs --follow日志里应该出现消息接收、Agent 启动、工具调用、消息发送的完整链路。这条跑通说明 Gateway、Agent、Skills 三块骨架全部联动成功。5. 本篇常见错误排查5.1 Gateway 启动失败最常见原因是openclaw.json的 JSON5 语法错误。用openclaw doctor --fix它会自动检测并修复大部分配置问题。如果还不行检查端口 18789 是否被占用。5.2 Agent 不响应消息先看bindings配置。消息进来后 Gateway 会根据 bindings 匹配 Agent没有匹配项就走默认 Agent。如果默认 Agent 没配消息会被丢弃。用openclaw channels status --probe确认渠道连接正常再检查 bindings 里的 peer id 是否和实际发送者一致。5.3 Skills 加载不到三个检查点SKILL.md 的 frontmatter 是否以---开头结尾requires.bins里的命令是否在 PATH 里requires.env里的环境变量是否已导出。缺一个技能就会被跳过。5.4 LLM 调用超时或 Rate Limit如果日志里出现 timeout 或 429先看 Gateway 的queue.rateLimit配置。QPM 设太高会触发上游限流设太低会拖慢响应。另外确认fallbacks里的备用模型也走同一个 TaoToken profile否则主模型挂了备用模型也调不通。5.5 Session 记忆丢失OpenClaw 的记忆分两层Session transcript 存在sessions/id.jsonl长期记忆存在MEMORY.md。如果重启后记忆没了检查session.reset配置里的daily和idleMinutes是否触发了重置。想保留长期记忆确保MEMORY.md在 workspace 根目录且没被清理。6. 把三块骨架串起来之后Gateway 跑通、Agent 挂上、Skills 加载成功这三步做完OpenClaw 的联动链路就通了。后面你要做的无非是往 Skills 目录里加更多 SKILL.md或者在agents.list里加更多隔离 Agent。如果你打算长期跑编码类 Agent建议把 Coding Plan 也接进来让 Agent 在需要写代码时走专门的通道。模型对话入口可以用来快速验证某个模型在 TaoToken 上是否可用接入文档里有完整的 base URL 和参数说明。API Keys 页面则是你管理所有 Key 的地方换 Key 不用改 OpenClaw 配置改auth-profiles.json一处就行。最后留一个实用技巧每次改完配置先跑openclaw doctor --fix再跑openclaw gateway status --deep最后openclaw logs --follow看实时链路。这三条命令能覆盖 90% 的配置问题比盲目翻文档快得多。