1. 先理清 OpenClaw 四层概念Gateway、Agent、Skills、Channels 到底谁管谁OpenClaw 是一套把大模型能力接到真实聊天入口、再落到具体任务执行的开源智能体框架。它最容易被新手搞混的地方不是安装命令而是四个核心概念的分工Gateway 是控制中枢Agent 是执行单元Skills 是功能模块Channels 是交互入口。你可以把它类比成一家公司Gateway 是前台加调度中心Agent 是具体干活的员工Skills 是员工掌握的技能包Channels 是客户找上门的渠道微信、飞书、钉钉等。谁负责收消息、谁负责调模型、谁负责真正动手理清这条链路配置才不会互相打架。我见过太多人第一次搭 OpenClaw卡在“消息进来了但 Agent 没反应”或者“Agent 装好了但渠道连不上”。根因几乎都是没搞清这四层的依赖顺序Channels 把消息交给 GatewayGateway 路由给某个 AgentAgent 再按需调用 Skills 完成任务结果原路返回。任何一层配置错位整条链路就断。这篇就按“概念关系 → 前置准备 → 可复制配置 → 验证请求 → 报错排查 → 下一步”的顺序带你在本地跑通一条完整链路。适合谁看第一次搭建多通道智能体工作流的开发者手里有 OpenClaw 但配置总是差一口气的人以及想把微信/飞书/钉钉接进自己 Agent 的国内用户。下面所有配置片段都可以直接复制路径和字段名以 OpenClaw 实际配置文件为准。先记住一句话Gateway 不干活它只调度Agent 才是干活的Skills 决定 Agent 会什么Channels 决定用户从哪进来。理解这句后面所有配置都是它的展开。2. 前置准备TaoToken 接入与 OpenClaw 环境初始化OpenClaw 本身不绑定某一家模型它通过 provider 配置去调用大模型 API。国内开发者最常遇到的坑是模型 API 的 Base URL、Key、Model ID 三件套没对齐导致 Agent 一启动就报 401 或连接超时。这里我用 TaoToken 作为模型接入层来演示因为它同时提供 OpenAI 兼容接口和 Claude 系列接口配置方式和 OpenClaw 的 provider 字段能直接对上。TaoToken 的定位是模型 API 聚合接入官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key然后拿到两个关键信息Base URL 和可用的 Model ID。OpenClaw 的 provider 配置里Base URL 填 TaoToken 的 API 地址Key 填你创建的令牌Model ID 填你要用的模型名。环境初始化分三步。第一步确认 Node 环境OpenClaw 依赖较新的 Node 版本node -v # 建议 v20 及以上 npm install -g openclaw openclaw --version第二步做基础初始化这一步会生成~/.openclaw/openclaw.json主配置文件和~/.openclaw/agents/目录openclaw setup openclaw onboardonboard会引导你选 provider、填 Key、选默认模型。如果你在这一步跳过了后面也可以手动改配置文件。第三步验证 Gateway 能否起来openclaw gateway start openclaw gateway status openclaw healthhealth返回正常说明 Gateway 这个控制中枢已经活了。注意Gateway 起来不代表 Agent 能用它只是调度层。接下来要配 provider 和 Agent才能让消息真正被处理。这里有个容易忽略的点OpenClaw 的配置文件是 JSON 格式字段层级比较深手改容易漏逗号或括号。建议每次改完都跑一次openclaw config validate它会告诉你哪一行语法错了。我试过直接改openclaw.json忘了加逗号Gateway 重启后直接起不来日志里只报 JSON parse error排查了半天。3. 可复制配置Gateway、Channels、Agent 与 Skills 绑定片段这一节是全文核心给你可以直接复制的配置片段。先明确文件位置主配置在~/.openclaw/openclaw.jsonAgent 定义在~/.openclaw/agents/目录下Skills 通过 ClawHub 安装后在 Agent 配置里引用。先看 Gateway 的基础配置。Gateway 管端口、内存限制、日志级别和 provider 路由{ gateway: { port: 18789, host: 127.0.0.1, memory: { limit: 2048 }, log: { level: info } }, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_API_KEY, models: { default: YOUR_MODEL_ID } } } }注意baseUrl填的是 TaoToken 的 API 地址apiKey换成你在控制台创建的令牌default换成你要用的 Model ID。这三件套必须同时正确缺一个就会在 Agent 调用时报错。再看 Channels 配置。Channels 决定用户从哪个入口进来每个渠道有自己的凭证字段。以飞书为例{ channels: { feishu: { enabled: true, appId: YOUR_APP_ID, appSecret: YOUR_APP_SECRET, encryptKey: YOUR_ENCRYPT_KEY, verificationToken: YOUR_VERIFICATION_TOKEN } } }如果你用命令行添加等价写法是openclaw channels add --channel feishu \ --app-id YOUR_APP_ID \ --app-secret YOUR_APP_SECRET \ --encrypt-key YOUR_ENCRYPT_KEY \ --verification-token YOUR_VERIFICATION_TOKEN然后是 Agent 定义。Agent 是执行单元它要绑定 provider、绑定 Skills、绑定它响应哪个 Channel。在~/.openclaw/agents/下新建一个assistant.json{ name: assistant, provider: taotoken, model: YOUR_MODEL_ID, channels: [feishu], skills: { browser-control: { enabled: true, config: { headless: false, timeout: 30000 } }, file-operations: { enabled: true, config: { allowed_directories: [~/Documents, ~/Downloads], max_file_size: 10485760 } } } }这段配置的含义是这个叫 assistant 的 Agent用 taotoken 这个 provider 的模型只响应 feishu 渠道进来的消息并且启用了浏览器控制和文件操作两个 Skills。Skills 必须先安装再引用安装命令是clawhub install browser-control clawhub install file-operations openclaw skills listskills list能列出已安装技能确认安装成功后再写进 Agent 配置。如果 Agent 配置里引用了一个没安装的 Skill启动时会报 skill not found。最后把 Gateway、Channels、Agent 串起来Gateway 负责把 feishu 渠道的消息路由给 assistant 这个 AgentAgent 再按需调用 browser-control 或 file-operations。改完所有配置后重启openclaw gateway restart openclaw agents list openclaw channels statusagents list能看到 assistantchannels status能看到 feishu 是 connected说明四层已经串通。4. 验证请求从发一条消息到看到 Agent 完整响应配置写完不代表链路通了必须做端到端验证。验证分三层Gateway 层、Channel 层、Agent 层。逐层确认出问题才知道卡在哪。第一层Gateway 健康检查openclaw health openclaw gateway statushealth返回 okstatus显示 running说明控制中枢正常。如果这里就失败先别管 Agent去看openclaw logs --follow的实时日志。第二层Channel 连通性openclaw channels status --probe--probe会主动探测渠道连接飞书会返回 token 是否有效、事件订阅是否配置。如果显示 disconnected多半是 appId/appSecret 填错或者飞书开放平台的事件订阅地址没指向你的 Gateway。第三层Agent 响应。在飞书里给机器人发一条消息比如“帮我看看 Downloads 目录里有哪些文件”。预期结果是 Agent 调用 file-operations 技能读取目录并返回文件列表。同时观察日志openclaw logs --follow正常链路会依次打印收到 feishu 消息 → Gateway 路由到 assistant → Agent 调用 file-operations → 返回结果 → 回写 feishu。如果日志停在“路由到 assistant”之后没有下文说明 Agent 的 provider 或 model 配置有问题通常是 401 或 model not found。你也可以用命令行直接测 Agent绕过 Channelopenclaw agents run assistant 列出 Downloads 目录这条命令直接触发 Agent 执行不经过飞书。如果命令行能跑通但飞书不行问题就在 Channel 层如果命令行也报错问题在 Agent 或 provider 层。这个二分法能帮你快速定位。验证模型本身是否可用可以到模型对话页面直接发一条测试消息确认 Key 和 Model ID 没问题。这一步能排除掉“Key 无效”这类基础问题避免在 OpenClaw 里反复排查。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。OpenClaw 接入模型 API 时报错信息往往不直观下面几个是我和读者都踩过的坑。401 Unauthorized。最常见原因是 Key 无效或 Base URL 不对。检查三件套baseUrl是否是https://taotoken.net/apiapiKey是否完整复制注意前后空格model是否是账号可用的 Model ID。改完跑openclaw config validate再重启。如果还报 401去控制台确认这个 Key 有没有被禁用或额度耗尽。local proxy failed / connection refused。这个报错通常出现在 Gateway 试图访问模型 API 但网络层不通。先确认baseUrl拼写再确认本机能否直接访问该地址curl -I https://taotoken.net/api如果 curl 也不通是网络环境问题不是 OpenClaw 配置问题。如果 curl 通但 OpenClaw 报错检查openclaw.json里有没有多余的 proxy 字段或者环境变量里有没有残留的代理设置干扰。reading choices of undefined。这个报错说明模型返回的响应结构不符合 OpenAI 兼容格式OpenClaw 去读choices字段时读到 undefined。原因通常是 Base URL 指向了非兼容端点或者 Model ID 填成了不存在的模型服务端返回了错误 JSON。解决方法是确认baseUrl是兼容接口地址model是真实存在的模型名。可以在模型对话页面用同一个 Model ID 发一条消息看返回结构是否正常。OAuth 相关报错。如果你用的是 Claude 系列模型OpenClaw 可能走 Anthropic 的 OAuth 流程。报错通常是 token 过期或 scope 不足。检查~/.openclaw/下的凭证文件是否过期重新走一次授权。如果用的是 API Key 模式而非 OAuth确认 provider 配置里没有混入 OAuth 字段。Agent 不响应但无报错。日志显示消息进来了但 Agent 没动作。检查 Agent 配置里的channels字段是否包含消息来源渠道。比如消息从 feishu 进来但 Agent 的channels只写了[wechat]Gateway 就找不到匹配的 Agent消息被丢弃。这个坑很隐蔽因为不报错。Skill 加载失败。报错 skill not found 或 skill load error。先openclaw skills list确认技能已安装再检查 Agent 配置里引用的技能名是否和安装名一致。ClawHub 上的技能名有时带前缀复制时容易漏。排查通用命令openclaw doctor --fix openclaw logs --filter error openclaw config validatedoctor --fix能自动修一部分配置问题logs --filter error只看错误日志config validate查语法。三个一起用大部分配置类问题都能定位。6. 下一步把链路跑稳之后该做什么链路跑通只是起点。接下来你大概率会想加更多 Channels、装更多 Skills、或者把 Agent 接到长期编码任务上。这里给几个方向。多通道扩展。飞书跑通后加钉钉或企业微信的配置结构和飞书类似都是 appId/appSecret 那一套区别在字段名。加完记得在 Agent 的channels数组里补上对应渠道名否则消息进不来。每个渠道单独openclaw channels status --probe验证。Skills 按需安装。不要一上来装一堆Skills 越多 Agent 的决策空间越大反而容易调错。先装 browser-control、file-operations、scheduler 这三个高频的跑稳了再按场景加。装完在 Agent 配置里逐个启用每加一个就测一次。长期编码和 Agent 任务。如果你想让 Agent 持续处理代码类任务可以了解 Coding Plan 这类长期方案它更适合高频、长会话的场景比单次 API 调用更省心。接入文档里有完整的 provider 配置说明遇到字段不确定时对照文档比猜快得多。最后提醒一句所有配置改完都要openclaw gateway restartGateway 不会热加载配置文件。重启后先openclaw health再测业务养成这个习惯能省很多排查时间。