同一条命令在本地终端能跑，Agent 中却报语法错误怎么办？
先确认 Agent 实际使用的 shell，再修正参数、引用和路径。
运行入口可能使用不同 shell
不要只根据操作系统或你手动打开的终端名称判断 Agent 的 shell。Windows 的桌面和 CLI 实际实现都可优先选 Git Bash，未找到时再使用 cmd；不是固定 PowerShell。Unix 桌面会选择主机可用的用户 shell，CLI 的普通命令路径使用 bash。换入口后，相同字符串的解释方式可能变化。
先检查路径和引用方式
让 Agent 先确认实际 shell，再处理含空格的路径、带问号或连接符的 URL，以及平台特有的参数语法。某些 shell 会把未引用的字符当作通配符，导致看起来像文件不存在的错误。不要仅修改一个可疑字符就继续批量执行，可以先把任务拆成一条可验证的只读命令观察结果。
区分语法问题与工具缺失
如果报错是找不到程序，先检查工具安装和路径；如果是访问拒绝，应检查系统权限；只有解析错误才重点修正 shell 写法。即使命令最后一段显示成功，也应检查前面的错误输出，避免忽略部分失败。确认单步行为正确后再恢复完整任务，不必为此重置连接令牌或默认提高客户端权限。