安装与升级
安装后找不到 step？
重新打开终端，使 PATH 配置生效。默认安装目录为~/.stepcode/bin；Windows 为 %USERPROFILE%\.stepcode\bin。检查可执行文件是否存在，以及是否配置了自定义安装路径。
安装脚本写入的 PATH 块带标记，可检查对应 Shell 登录配置。
如何升级？
运行step update，更新过程包含 checksum 校验、冒烟测试和失败回滚。
登录与模型
/login 中应该选择哪个平台？
国内阶跃订阅选择 Step Plan，海外订阅选择 Step Plan Oversea。按量付费使用对应地区的开放平台 API Key。其他供应商选择其对应入口，不能混用密钥。更新环境变量后仍在使用旧密钥？
检查~/.stepcode/auth.json 是否已有对应平台的凭据。文件凭据优先于环境变量，命令行 --api-key 又优先于文件凭据。调整后从已设置变量的终端重启。
自定义模型没有出现在 /model？
检查models.json 的 JSON 格式、模型 ID 和平台配置。本地无鉴权服务也需要非空 apiKey 占位值。保存后重新打开 /model；涉及登录和环境变量时还需重启。
切换模型后用量增加？
切换模型可能无法复用之前的提示词缓存，价格和分词方式也可能不同。查看当前模型、会话用量和账户账单，不要仅根据对话长度判断成本。交互
Shift+Enter 发送了消息，而没有换行？
改用 Ctrl+J 或 Alt+Enter。部分终端会拦截组合键，需要调整终端按键转发或 Step Code 的键位配置。为什么工具不弹审批？
默认模式是 Bypass。运行/permissions 选择 Ask；需要只读工具时选择 Read Only。危险命令规则命中的操作会另行处理，但规则不是覆盖所有风险的安全沙箱。
粘贴图片失败？
使用 Ctrl+V，Windows / WSL 使用 Alt+V。确认剪贴板中确实是图片、终端快捷键没有冲突，并选择支持图片的模型。可改用step @screenshot.png 引用文件。
终端图片协议影响内联显示，不等于所有粘贴和图片输入都必须依赖同一协议。
MCP 与插件
MCP 显示 failed？
运行step mcp get <名称> 检查声明。stdio 服务重点检查命令路径、参数、依赖和环境变量；HTTP 服务检查地址、鉴权变量和授权状态。不要在反馈中粘贴真实 token。
安装插件后 MCP 没有生效？
安装或卸载插件后需重启 Step Code，再通过/mcp 检查。确认程序已安装，项目已信任，服务器没有被设置为 enabled = false。
数据与隐私
数据保存在哪里？
默认全局数据在~/.stepcode/，项目资源在项目 .stepcode/。自定义路径和清理方式见数据路径。
本地 Agent 是否意味着代码不会发送出去？
不是。模型调用会发送任务相关内容，工具和插件也可能访问外部服务。只读工具不修改文件，但读取内容仍可能进入模型上下文。处理敏感项目时应先确认供应商、数据处理要求和可访问范围。如何关闭遥测？
在全局config.toml 设置：
反馈
使用/feedback 提交问题。建议附上 step --version 的结果、操作系统、终端类型、复现步骤，以及脱敏后的错误信息。分享会话导出或日志前检查代码、路径和凭据。