Question 1

macOS 如何安装 OpenCode？

Accepted Answer

有两种安装方式：

方式一：Homebrew（推荐）

方式二：一键安装脚本

安装完成后，运行 opencode --version 验证安装是否成功。

Question 2

Windows 如何安装 OpenCode？

Accepted Answer

方式一：Winget（推荐）

方式二：Scoop

方式三：手动下载
从 [GitHub Releases](https://github.com/anomalyco/opencode/releases) 下载 Windows 版本，解压后添加到 PATH。

Question 3

Linux 如何安装 OpenCode？

Accepted Answer

一键安装脚本（通用）

Arch Linux（AUR）

Nix

Question 4

如何更新 OpenCode 到最新版本？

Accepted Answer

更新方式取决于你的安装方式：

Homebrew

Winget

一键脚本安装的用户

重新运行安装脚本即可自动更新。

Question 5

如何配置 API 密钥？

Accepted Answer

方式一：使用 /connect 命令（推荐）

按照交互提示选择提供商并输入 API 密钥。

方式二：环境变量

方式三：配置文件
编辑 ~/.config/opencode/config.json：

Question 6

如何配置代理？国内用户如何使用？

Accepted Answer

OpenCode 支持 HTTP/HTTPS/SOCKS 代理。

方式一：环境变量

方式二：配置文件
在 ~/.config/opencode/config.json 中添加：

国内用户建议
1. 使用代理访问 API
2. 或选择支持国内访问的提供商（如 Azure OpenAI、阿里云等）

Question 7

如何切换 AI 模型？

Accepted Answer

运行时切换
在 OpenCode 中输入 /model 命令，然后选择模型。

配置默认模型
编辑 ~/.config/opencode/config.json：

常用模型
- claude-sonnet-4-20250514 - Claude Sonnet 4（推荐）
- gpt-4o - GPT-4o
- gemini-2.0-flash - Gemini 2.0 Flash

Question 8

什么是 Zen 模式？如何使用？

Accepted Answer

Zen 是 OpenCode 提供的免费精选模型列表，无需自己的 API 密钥即可使用。

启用 Zen

特点
- 免费使用，无需 API 密钥
- 精选高质量模型
- 适合入门体验

限制
- 有使用配额限制
- 可能需要排队等待
- 生产环境建议使用自己的 API

Question 9

如何让 AI 读取项目文件？

Accepted Answer

使用 @ 符号引用文件

引用多个文件

引用整个目录

AI 会自动读取引用的文件内容并理解上下文。

Question 10

有哪些常用的斜杠命令？

Accepted Answer

基础命令 - /help - 显示帮助 - /clear - 清空对话 - /undo - 撤销上一步操作 - /model - 切换模型 - /connect - 连接 AI 提供商文件操作 - /add - 添加文件到上下文 - /remove - 从上下文移除文件会话管理 - /save - 保存当前会话 - /load - 加载历史会话 - /sessions - 查看所有会话

Question 11

计划模式和构建模式有什么区别？

Accepted Answer

OpenCode 有两种工作模式，按 Tab 键切换：

计划模式（Plan Mode）
- 用于设计和讨论方案
- AI 不会直接修改文件
- 适合：需求分析、架构设计、代码审查

构建模式（Build Mode）
- AI 可以执行命令和修改文件
- 实际进行代码开发
- 适合：编写代码、修复 Bug、重构

建议流程
1. 先在计划模式讨论方案
2. 确认后切换到构建模式执行

Question 12

操作出错了如何撤销？

Accepted Answer

撤销 AI 的最近操作

撤销多步操作
连续多次输入 /undo 可以逐步撤销。

Git 级别撤销
如果 AI 已经提交了代码：

建议
- 重要操作前先确认方案
- 使用 Git 分支隔离实验性更改

Question 13

连接失败 / 网络超时怎么办？

Accepted Answer

1. 检查网络连接

2. 检查代理配置
确保代理正确配置：

3. 检查 API 密钥
确认密钥正确且有效：

4. 尝试其他提供商
如果某个提供商不可用，可以切换到其他提供商。

5. 查看详细日志

Question 14

API 密钥无效或余额不足怎么办？

Accepted Answer

API 密钥无效
1. 检查密钥是否复制完整（无多余空格）
2. 确认密钥未过期或被撤销
3. 重新生成密钥并配置

余额不足
1. 登录 API 提供商控制台查看余额
2. 充值或升级套餐
3. 考虑使用 Zen 模式（免费）

查看当前配置

Question 15

AI 无法修改文件 / 权限被拒绝？

Accepted Answer

检查文件权限

检查 OpenCode 权限设置
查看 ~/.config/opencode/config.json 中的权限配置：

运行时授权
当 AI 请求执行操作时，需要手动确认授权。

重置权限

Question 16

OpenCode 响应很慢怎么办？

Accepted Answer

1. 检查模型选择
大模型（如 GPT-4、Claude Opus）较慢，可切换到快速模型：

2. 减少上下文大小
清除不需要的文件引用：

3. 检查网络延迟
使用代理可能增加延迟，尝试直连或更换代理节点。

4. 本地模型
考虑使用 Ollama 运行本地模型，避免网络延迟。

# 常见问题

📦安装问题(Installation)

⚙️配置问题(Configuration)

💡使用问题(Usage)

🔧故障排除(Troubleshooting)