Step Code 在终端报错时，报错来源通常落在两处：本地运行环境没准备好（命令找不到、依赖缺失、路径或环境变量不对），或者模型侧配置没填对（模型名、访问凭据、请求地址、参数格式）。分不清这两类，就容易在错误的方向上反复改配置。判断顺序可以按报错发生的阶段来分：程序连加载都没完成就失败，先查本地环境；程序已经起来、在连接模型或返回结果时失败，先查模型侧配置。下面按四步走，每一步给可执行的检查动作和验证方式。

先看报错第一行和退出码：启动阶段失败（命令找不到、模块导入失败、配置读取失败）通常归到本地环境，退出码非零且发生在加载阶段；任务执行中失败（连接超时、鉴权失败、响应结构异常）更像是模型侧配置或网络问题。这个分法适用于能拿到完整终端输出的场景；如果日志被脚本截断或包装过，先让原始报错露出来再判断。

先读报错里的第一行和退出码

终端报错往往很长，但决定性信息集中在前几行和进程退出码上。建议先把完整输出留下来，再分段看：

stepcode ... 2>&1 | tee run.log
head -20 run.log
tail -20 run.log
echo $?      # Windows CMD 用 echo %ERRORLEVEL%

启动失败的特征是：可执行命令找不到、运行时/解释器版本不匹配、依赖模块导入失败、配置文件解析失败。这类错误通常发生在程序发出任何网络请求之前，日志里看不到连接动作。执行中途失败的特征是：报错出现在连接、鉴权、流式返回或超时阶段，程序已经加载完成，日志中能看到请求已经发出的痕迹。先做这个判断，能省掉一半无关排查。

检查本地命令与运行环境

确认命令本身可用，再谈配置。常用动作：

• 版本与帮助：stepcode `--version`、stepcode `--help`；运行时版本按实际技术栈查，如 node -v 或 python -V。
• 命令定位：which stepcode，Windows 用 where stepcode。报 command not found 或“不是内部或外部命令”，一般是可执行文件不在 PATH，或者安装目录没加进 PATH。
• 环境变量：env | grep -i step；PowerShell 可用 Get-ChildItem Env: | Where-Object Name -like '*STEP*'。逐个确认变量名没拼错，值里没有多余空格或引号。

路径问题的典型表现：配置里写死的绝对路径换机器后不存在；相对路径在不同工作目录下失效，建议先 pwd 确认当前目录。权限问题表现为可执行文件无法运行或配置无法读取。依赖缺失表现为模块导入报错或共享库找不到，按报错提示补齐依赖或对齐运行时版本即可。

核对模型侧配置项

配置文件位置常见于用户主目录下的隐藏目录、项目根目录，或由 `--config` 参数指向。不要凭记忆改文件，先看启动日志里类似 “loading config from …” 的记录，确认程序实际读取的是哪个路径。需要核对的字段通常包括：

• 模型名或模型 ID
• 访问凭据（API key 或 token）
• 请求地址（base URL / endpoint）
• 请求参数（超时、最大输出长度等）

字段名以配置样例或 `--help` 输出为准。写错时的报错特征可以粗略对照：凭据错误一般返回 401 或 unauthorized、invalid api key，说明请求已经发出但没通过鉴权；模型名写错常见 404 或 model not found；地址写错表现为连接被拒绝、域名解析失败或证书校验失败，通常是连不上而不是返回业务错误；参数格式错误多为 400，提示字段类型或必填项不符。还要注意配置优先级：环境变量一般覆盖配置文件，命令行参数又可能覆盖环境变量，改之前先确认当前生效的是哪一层。

改完配置后跑一次最小验证

不要直接上完整任务，先做两步最小验证。第一步是最小启动，确认配置能被解析：

stepcode `--version`
stepcode config validate   # 若该子命令存在，以 `--help` 输出为准

第二步是最小请求，用一条不依赖具体业务的调用确认能连上模型并拿到响应，例如 stepcode run "ping"，或先用 dry-run / 连接检查参数。

成功输出特征：进程退出码为 0，日志里没有 error 级别记录，返回内容是从模型正常返回的文本，而不是空值或错误结构。仍然失败时，回落做法是一次只改一个变量：固定配置只换环境，或固定环境只换配置，用对照方式定位。同时把日志级别调高到 debug 或 verbose，看失败卡在哪一步——请求已经发出、返回是 4xx，问题在配置字段；请求根本没发出去，回到本地命令与网络环境检查。