OpenClaw-RL 源码阅读笔记（1）基础：Agentic RL 与 OPD 的配置骨架怎么搭

1. 从一次跑不通的 OpenClaw-RL 说起OpenClaw-RL 是一个面向 Agentic RL 的在线强化学习框架核心思路是把 Agent 每次动作之后收到的「下一状态」——用户回复、工具输出、终端报错、GUI 变化——当成训练信号回收利用。它提供三种模式openclaw-rlBinary RL / GRPO、openclaw-opdHindsight-Guided On-Policy Distillation、openclaw-combine两者联合。适合谁适合已经了解 PPO/GRPO 基本概念、想读源码但被一堆配置文件劝退的工程师也适合想把 Agent 接进训练闭环、却卡在「入口在哪、Key 填哪」的实践者。我第一次拉下仓库时最直接的感受不是算法难而是配置骨架散settings.json、config.toml、环境变量、CC Switch、Cline 各管一段谁先谁后没有一张图。结果就是openclaw-rl能起来openclaw-opd报 401或者 rollout 跑通了PRM 评分一直 pending。这篇笔记只做一件事把基础篇的配置骨架搭起来让最小可运行环境先跑通再谈读openclaw_api_server.py那 730 行。我会按「问题场景 → TaoToken 前置 → 可复制配置 → 验证请求 → 错排查 → 下一步」的顺序走。所有 Key/API 通道统一走 TaoToken这样 RL、OPD、Combine 三个 server 不用各配一套上游省掉大量对不齐的麻烦。2. TaoToken 前置统一 Key 与 API 通道OpenClaw-RL 的推理侧默认对接 SGLang但 PRM 评分、Hint Judge、Teacher log-probs 这些环节都要调外部模型。如果每个组件各填一个 base_url 和 key配置会迅速失控。我的做法是所有模型调用统一走 TaoToken 的 API 通道只维护一份 Key。TaoToken 在这里扮演的是「统一入口」你拿到一个 API Key配一个 base_urlRL server、OPD server、Combine server 以及 Cline 这类编辑器插件都指向同一个地址。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意这个不带 UTM。具体要准备的东西一个 API Key在控制台创建见 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 只放在本地环境变量或.env不要写进会提交到 git 的settings.json。我见过有人把 key 直接塞进 config 然后 push后面只能全部轮换。如果你只是想先验证模型通道是否通不用急着配 RL直接去模型对话页发一条消息即可https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。通道通了再往下搭骨架。3. 可复制配置settings.json 与 config.toml 骨架OpenClaw-RL 的配置分两层应用层用settings.jsonOpenClaw App 侧TypeScript训练/服务层用config.tomlPython 侧Slime/Megatron 风格。两者通过环境变量桥接。下面是我实测能跑通的最小骨架。3.1 settings.json应用侧入口这个文件决定 OpenClaw App 把请求发到哪、用哪个模型。关键字段是baseUrl和apiKey都指向 TaoToken。{ provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514, timeoutMs: 120000, retry: { maxAttempts: 3, backoffMs: 800 }, rollout: { endpoint: http://127.0.0.1:8780, sessionHeader: X-OpenClaw-Session } }这里${TAOTOKEN_API_KEY}是占位实际从环境变量注入。rollout.endpoint指向本地 RL server 的 API 端口OpenClaw App 的每轮对话会打到这个端口由 server 决定是否转成训练样本。3.2 config.toml训练与服务侧骨架Python 侧的config.toml管三件事推理服务SGLang、训练Megatron、以及 OpenClaw 特有的 PRM/OPD 参数。最小骨架如下[server] host 0.0.0.0 port 8780 mode openclaw-rl # 可选 openclaw-rl / openclaw-opd / openclaw-combine [upstream] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY prm_model claude-sonnet-4-20250514 hint_model claude-sonnet-4-20250514 teacher_model claude-sonnet-4-20250514 [prm] enable true votes 3 # PRM_M多数投票次数 timeout_s 60 [opd] enable false # openclaw-opd / combine 时置 true hint_min_len 10 topk 20 [combine] w_rl 1.0 # OPENCLAW_COMBINE_W_RL w_opd 1.0 # OPENCLAW_COMBINE_W_OPD [rollout] function_path openclaw_rollout.generate_rollout_openclaw passive true # 被动等待用户驱动三个 mode 的差异只在[opd]和[combine]段是否启用。openclaw-rl只用 PRMopenclaw-opd关 PRM、开 OPDopenclaw-combine两个都开。3.3 环境变量把两层粘起来export TAOTOKEN_API_KEYsk-你的key export OPENCLAW_MODEopenclaw-rl export OPENCLAW_COMBINE_W_RL1.0 export OPENCLAW_COMBINE_W_OPD1.0 export PRM_M3提示config.toml里的api_key_env只写变量名不写值。这样同一份 config 可以在不同机器上复用Key 走各自的 shell 环境。3.4 CC Switch 与 Cline 的接入CC Switch 用来在多个 provider 配置间切换。给它加一个 TaoToken profile{ name: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, models: [claude-sonnet-4-20250514, gpt-4o] }ClineVS Code 插件里选 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填同一个。这样你在编辑器里调试 Agent 逻辑时和 RL server 走的是同一条通道行为一致排查问题时不会因为「编辑器能通、server 不通」而绕弯。4. 验证请求从单轮到 PRM 评分配置搭好后别急着开训练。按下面三步验证每步都有明确的成功标志。4.1 第一步验证模型通道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: reply with OK}] } | head -c 300返回里有choices[0].message.content就算通。这一步不通后面全白搭。4.2 第二步启动 RL server 并打一轮python -m openclaw_rl.openclaw_api_server --config config.toml启动日志里应该能看到submission_enabled初始为 True、PRM votes3。然后模拟一轮对话curl -s http://127.0.0.1:8780/v1/chat \ -H Content-Type: application/json \ -H X-OpenClaw-Session: test-session-001 \ -d {messages:[{role:user,content:写一个快速排序}]}成功标志返回 assistant 回复同时 server 日志出现pending turn stored。此时数据进了_pending_turn_data等下一轮触发 PRM。4.3 第三步触发 PRM 评分再发一轮模拟用户反馈curl -s http://127.0.0.1:8780/v1/chat \ -H Content-Type: application/json \ -H X-OpenClaw-Session: test-session-001 \ -d {messages:[{role:user,content:不对我要的是归并排序}]}成功标志日志出现_flush_pending_record→_fire_prm_scoring→_maybe_submit_ready_samples最终打印sample submitted, reward-1。这说明「下一状态信号 → PRM 评分 → 训练样本」这条链路通了。注意PRM 是异步的sample submitted可能比 HTTP 返回晚几秒。别看到 HTTP 200 就以为评分完成了盯日志。5. 本篇常见错排查5.1 401 / 403Key 没注入最常见。config.toml里写了api_key_env TAOTOKEN_API_KEY但 shell 里没 export或者用了sudo导致环境变量丢失。检查echo $TAOTOKEN_API_KEY | head -c 8输出为空就是没注入。另外确认 base_url 是https://taotoken.net/api不要多加/v1后缀导致路径重复。5.2 PRM 一直 pending样本不提交日志停在pending turn stored不动。原因通常是PRM_M次查询里有超时asyncio.gather卡住。把[prm].timeout_s调大或临时把votes降到 1 验证链路。还有一种情况session id 没带server 无法把两轮关联到同一 session自然不触发 flush。检查请求头X-OpenClaw-Session。5.3 OPD 模式报 hint 为空openclaw-opd下日志出现no valid hint。这是正常的——OPD 只对「下一状态包含明确指导信息」的 turn 生效。如果用户回复是「谢谢」hint judge 会拒绝该 turn 不产生 OPD 样本。想验证 OPD 链路用带具体纠正的回复比如「你应该先检查文件是否存在」。5.4 Combine 模式 advantage 全为 0openclaw-combine下如果w_rl和w_opd都是 0advantage 恒为 0训练不动。检查环境变量OPENCLAW_COMBINE_W_RL/OPENCLAW_COMBINE_W_OPD是否被覆盖成 0。默认都是 1.0。5.5 Cline 能通但 server 不通两者 base_url 一样却结果不同多半是 Cline 用了自己的代理设置或证书。对比两边的实际请求Cline 侧看输出面板的 request logserver 侧加--log-level debug。差异通常在 header 或超时上。6. 下一步读源码与长期编码骨架跑通后读源码的顺序建议是先openclaw_api_server.py的_flush_pending_record和_maybe_submit_ready_samples理解双缓冲异步状态机再看openclaw_opd_api_server.py的 hint judge 流程最后看combine_loss.py那 140 行理解 RL 和 OPD 如何在同一个 PPO 更新里解耦。如果你打算长期在这套框架上做 Agent 编码实验建议把 Key 和通道固定下来用 Coding Plan 管理额度与模型切换https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节随时查文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。我踩过的一个坑一开始把 PRM 和 Hint Judge 配成不同 provider结果两边的超时和重试策略不一致排查异步问题时非常痛苦。统一走 TaoToken 之后至少「通道」这个变量被消掉了剩下的都是框架本身的问题好定位得多。