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 为什么会“看起来不工作”
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。
官方资料入口
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，最后查路径、环境变量、凭证、依赖和资源。这样能把“工具根本不可用”和“工具可用但命令执行失败”分开，排查成本最低。