1. 为什么要在 OpenClaw 里做统一模型接入OpenClaw 是一个把大模型推理和本地系统操作结合起来的 Agent 运行时框架核心由 Gateway、Agent、Skill、Memory 四大模块组成。Gateway 负责消息调度和路由Agent 负责决策推理Skill 封装具体能力Memory 管理上下文持久化。这套架构跑起来之后真正决定体验上限的其实是模型通道——Agent 每一轮 Lobster Loop 都要调 LLMSkill 执行结果要回灌上下文Memory 检索出来的片段也要塞进 Prompt这些环节全部依赖一个稳定、低延迟、可切换的模型入口。我试过在 OpenClaw 里直接写死某一家厂商的 API Key结果换模型要改源码、加渠道要重新打包、多 Agent 共用一套配置时 Key 到处散落。后来把模型通道统一收敛到 TaoTokenGateway 只认一个 Base URL 和一个 KeyAgent 初始化时通过环境变量注入Skill 和 Memory 的 embedding 也走同一条通道整个链路清爽很多。这篇会按源码结构把四个模块拆开讲重点落在可复制的配置上Gateway 的路由配置、Agent 的初始化参数、Skill 的注册模板、Memory 的持久化设置每一步都给验证动作。适合已经在跑 OpenClaw、想把它接进自己业务链路的开发者也适合刚开始读这套源码、想先跑通再深入的人。下面所有配置都基于 OpenClaw 的openclaw.json和~/.openclaw/workspace/目录结构路径和字段名跟源码保持一致。2. TaoToken 前置准备与 OpenClaw 模型通道配置在动 Gateway 和 Agent 之前先把模型通道准备好。TaoToken 提供统一的 API 入口OpenClaw 的providers/目录下每个 Provider 本质上就是一个 baseURL apiKey model 的组合所以接入方式很直接。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 后面会同时给 Agent 推理、Skill 内部调用、Memory embedding 三处使用所以建议单独建一个项目 Key方便按项目做额度隔离。Base URL 用https://taotoken.net/api注意不要带任何查询参数。OpenClaw 的 Provider 配置里 baseURL 会被拼成{baseURL}/v1/chat/completions这种形式多一个斜杠或少一个斜杠都会导致 404这个坑后面排障章节会细说。模型 ID 方面Agent 主推理建议用带工具调用能力的模型比如claude-sonnet-4-20250514或gpt-4o具体可用列表在 https://taotoken.net/doc 里能查到。Memory 的 embedding 单独配一个 embedding 模型比如text-embedding-3-small1536 维跟 OpenClaw 默认的chunks_vec表结构对得上。配置写进openclaw.json的providers段{ providers: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: claude-sonnet-4-20250514, fast: gpt-4o-mini, embedding: text-embedding-3-small } } }, defaultProvider: taotoken }Key 不要硬编码进 JSON用环境变量注入。在启动脚本或.env里写export TAOTOKEN_API_KEYsk-你的实际KeyOpenClaw 的src/runtime.ts在初始化时会读取${VAR}形式的占位符并做环境变量替换所以这样写是安全的。如果你用 Docker 跑在docker-compose.yml的environment段里加一行TAOTOKEN_API_KEY${TAOTOKEN_API_KEY}宿主机.env里放真实值。验证通道是否通不用等整个 OpenClaw 起来先单独打一个请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }返回里能看到choices[0].message.content就说明 Key 和 Base URL 都对。这一步过了再往下配 Gateway能省掉很多「到底是通道问题还是框架问题」的排查时间。3. Gateway 路由配置与 Agent 初始化参数可复制模板Gateway 是 OpenClaw 的中枢源码在src/gateway/目录下server.ts管 WebSocket 和 HTTP 服务boot.ts管启动引导。它默认监听ws://127.0.0.1:18789和http://127.0.0.1:18793所有渠道消息、Agent 会话、工具调用都从这里过。Gateway 本身不直接调模型它把消息归一化成MsgContext之后路由给 Agent 实例。所以 Gateway 的配置重点是路由规则和鉴权模型通道在 Agent 层注入。openclaw.json里 Gateway 段这样写{ gateway: { host: 127.0.0.1, wsPort: 18789, httpPort: 18793, auth: { mode: token, token: ${GATEWAY_TOKEN} }, routing: { defaultAgent: marketing-agent, rules: [ { match: { channel_id: feishu }, agent: marketing-agent }, { match: { channel_id: telegram, content_prefix: /code }, agent: coding-agent } ] }, rateLimit: { enabled: true, tokensPerMinute: 120 } } }routing.rules是三级路由里的第二层按channel_id和内容前缀把消息分发给不同 Agent。defaultAgent兜底。rateLimit用令牌桶防止某个渠道刷爆。Agent 初始化参数在agents段。OpenClaw 的 Agent Runtime 在src/agents/下Lobster Loop 的循环逻辑在这里Planner 的强规则校验也在这里。初始化时最关键的是把 provider 和 model 指对{ agents: { marketing-agent: { provider: taotoken, model: claude-sonnet-4-20250514, systemPromptFile: ~/.openclaw/workspace/SOUL.md, maxToolRounds: 12, contextWindow: 128000, planner: { enabled: true, blockedTools: [exec, write], requireConfirm: [browser] }, skills: { allowlist: [weather, github, notion, feishu-doc] }, memory: { agentId: marketing-agent, sqlitePath: ~/.openclaw/memory/marketing-agent.sqlite, embeddingProvider: taotoken, embeddingModel: text-embedding-3-small } } } }几个参数值得展开。maxToolRounds对应 Lobster Loop 的最大轮数终止条件复杂任务调十几次工具很常见设 12 是保守值你可以按业务调。planner.blockedTools是安全防线把exec和write拦掉防止 LLM 幻觉直接改本地文件。skills.allowlist是 per-agent 的 Skill 白名单只有列出来的 Skill 会被注入这个 Agent 的 System Prompt。memory.agentId决定 SQLite 文件名每个 Agent 一个独立库互不干扰。embeddingProvider指向 taotoken复用同一个 Key。Gateway 和 Agent 都配好之后启动服务cd openclaw npm run build node dist/entry.js --config ./openclaw.json启动日志里会依次打印加载配置、初始化日志、扫描 skills 目录、初始化 provider、启动 WebSocket 18789、启动 HTTP 18793、注册 Channel 适配器、初始化记忆系统。看到Gateway ready就说明四模块的骨架都起来了。4. Skill 注册模板与 Memory 持久化设置Skill 解决的是「Agent 应该怎么做」每个 Skill 是一个含SKILL.md的目录放在skills/下。SKILL.md分两部分YAML Frontmatter 给 OpenClaw 读元数据Markdown Body 给 Agent 读行为指令。一个可复制的最小 Skill 模板比如做营销文案生成的--- name: marketing-copy description: 根据产品信息生成营销文案支持多平台风格适配。 metadata: openclaw: requires: bins: [] env: [] --- # Marketing Copy Skill 当用户要求生成营销文案时按以下流程执行 1. 先确认产品名称、目标平台、核心卖点三个要素缺哪个问哪个。 2. 根据平台选择风格小红书偏口语化带 emoji 分段公众号偏正式带小标题Twitter 偏短句带钩子。 3. 生成 3 个版本每个版本标注适用场景。 4. 输出格式固定为标题 / 正文 / 标签建议。 调用 read 工具读取产品资料文件不要凭空编造卖点。Frontmatter 里的metadata.openclaw.requires是门控条件bins列依赖的二进制env列需要的环境变量不满足条件的 Skill 会被过滤掉不会注入 Prompt。这个机制在多环境部署时很有用。Skill 的加载优先级是内置skills/目录 → 用户本地覆盖 → per-agent allowlist。同名 Skill 本地覆盖内置。加载链路就三步扫描目录、解析 SKILL.md 提取 namedescriptionbody、格式化成 XML 片段拼进 System Prompt。Memory 的持久化设置分两块工作区文件结构和 SQLite 索引。工作区在~/.openclaw/workspace/~/.openclaw/workspace/ ├── MEMORY.md # 长期记忆偏好、决策、持久事实 ├── memory/ │ ├── 2026-03-05.md # 今日日志短期记忆 │ └── 2026-03-04.md # 昨日日志 ├── sessions/ # 会话存档近端记忆 ├── USER.md # 用户身份 └── SOUL.md # Agent 人格设定新会话启动时OpenClaw 自动加载「今天昨天」的日志作为短期记忆MEMORY.md作为长期记忆常驻sessions/里的历史会话按需检索。SQLite 索引在~/.openclaw/memory/{agentId}.sqlite核心表结构CREATE TABLE files ( id INTEGER PRIMARY KEY, path TEXT UNIQUE, mtime INTEGER, size INTEGER, hash TEXT ); CREATE TABLE chunks ( id INTEGER PRIMARY KEY, file_id INTEGER, start_line INTEGER, end_line INTEGER, text TEXT, hash TEXT UNIQUE, embedding TEXT ); CREATE VIRTUAL TABLE chunks_fts USING fts5(text, contentchunks); CREATE VIRTUAL TABLE chunks_vec USING vec0(embedding float[1536]);files表用mtime和hash做增量索引只重新索引变更的文件。chunks表存分块内容和向量hash做跨文件去重。chunks_fts是 BM25 全文检索chunks_vec是向量检索两路并行后合并加权排序。embedding 走 TaoToken 的话chunks_vec的维度要跟模型对上text-embedding-3-small是 1536 维跟上面建表语句一致。如果换text-embedding-3-large的 3072 维建表语句里的float[1536]要改否则插入会报维度不匹配。Memory 的检索配置在openclaw.json的memory段{ memory: { retrieval: { topK: 8, bm25Weight: 0.4, vectorWeight: 0.6, minScore: 0.3 }, indexing: { chunkSize: 512, chunkOverlap: 64, watch: true } } }bm25Weight和vectorWeight控制两路检索结果的合并权重关键词查询多的场景把 bm25 调高语义查询多的把 vector 调高。watch: true开启文件监听工作区文件一改就触发增量索引。5. 四模块协同验证与常见报错排查配置写完启动服务按 Gateway → Agent → Skill → Memory 的顺序逐个验证。Gateway 转发日志。启动后看控制台正常会打印[gateway] WebSocket server listening on ws://127.0.0.1:18789 [gateway] HTTP server listening on http://127.0.0.1:18793 [gateway] routing rules loaded: 2 [gateway] channel adapters registered: feishu, telegram发一条测试消息日志里应该出现[gateway] MsgContext normalized和[gateway] routed to agentmarketing-agent。如果只看到 normalized 没有 routed说明routing.rules的 match 条件没命中检查channel_id拼写。Agent 任务响应。Gateway 路由过去之后Agent 的 Lobster Loop 开始跑日志里会看到[agent] Think→[agent] Act→[agent] Observe的循环。如果卡在 Think 不动多半是模型通道问题回到第 2 节的 curl 验证。Skill 调用链路。Agent 决定调 Skill 时日志里出现[skill] loading marketing-copy和[skill] injected into system prompt。如果 Skill 没被加载检查skills.allowlist里有没有列以及SKILL.md的 frontmatter 格式对不对。Memory 读写结果。Agent 每轮结束会把关键信息写进当日日志日志里出现[memory] appended to 2026-03-05.md。检索时出现[memory] bm25 hits3 vector hits5 merged6。如果 vector hits0检查 embedding 模型和维度。下面是我踩过的几个真实报错对照排查。401 Unauthorized。日志里[provider] request failed status401。原因通常是 Key 没注入成功${TAOTOKEN_API_KEY}没被替换。检查启动环境里有没有exportDocker 里检查environment段。还有一种情况是 Key 复制时带了空格用echo $TAOTOKEN_API_KEY | wc -c看长度对不对。local proxy failed / ECONNREFUSED。日志里[provider] local proxy failed。这是 baseURL 写错比如写成了https://taotoken.net/api/带尾斜杠或者写成了https://taotoken.net少了/api。正确值是https://taotoken.net/api不带尾斜杠。reading choices 报错。日志里Cannot read properties of undefined (reading choices)。这是响应体结构跟预期不符通常是模型 ID 写错返回了错误对象而不是正常响应。用 curl 单独打一次确认模型 ID 在 https://taotoken.net/doc 的列表里。OAuth / token expired。日志里[provider] oauth token expired。OpenClaw 某些 Provider 走 OAuth 流程taotoken 走的是 API Key 模式如果出现这个报错说明type字段写错了应该是openai-compatible而不是oauth。Skill 没生效。Agent 回复里完全没提 Skill 的流程。检查SKILL.md的 frontmatter 有没有---包裹YAML 缩进对不对。OpenClaw 解析失败时会静默跳过日志里不会有明显报错可以在启动时加--verbose看扫描结果。Memory 检索为空。[memory] bm25 hits0 vector hits0。检查~/.openclaw/workspace/memory/下有没有当日日志文件以及 SQLite 文件有没有生成。如果 SQLite 生成了但 chunks 表为空说明索引没跑手动触发一次node dist/cli.js memory reindex --agent marketing-agent。Gateway 端口占用。EADDRINUSE: address already in use 127.0.0.1:18789。上次进程没退干净lsof -i :18789找到 PID 杀掉或者改wsPort换端口。Agent 循环不终止。日志里 Lobster Loop 一直转超过maxToolRounds才停。这是 Planner 没拦住检查planner.enabled是不是 true以及blockedTools有没有覆盖到出问题的工具。上下文超限。日志里context length exceeded, compressing。这是 Memory 的动态上下文管理在压缩正常行为。如果频繁触发把memory.retrieval.topK调小或者把chunkSize调大减少碎片。6. 把四模块接进你的业务链路跑通之后下一步是把 OpenClaw 接进实际业务。Gateway 的 HTTP 接口http://127.0.0.1:18793可以直接被外部系统调用用POST /v1/message发消息body 里带channel_id和contentGateway 会按路由规则分发给对应 Agent。这样你的 CRM、工单系统、营销后台都能通过一个 HTTP 接口触发 Agent。多 Agent 场景下每个 Agent 在agents段独立配置 provider、model、skills、memory共用同一个 TaoToken Key。额度按项目 Key 隔离在 https://taotoken.net/console 里能看到每个 Key 的调用量和费用。长期跑编码类 Agent 的话Coding Plan 的额度模型比按量计费更划算具体在 https://taotoken.net/coding-plan 看。Skill 的扩展是这套架构里最灵活的部分。你不需要改 Gateway 或 Agent 的源码只要在skills/下新建目录、写SKILL.md、加进allowlist重启服务就生效。我建议把业务相关的 Skill 单独放一个目录用metadata.openclaw.requires.env做环境门控测试环境和生产环境用不同的 Skill 集合。Memory 的调优是个持续过程。初期topK设小一点8 左右观察 Agent 回复质量。如果发现 Agent 经常「忘记」之前说过的偏好把MEMORY.md手动补几条关键事实长期记忆是常驻的不参与检索排序优先级最高。日志文件按天滚动历史日志靠 BM25 向量检索捞所以写日志时尽量把关键决策写清楚检索命中率会高很多。最后提一个容易忽略的点Gateway 的auth.token和 TaoToken 的 API Key 是两套东西。前者是 OpenClaw 内部 WebSocket/HTTP 的鉴权后者是模型通道的鉴权。两个都要设但用途不同别混在一起。Gateway token 用openssl rand -hex 32生成一个随机值就行不需要跟 TaoToken 有任何关联。
1. 为什么要在 OpenClaw 里做统一模型接入OpenClaw 是一个把大模型推理和本地系统操作结合起来的 Agent 运行时框架核心由 Gateway、Agent、Skill、Memory 四大模块组成。Gateway 负责消息调度和路由Agent 负责决策推理Skill 封装具体能力Memory 管理上下文持久化。这套架构跑起来之后真正决定体验上限的其实是模型通道——Agent 每一轮 Lobster Loop 都要调 LLMSkill 执行结果要回灌上下文Memory 检索出来的片段也要塞进 Prompt这些环节全部依赖一个稳定、低延迟、可切换的模型入口。我试过在 OpenClaw 里直接写死某一家厂商的 API Key结果换模型要改源码、加渠道要重新打包、多 Agent 共用一套配置时 Key 到处散落。后来把模型通道统一收敛到 TaoTokenGateway 只认一个 Base URL 和一个 KeyAgent 初始化时通过环境变量注入Skill 和 Memory 的 embedding 也走同一条通道整个链路清爽很多。这篇会按源码结构把四个模块拆开讲重点落在可复制的配置上Gateway 的路由配置、Agent 的初始化参数、Skill 的注册模板、Memory 的持久化设置每一步都给验证动作。适合已经在跑 OpenClaw、想把它接进自己业务链路的开发者也适合刚开始读这套源码、想先跑通再深入的人。下面所有配置都基于 OpenClaw 的openclaw.json和~/.openclaw/workspace/目录结构路径和字段名跟源码保持一致。2. TaoToken 前置准备与 OpenClaw 模型通道配置在动 Gateway 和 Agent 之前先把模型通道准备好。TaoToken 提供统一的 API 入口OpenClaw 的providers/目录下每个 Provider 本质上就是一个 baseURL apiKey model 的组合所以接入方式很直接。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 后面会同时给 Agent 推理、Skill 内部调用、Memory embedding 三处使用所以建议单独建一个项目 Key方便按项目做额度隔离。Base URL 用https://taotoken.net/api注意不要带任何查询参数。OpenClaw 的 Provider 配置里 baseURL 会被拼成{baseURL}/v1/chat/completions这种形式多一个斜杠或少一个斜杠都会导致 404这个坑后面排障章节会细说。模型 ID 方面Agent 主推理建议用带工具调用能力的模型比如claude-sonnet-4-20250514或gpt-4o具体可用列表在 https://taotoken.net/doc 里能查到。Memory 的 embedding 单独配一个 embedding 模型比如text-embedding-3-small1536 维跟 OpenClaw 默认的chunks_vec表结构对得上。配置写进openclaw.json的providers段{ providers: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: claude-sonnet-4-20250514, fast: gpt-4o-mini, embedding: text-embedding-3-small } } }, defaultProvider: taotoken }Key 不要硬编码进 JSON用环境变量注入。在启动脚本或.env里写export TAOTOKEN_API_KEYsk-你的实际KeyOpenClaw 的src/runtime.ts在初始化时会读取${VAR}形式的占位符并做环境变量替换所以这样写是安全的。如果你用 Docker 跑在docker-compose.yml的environment段里加一行TAOTOKEN_API_KEY${TAOTOKEN_API_KEY}宿主机.env里放真实值。验证通道是否通不用等整个 OpenClaw 起来先单独打一个请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }返回里能看到choices[0].message.content就说明 Key 和 Base URL 都对。这一步过了再往下配 Gateway能省掉很多「到底是通道问题还是框架问题」的排查时间。3. Gateway 路由配置与 Agent 初始化参数可复制模板Gateway 是 OpenClaw 的中枢源码在src/gateway/目录下server.ts管 WebSocket 和 HTTP 服务boot.ts管启动引导。它默认监听ws://127.0.0.1:18789和http://127.0.0.1:18793所有渠道消息、Agent 会话、工具调用都从这里过。Gateway 本身不直接调模型它把消息归一化成MsgContext之后路由给 Agent 实例。所以 Gateway 的配置重点是路由规则和鉴权模型通道在 Agent 层注入。openclaw.json里 Gateway 段这样写{ gateway: { host: 127.0.0.1, wsPort: 18789, httpPort: 18793, auth: { mode: token, token: ${GATEWAY_TOKEN} }, routing: { defaultAgent: marketing-agent, rules: [ { match: { channel_id: feishu }, agent: marketing-agent }, { match: { channel_id: telegram, content_prefix: /code }, agent: coding-agent } ] }, rateLimit: { enabled: true, tokensPerMinute: 120 } } }routing.rules是三级路由里的第二层按channel_id和内容前缀把消息分发给不同 Agent。defaultAgent兜底。rateLimit用令牌桶防止某个渠道刷爆。Agent 初始化参数在agents段。OpenClaw 的 Agent Runtime 在src/agents/下Lobster Loop 的循环逻辑在这里Planner 的强规则校验也在这里。初始化时最关键的是把 provider 和 model 指对{ agents: { marketing-agent: { provider: taotoken, model: claude-sonnet-4-20250514, systemPromptFile: ~/.openclaw/workspace/SOUL.md, maxToolRounds: 12, contextWindow: 128000, planner: { enabled: true, blockedTools: [exec, write], requireConfirm: [browser] }, skills: { allowlist: [weather, github, notion, feishu-doc] }, memory: { agentId: marketing-agent, sqlitePath: ~/.openclaw/memory/marketing-agent.sqlite, embeddingProvider: taotoken, embeddingModel: text-embedding-3-small } } } }几个参数值得展开。maxToolRounds对应 Lobster Loop 的最大轮数终止条件复杂任务调十几次工具很常见设 12 是保守值你可以按业务调。planner.blockedTools是安全防线把exec和write拦掉防止 LLM 幻觉直接改本地文件。skills.allowlist是 per-agent 的 Skill 白名单只有列出来的 Skill 会被注入这个 Agent 的 System Prompt。memory.agentId决定 SQLite 文件名每个 Agent 一个独立库互不干扰。embeddingProvider指向 taotoken复用同一个 Key。Gateway 和 Agent 都配好之后启动服务cd openclaw npm run build node dist/entry.js --config ./openclaw.json启动日志里会依次打印加载配置、初始化日志、扫描 skills 目录、初始化 provider、启动 WebSocket 18789、启动 HTTP 18793、注册 Channel 适配器、初始化记忆系统。看到Gateway ready就说明四模块的骨架都起来了。4. Skill 注册模板与 Memory 持久化设置Skill 解决的是「Agent 应该怎么做」每个 Skill 是一个含SKILL.md的目录放在skills/下。SKILL.md分两部分YAML Frontmatter 给 OpenClaw 读元数据Markdown Body 给 Agent 读行为指令。一个可复制的最小 Skill 模板比如做营销文案生成的--- name: marketing-copy description: 根据产品信息生成营销文案支持多平台风格适配。 metadata: openclaw: requires: bins: [] env: [] --- # Marketing Copy Skill 当用户要求生成营销文案时按以下流程执行 1. 先确认产品名称、目标平台、核心卖点三个要素缺哪个问哪个。 2. 根据平台选择风格小红书偏口语化带 emoji 分段公众号偏正式带小标题Twitter 偏短句带钩子。 3. 生成 3 个版本每个版本标注适用场景。 4. 输出格式固定为标题 / 正文 / 标签建议。 调用 read 工具读取产品资料文件不要凭空编造卖点。Frontmatter 里的metadata.openclaw.requires是门控条件bins列依赖的二进制env列需要的环境变量不满足条件的 Skill 会被过滤掉不会注入 Prompt。这个机制在多环境部署时很有用。Skill 的加载优先级是内置skills/目录 → 用户本地覆盖 → per-agent allowlist。同名 Skill 本地覆盖内置。加载链路就三步扫描目录、解析 SKILL.md 提取 namedescriptionbody、格式化成 XML 片段拼进 System Prompt。Memory 的持久化设置分两块工作区文件结构和 SQLite 索引。工作区在~/.openclaw/workspace/~/.openclaw/workspace/ ├── MEMORY.md # 长期记忆偏好、决策、持久事实 ├── memory/ │ ├── 2026-03-05.md # 今日日志短期记忆 │ └── 2026-03-04.md # 昨日日志 ├── sessions/ # 会话存档近端记忆 ├── USER.md # 用户身份 └── SOUL.md # Agent 人格设定新会话启动时OpenClaw 自动加载「今天昨天」的日志作为短期记忆MEMORY.md作为长期记忆常驻sessions/里的历史会话按需检索。SQLite 索引在~/.openclaw/memory/{agentId}.sqlite核心表结构CREATE TABLE files ( id INTEGER PRIMARY KEY, path TEXT UNIQUE, mtime INTEGER, size INTEGER, hash TEXT ); CREATE TABLE chunks ( id INTEGER PRIMARY KEY, file_id INTEGER, start_line INTEGER, end_line INTEGER, text TEXT, hash TEXT UNIQUE, embedding TEXT ); CREATE VIRTUAL TABLE chunks_fts USING fts5(text, contentchunks); CREATE VIRTUAL TABLE chunks_vec USING vec0(embedding float[1536]);files表用mtime和hash做增量索引只重新索引变更的文件。chunks表存分块内容和向量hash做跨文件去重。chunks_fts是 BM25 全文检索chunks_vec是向量检索两路并行后合并加权排序。embedding 走 TaoToken 的话chunks_vec的维度要跟模型对上text-embedding-3-small是 1536 维跟上面建表语句一致。如果换text-embedding-3-large的 3072 维建表语句里的float[1536]要改否则插入会报维度不匹配。Memory 的检索配置在openclaw.json的memory段{ memory: { retrieval: { topK: 8, bm25Weight: 0.4, vectorWeight: 0.6, minScore: 0.3 }, indexing: { chunkSize: 512, chunkOverlap: 64, watch: true } } }bm25Weight和vectorWeight控制两路检索结果的合并权重关键词查询多的场景把 bm25 调高语义查询多的把 vector 调高。watch: true开启文件监听工作区文件一改就触发增量索引。5. 四模块协同验证与常见报错排查配置写完启动服务按 Gateway → Agent → Skill → Memory 的顺序逐个验证。Gateway 转发日志。启动后看控制台正常会打印[gateway] WebSocket server listening on ws://127.0.0.1:18789 [gateway] HTTP server listening on http://127.0.0.1:18793 [gateway] routing rules loaded: 2 [gateway] channel adapters registered: feishu, telegram发一条测试消息日志里应该出现[gateway] MsgContext normalized和[gateway] routed to agentmarketing-agent。如果只看到 normalized 没有 routed说明routing.rules的 match 条件没命中检查channel_id拼写。Agent 任务响应。Gateway 路由过去之后Agent 的 Lobster Loop 开始跑日志里会看到[agent] Think→[agent] Act→[agent] Observe的循环。如果卡在 Think 不动多半是模型通道问题回到第 2 节的 curl 验证。Skill 调用链路。Agent 决定调 Skill 时日志里出现[skill] loading marketing-copy和[skill] injected into system prompt。如果 Skill 没被加载检查skills.allowlist里有没有列以及SKILL.md的 frontmatter 格式对不对。Memory 读写结果。Agent 每轮结束会把关键信息写进当日日志日志里出现[memory] appended to 2026-03-05.md。检索时出现[memory] bm25 hits3 vector hits5 merged6。如果 vector hits0检查 embedding 模型和维度。下面是我踩过的几个真实报错对照排查。401 Unauthorized。日志里[provider] request failed status401。原因通常是 Key 没注入成功${TAOTOKEN_API_KEY}没被替换。检查启动环境里有没有exportDocker 里检查environment段。还有一种情况是 Key 复制时带了空格用echo $TAOTOKEN_API_KEY | wc -c看长度对不对。local proxy failed / ECONNREFUSED。日志里[provider] local proxy failed。这是 baseURL 写错比如写成了https://taotoken.net/api/带尾斜杠或者写成了https://taotoken.net少了/api。正确值是https://taotoken.net/api不带尾斜杠。reading choices 报错。日志里Cannot read properties of undefined (reading choices)。这是响应体结构跟预期不符通常是模型 ID 写错返回了错误对象而不是正常响应。用 curl 单独打一次确认模型 ID 在 https://taotoken.net/doc 的列表里。OAuth / token expired。日志里[provider] oauth token expired。OpenClaw 某些 Provider 走 OAuth 流程taotoken 走的是 API Key 模式如果出现这个报错说明type字段写错了应该是openai-compatible而不是oauth。Skill 没生效。Agent 回复里完全没提 Skill 的流程。检查SKILL.md的 frontmatter 有没有---包裹YAML 缩进对不对。OpenClaw 解析失败时会静默跳过日志里不会有明显报错可以在启动时加--verbose看扫描结果。Memory 检索为空。[memory] bm25 hits0 vector hits0。检查~/.openclaw/workspace/memory/下有没有当日日志文件以及 SQLite 文件有没有生成。如果 SQLite 生成了但 chunks 表为空说明索引没跑手动触发一次node dist/cli.js memory reindex --agent marketing-agent。Gateway 端口占用。EADDRINUSE: address already in use 127.0.0.1:18789。上次进程没退干净lsof -i :18789找到 PID 杀掉或者改wsPort换端口。Agent 循环不终止。日志里 Lobster Loop 一直转超过maxToolRounds才停。这是 Planner 没拦住检查planner.enabled是不是 true以及blockedTools有没有覆盖到出问题的工具。上下文超限。日志里context length exceeded, compressing。这是 Memory 的动态上下文管理在压缩正常行为。如果频繁触发把memory.retrieval.topK调小或者把chunkSize调大减少碎片。6. 把四模块接进你的业务链路跑通之后下一步是把 OpenClaw 接进实际业务。Gateway 的 HTTP 接口http://127.0.0.1:18793可以直接被外部系统调用用POST /v1/message发消息body 里带channel_id和contentGateway 会按路由规则分发给对应 Agent。这样你的 CRM、工单系统、营销后台都能通过一个 HTTP 接口触发 Agent。多 Agent 场景下每个 Agent 在agents段独立配置 provider、model、skills、memory共用同一个 TaoToken Key。额度按项目 Key 隔离在 https://taotoken.net/console 里能看到每个 Key 的调用量和费用。长期跑编码类 Agent 的话Coding Plan 的额度模型比按量计费更划算具体在 https://taotoken.net/coding-plan 看。Skill 的扩展是这套架构里最灵活的部分。你不需要改 Gateway 或 Agent 的源码只要在skills/下新建目录、写SKILL.md、加进allowlist重启服务就生效。我建议把业务相关的 Skill 单独放一个目录用metadata.openclaw.requires.env做环境门控测试环境和生产环境用不同的 Skill 集合。Memory 的调优是个持续过程。初期topK设小一点8 左右观察 Agent 回复质量。如果发现 Agent 经常「忘记」之前说过的偏好把MEMORY.md手动补几条关键事实长期记忆是常驻的不参与检索排序优先级最高。日志文件按天滚动历史日志靠 BM25 向量检索捞所以写日志时尽量把关键决策写清楚检索命中率会高很多。最后提一个容易忽略的点Gateway 的auth.token和 TaoToken 的 API Key 是两套东西。前者是 OpenClaw 内部 WebSocket/HTTP 的鉴权后者是模型通道的鉴权。两个都要设但用途不同别混在一起。Gateway token 用openssl rand -hex 32生成一个随机值就行不需要跟 TaoToken 有任何关联。
![[实测可用 v2.7.5] 桌面端 Open Claw 搭建流程全程图文教程：把 settings 改到 TaoToken](http://pic.xiahunao.cn/yaotu/[实测可用 v2.7.5] 桌面端 Open Claw 搭建流程全程图文教程：把 settings 改到 TaoToken)
