OpenClaw WSL2 与 Codex Tool Calls 排查指南
如果 OpenClaw WSL2 环境里的 Codex tool calls 看起来不工作，先不要把问题简单归因于 “Codex 坏了”。更高概率的问题是运行时、路径、sandbox、工具暴露层或 AGENTS.md / Agent Skills 约束没有对齐。
先选对运行路径
| 路径 | 适合场景 | 第一检查项 |
|---|---|---|
| Native Windows | 默认 Windows Codex 工作流，项目依赖主要在 Windows 侧。 | sandbox、工作目录、PowerShell 命令。 |
| WSL2 | 仓库、Shell、依赖、CI 假设或 Linux-native 工具链已经在 WSL2。 | distro 路径、包管理器、环境变量。 |
| OpenClaw Codex harness | OpenClaw 负责编排消息和会话，Codex 负责底层 coding session。 | 当前工具列表、审批策略、会话来源。 |
正确模型：先分层，再排查
Tool call 不是一个单点能力，而是多层系统共同工作的结果。Windows / WSL2 决定命令和路径， Codex CLI 或 OpenClaw Codex harness 决定会话形态，Codex-native tools、OpenClaw dynamic tools、MCP/plugin tools 决定可用工具面，AGENTS.md 和 Agent Skills 决定工作流约束。
User -> OpenClaw chat/session -> Codex harness -> Codex tool calls -> local shell/files/MCP/plugin surfacesWSL2 什么时候值得用
WSL2 的价值是让 Linux-native 工作流保持一致，不是替代所有 Windows 原生开发。项目已经在 Linux 路径、依赖依赖 Bash 行为、CI 和线上环境都是 Linux，或者 Windows 原生 sandbox 行为和项目不匹配时，WSL2 才是更清晰的选择。
不要混用路径
最常见的低级错误是仓库在 WSL2，配置却指向 Windows 路径，或者反过来。先用一个 harmless list/read 命令确认 agent 看到的目录就是你以为的目录。
Codex Tool Calls 为什么会“看起来不工作”
Codex MCP tools not showing 时先查什么？
先把“工具没有暴露”和“工具调用失败”分开。打开当前会话的 tools list，确认你期待的是 Codex-native tool、OpenClaw dynamic tool，还是 MCP/plugin tool；如果列表里没有，就不要继续调 prompt，而是回到 harness、plugin 安装状态、MCP server 启动状态和本轮会话配置。
Windows 和 WSL2 路径混用怎么定位？
路径混用通常表现为本地能打开文件，agent 却读不到；或者命令能运行，凭证、配置、缓存位置却不对。 排查时先打印当前工作目录，再分别验证仓库路径、配置文件路径、包管理器路径和凭证路径，避免把 `/mnt/c/...`、`C:\...` 和 Linux home 目录混成一个环境。
最小验证
用同一个 session 完成 `pwd`、只读文件检查、包管理器版本检查和一次无副作用命令。如果其中任一步跨到另一个路径体系， 先修路径和环境变量，再继续排 tool calls。
OpenClaw dynamic tools 和 MCP tools 有什么区别？
OpenClaw dynamic tools 是当前 OpenClaw 会话按运行上下文暴露的能力，例如消息、会话、媒体、节点或平台编排工具； MCP tools 通常来自独立 MCP server 或 plugin connector。两者都可能出现在 agent 的工具面里，但加载来源、鉴权、 生命周期和故障边界不同。
| 类型 | 先查什么 | 常见故障 |
|---|---|---|
| OpenClaw dynamic tools | 当前会话、账号、节点和权限上下文。 | 工具未暴露、账号缺失、目标 channel 或 node 不可用。 |
| MCP/plugin tools | server 是否启动、配置是否加载、运行环境是否一致。 | server 未加载、路径错位、凭证缺失、connector 未授权。 |
AGENTS.md 与 Agent Skills 怎么配合
AGENTS.md 负责项目级规则，比如测试命令、分支策略、代码风格和团队约束。Agent Skills 负责可复用任务流，比如 SEO audit、browser automation、公众号发布、数据抓取或某个工具链的标准步骤。
从 skill-cn 的内容模型看，Agent Skills directory 的价值不只是列出工具，而是把 Skill 连接到真实场景和实践：Skill x scenario = practice。
最小可复现排查流程
- 确认当前是 Windows 原生还是 WSL2。
- 确认工作目录、仓库路径和包管理器位置。
- 确认运行时是 Codex CLI、Codex app 还是 OpenClaw Codex harness。
- 执行一次无副作用的文件读取或目录列表命令。
- 在临时目录执行一次无副作用写入。
- 检查当前会话暴露了哪些 dynamic tools、MCP/plugin tools 和 Skill 工作流。
- 读取相关 AGENTS.md 和已选 Skill 的约束。
- 把错误归类为 missing tool、permission denied、command failure、timeout 或 resource exhaustion。
相关实践入口
排查完成后，下一步是把可用 tool calls 接到具体任务。下面这些实践页能帮助你从 Codex、 OpenClaw 和 Agent Skills 的概念，落到真实工作流。
官方资料入口
FAQ
Codex 在 Windows 上应该用原生还是 WSL2？
优先按当前项目环境选择。项目和依赖都在 Windows 原生环境时，直接用 Windows 更简单；仓库、Shell、包管理器、CI 假设都在 Linux 环境时，WSL2 更稳定。不要把 WSL2 当成万能修复项，先确认路径、权限和运行时一致。
OpenClaw Codex harness 和直接运行 Codex CLI 有什么区别？
直接运行 Codex CLI 时，Codex 主要面对本机命令、文件和当前 CLI 配置。OpenClaw Codex harness 场景下，Codex 负责底层 coding session，OpenClaw 负责消息通道、会话编排、动态工具、审批和 transcript mirror，所以可见工具和权限策略可能不同。
为什么 Codex 看不到 MCP/plugin tools？
常见原因包括当前会话不是预期的 harness、工具没有在本轮暴露、MCP/plugin server 未被当前运行时加载、审批或 sandbox 策略限制、以及 Windows 路径和 WSL2 路径混用。先确认工具列表，再确认运行时和配置文件。
AGENTS.md 和 Agent Skills 谁负责什么？
AGENTS.md 更适合放项目级、团队级、仓库级约束，例如测试命令、分支策略和代码风格。Agent Skills 更适合沉淀可复用工作流，例如浏览器自动化、SEO audit、公众号发布或特定工具链操作。
Agent Skills directory 和普通工具目录有什么区别？
普通工具目录回答“有什么工具”，Agent Skills directory 更应该回答“在什么场景用什么 Skill，以及怎么复用”。skill-cn 的核心模型是 Skill x scenario = practice，重点是把工具和真实任务连接起来。
Tool call 失败时应该先查权限、路径还是工具暴露？
先查工具是否暴露，再查权限和 sandbox，最后查路径、环境变量、凭证、依赖和资源。这样能把“工具根本不可用”和“工具可用但命令执行失败”分开，排查成本最低。