1. 为什么你装了 OpenClaw 却总觉得“它不听话”很多人第一次接触 OpenClaw是被“AI 代理框架”这个词吸引的能自己上网查资料、能发邮件、能操作浏览器听起来像给电脑请了个数字员工。可真正把环境搭起来、在控制台里敲下第一句指令之后问题就来了——明明装了查天气的技能AI 却回你“找不到对应能力”照着旧教程敲clawdbot status终端直接甩一句命令不存在想装个邮件技能在 ClawHub 和 GitHub 之间来回翻最后连依赖都没装明白。这些卡点几乎都指向同一件事你没把 OpenClaw 的组件边界理清楚。OpenClaw 不是一个“单体大程序”它更像一支分工明确的数字员工团队。你只盯着“老板”下命令却不知道“前台”有没有把话传进去、“员工”有没有到岗、“招聘渠道”有没有选对出问题时自然无从下手。这篇是《OpenClaw 从入门到精通》的第 03 篇目标很具体把 Gateway、Skills、ClawHub 这三个最容易混淆的核心概念拆开讲透。读完之后你应该能做到三件事——看懂 Gateway 的路由配置、独立完成 Skills 的注册与调用、在 ClawHub 里正确接入技能并验证生效。全程按 2026 年实测的命令和参数来写遇到报错也有对应的排查路径。先给一个全局类比后面所有细节都挂在这张图上OpenClaw 核心是“老板”负责理解意图、拆任务、做调度Gateway 是“前台加后勤”负责接电话、记会话、管技能加载Skills 是“专业员工”真正动手干活ClawHub 是“人才市场”让你一条命令招到合适的员工。四者缺一不可但职责绝不重叠。搞混任何一个都会在排障时走弯路。2. TaoToken 前置给 OpenClaw 核心接上“大脑”在深入 Gateway 和 Skills 之前得先解决一个前置问题OpenClaw 核心本身没有大模型推理能力。它只是个调度器真正“听懂人话”的那部分要靠你配置的大模型 API。这一步没做对后面 Gateway 起得再稳、Skills 装得再多AI 也只会回你“我无法理解”。我试过用 TaoToken 作为 OpenClaw 的模型接入层原因是它把多家模型的调用统一成一个 OpenAI 兼容接口配置起来比逐个对接省事。下面按“拿 Key → 写配置 → 验证连通”三步走每一步都给可复制的命令。2.1 获取 API Key 与确认 Base URL先到 TaoToken 控制台创建 API Key。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_gateway_skills_clawhub登录后点“创建密钥”复制那串以sk-开头的字符串。注意Key 只在创建时完整显示一次关掉弹窗就看不到了建议先存到密码管理器。Base URL 用https://taotoken.net/api这个地址不加任何查询参数。它兼容 OpenAI 的/v1/chat/completions路径所以 OpenClaw 里凡是要求填 OpenAI 兼容端点的位置都填它。2.2 写入 OpenClaw 的模型配置OpenClaw 的配置文件默认在~/.openclaw/openclaw.json。你可以用openclaw config set逐项写也可以直接编辑 JSON。推荐后者因为一次能看清结构。下面这段是 2026 年实测可用的最小配置片段路径和字段名与官方一致{ models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [gpt-4o-mini, claude-3-5-sonnet] } }, default: taotoken/gpt-4o-mini } }这里type必须是openai-compatiblebaseUrl结尾不要带/v1OpenClaw 会自己拼。models数组里写你打算用的模型 IDdefault指定默认走哪个。改完保存执行一次openclaw gateway restart让配置生效。2.3 验证模型连通性配置写完别急着往下走先单独验证模型能不能通。OpenClaw 提供了一个轻量测试命令openclaw models test taotoken/gpt-4o-mini正常输出会类似Provider: taotoken Model: gpt-4o-mini Response: pong (latency: 842ms)如果这里就报401 Unauthorized说明 Key 错了或没生效报connection refused检查 Base URL 是否写成了https://taotoken.net/api/多一个斜杠有时会出问题。这一步过了才说明 OpenClaw 核心有了“大脑”后面的 Gateway 和 Skills 才有意义。3. Gateway 路由配置示例让指令进得来、结果出得去Gateway 是 OpenClaw 的后台常驻进程你可以把它理解成“一直守在服务器后台的管家”。它不直接处理你的指令但没有它OpenClaw 就是一间没门的房子——你进不去结果也出不来。这一章给一份可复制的 Gateway 路由配置并逐项说明每个参数的作用。3.1 Gateway 到底管什么Gateway 的职责有四块连接管理、会话维护、技能加载、事件处理。连接管理指它监听 Web 控制台、钉钉/飞书机器人、TUI 终端这些入口会话维护指它把对话历史存到~/.openclaw/sessions让你在电脑上发的指令手机上也能看到回复技能加载指它启动时扫描技能目录建立“技能注册表”事件处理指它跑定时任务和 Webhook。这四块里最常出问题的是连接管理和技能加载。连接没配好控制台打不开技能没加载AI 能理解指令却执行不了。下面的配置主要围绕这两块。3.2 可复制的 Gateway 配置片段Gateway 的配置同样写在openclaw.json里顶层键是gateway。下面这份是 2026 年实测可用的路由配置包含监听地址、端口、会话存储和技能目录{ gateway: { host: 0.0.0.0, port: 18789, sessionStore: ~/.openclaw/sessions, skillsDir: ~/.openclaw/skills, workspaceSkillsDir: ./skills, channels: { web: { enabled: true }, dingtalk: { enabled: false, webhook: https://oapi.dingtalk.com/robot/send?access_token你的token } }, scheduler: { enabled: true, timezone: Asia/Shanghai } } }逐项说明host填0.0.0.0表示允许外部访问只在本机用可以填127.0.0.1port默认 18789改端口后记得防火墙同步放行sessionStore和skillsDir是路径用~开头即可workspaceSkillsDir指向当前工作目录下的skills这是后面讲技能优先级的关键channels里按需开启入口钉钉的webhook换成你自己的机器人地址scheduler控制定时任务时区填Asia/Shanghai避免任务在半夜跑。3.3 启动与状态验证配置写完后按顺序执行openclaw gateway start openclaw statusopenclaw status的正常输出类似Gateway is running (pid: 18901) - uptime: 0d 0h 2m 15s Listening on: 0.0.0.0:18789 Loaded skills: 12 (0 workspace, 11 managed, 1 built-in) Active sessions: 3看到Loaded skills这一行说明 Gateway 已经完成技能扫描。如果这里显示0 managed而你明明装过技能那多半是skillsDir路径写错了或者装完技能后没执行openclaw skills reload。这是新手最常踩的坑之一后面第五章会专门讲。3.4 两种部署模式的取舍Gateway 可以本地跑也可以云端跑。本地模式适合个人电脑单机使用数据全在本地但电脑关机服务就停。云端模式适合 7×24 小时在线和团队共享需要配开机自启和安全组放行 18789 端口。云端部署时Linux 下执行systemctl enable openclaw设置自启然后确认云服务器安全组里 18789 是放行状态否则控制台会提示连接拒绝。如果你既想要云端在线又想让 AI 操作本地文件可以用“云加端”分布式思路云端跑 Gateway 负责调度和联网本地跑设备节点通过内网穿透连接。这个属于进阶内容先把单机模式跑通再考虑。4. Skills 注册与调用清单从“能说”到“能做”Skills 是 OpenClaw 真正动手干活的部分。没有 SkillsAI 只能和你文字聊天有了 Skills它才能查天气、发邮件、操作浏览器。这一章给一份技能注册与调用的完整清单包括来源、优先级、注册命令和调用验证。4.1 技能的三大来源与加载优先级OpenClaw 的技能有三个来源加载顺序是“工作区技能 → 托管技能 → 内置技能”同名技能后加载的会覆盖先加载的。这个顺序是排障的核心知识点。内置技能在 OpenClaw 安装目录的skills/下装框架时自带不可卸载提供会话管理、帮助这类基础功能。托管技能在~/.openclaw/skills/managed/下通过 ClawHub 安装是你日常用的主力。工作区技能在当前目录的./skills/下你自己开发或改过的技能放这里优先级最高。理解这个优先级你就能在不改动原技能的前提下覆盖它的行为。比如你想改邮件技能的默认发件人不用去动托管目录复制一份到工作区改掉即可测试完删掉工作区文件就恢复原版。4.2 技能注册与查看命令清单下面这组命令覆盖了技能的注册、查看、启用、禁用和重载建议收藏# 查看所有已加载技能 openclaw skills list # 查看某个技能的详细信息来源、版本、路径、状态 openclaw skills info email # 重新扫描技能目录装完新技能后必做 openclaw skills reload # 禁用某个技能保留安装不加载 openclaw skills disable --name tavily-search # 启用被禁用的技能 openclaw skills enable --name tavily-search # 测试某个技能是否可用 openclaw skills test emailopenclaw skills info email的输出里Source字段会告诉你这个技能来自Workspace、ClawHub (managed)还是built-in。当你改了技能却没生效时先看这个字段确认加载的是不是你改的那份。4.3 调用技能的正确姿势技能不是靠“喊名字”调用的而是 OpenClaw 核心根据你的指令意图自动匹配已加载的技能。你要做的是把指令说清楚让核心能拆出子任务。比如“查明天北京天气发我邮箱”这句话核心会拆成“查天气”和“发邮件”两个子任务分别匹配对应技能。如果核心提示“找不到对应能力”按这个顺序排查先openclaw skills list确认技能在列表里再openclaw skills info 技能名确认状态是enabled然后openclaw skills test 技能名确认技能本身能跑最后检查指令里有没有明确的任务动词。三步都过了还不行看 Gateway 日志openclaw logs里面会记录技能匹配的详细过程。4.4 技能不是越多越好装太多技能会拖慢 Gateway 启动还会让核心在匹配时混淆。实测装 50 个技能Gateway 启动时间从 10 秒涨到 45 秒。建议按需安装暂时不用的用openclaw skills disable禁用而不是卸载需要时再启用。这样既保留配置又不影响启动速度。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一章把 OpenClaw 配置过程中最常见的四类报错拎出来逐个给排查路径。这些报错在 Gateway、Skills、模型接入三个环节都会出现对照着看能省不少时间。5.1 401 Unauthorized这个报错几乎都出在模型接入环节。执行openclaw models test或发指令时返回 401说明 API Key 无效或没被正确读取。排查顺序先确认openclaw.json里apiKey字段填的是完整 Key没有多余空格再确认baseUrl是https://taotoken.net/api结尾没多斜杠然后执行openclaw config get models.providers.taotoken.apiKey看实际读到的值最后openclaw gateway restart让配置重载。如果 Key 是在 TaoToken 控制台刚创建的确认没有误删。5.2 local proxy failed这个报错通常出现在 Gateway 启动阶段提示本地代理连接失败。原因一般是 Gateway 配置里指向了一个不存在的本地服务或者端口被占用。排查先openclaw status看 Gateway 是否已在运行如果已运行又启动一次会端口冲突再检查openclaw.json里gateway.port有没有和其他服务撞车换一个端口试试如果配了channels里的 webhook确认那个地址能通。改完配置记得openclaw gateway restart。5.3 reading choices 相关报错这类报错多出现在模型返回格式不符合预期时日志里会看到error reading choices或类似字样。根因通常是模型端点返回的 JSON 结构和 OpenClaw 期望的不一致。排查确认baseUrl指向的是 OpenAI 兼容端点确认type字段是openai-compatible用curl直接打一次端点看返回结构curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}返回里应该有choices数组。如果没有说明端点或模型 ID 不对。5.4 OAuth 相关报错如果你在配置某些需要 OAuth 的技能或渠道时看到 OAuth 报错先确认回调地址有没有填对。OpenClaw 的 OAuth 回调一般走http://你的IP:18789/oauth/callback端口要和 Gateway 配置一致。如果是在云端确认安全组放行了这个端口。另外OAuth 的 token 有时效过期后需要重新授权日志里会提示token expired。5.5 三件套检查法不管是哪类报错配完模型后都建议做一次“三件套”检查Base URL、Key、Model ID 三项是否齐全且一致。Base URL 用https://taotoken.net/apiKey 用sk-开头那串Model ID 用taotoken/gpt-4o-mini这种“provider/model”格式。三项里任何一项写错都会导致上面某类报错。把这三项写进配置后先跑openclaw models test过了再动 Gateway 和 Skills排障范围能缩小一大半。6. 语义一致 CTA把概念地图用起来概念理清之后下一步就是动手验证。如果你还在模型接入阶段建议先把 API Key 和接入文档过一遍地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_gateway_skills_clawhub接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_gateway_skills_clawhub里面有各语言的最小调用示例。想先验证模型对话是否正常可以直接在模型对话页试一句地址是https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_gateway_skills_clawhub输入“ping”看有没有正常回复能快速排除 Key 和端点问题。如果你打算长期跑编码类或 Agent 类任务Coding Plan 会更划算地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_gateway_skills_clawhub适合需要稳定调用、频繁跑任务的场景。控制台在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_gateway_skills_clawhub可以看用量和余额。最后留一个实操建议把这篇里的 Gateway 配置片段和 Skills 命令清单存成一个openclaw-notes.md下次遇到“技能不生效”或“控制台打不开”直接对着清单逐项打勾。概念地图的价值不在于背下来而在于出问题时你知道该看哪一层。Gateway 看连接和加载Skills 看来源和状态模型接入看三件套三条线分开查大部分问题十分钟内能定位。