> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

按安装、登录、交互和插件分类排查常见问题。提交反馈时请附版本、操作步骤和脱敏后的错误信息。

## 安装与升级

### 安装后找不到 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/`。自定义路径和清理方式见[数据路径](/docs/zh/step-code/configuration/data-paths)。

### 本地 Agent 是否意味着代码不会发送出去？

不是。模型调用会发送任务相关内容，工具和插件也可能访问外部服务。只读工具不修改文件，但读取内容仍可能进入模型上下文。处理敏感项目时应先确认供应商、数据处理要求和可访问范围。

### 如何关闭遥测？

在全局 `config.toml` 设置：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[telemetry]
enabled = false
```

遥测包含设备与账号标识，不含提示词、代码与路径。关闭遥测不会关闭模型请求，也不替代对主动提交反馈内容的检查。

## 反馈

使用 `/feedback` 提交问题。建议附上 `step --version` 的结果、操作系统、终端类型、复现步骤，以及脱敏后的错误信息。分享会话导出或日志前检查代码、路径和凭据。