OpenCode 中文社区

Appearance

G. 常见问题（FAQ） ​

💡 一句话总结：遇到问题？先看这里

安装问题 ​

Q: 安装命令报错 "command not found" ​

A: 可能是 PATH 环境变量没有正确设置。

bash
# 检查安装位置
which opencode

# 手动添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Q: Windows 上安装失败 ​

A: 推荐使用包管理器安装：

powershell
# 使用 Scoop
scoop install opencode

# 或使用 npm
npm install -g @anthropic-ai/opencode

Q: macOS 提示"无法验证开发者" ​

A: 这是 macOS 的安全限制。

bash
# 方法1：右键点击应用，选择"打开"
# 方法2：在终端运行
xattr -d com.apple.quarantine /path/to/opencode

网络问题 ​

Q: 连接超时，提示 "ETIMEDOUT" ​

A: 这是网络连接问题，国内用户常见。

方案1：设置代理

bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
opencode

方案2：使用国产模型

bash
/connect  # 选择 Z.AI 或 DeepSeek

Q: API Key 设置了但提示"认证失败" ​

A: 检查以下几点：

  1. API Key 格式正确
  2. API Key 有效：在提供商官网测试
  3. 环境变量设置正确
  4. 配置文件语法正确

模型配置问题 ​

Q: 如何切换不同的模型 ​

A:

方法1：TUI 中切换

/models

方法2：命令行指定

bash
opencode -m deepseek-chat

方法3：配置文件设置默认值

json
{
  "model": "deepseek-chat"
}

Q: 多个提供商如何配置 ​

A: 在配置文件中添加多个提供商：

json
{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      }
    }
  }
}

权限问题 ​

Q: 每次操作都要确认太烦了 ​

A: 可以设置权限模式：

配置文件设置

json
{
  "permission": {
    "read": "allow",
    "edit": "allow",
    "bash": "allow"
  }
}

Q: 如何限制 AI 只读不写 ​

A: 使用 Plan 模式：

  1. 按 Tab 切换到 Plan 模式
  2. 或启动时指定 Agent：opencode -a plan

性能问题 ​

Q: 响应很慢 ​

A: 可能的原因和解决方案：

  1. 网络延迟：使用代理或切换到国产模型
  2. 模型太大：使用更小的模型
  3. 上下文太长：使用 /compact 压缩上下文

Q: 上下文太长导致报错 ​

A:

bash
# 手动压缩
/compact

功能问题 ​

Q: 如何让 AI 记住我的偏好 ​

A: 使用 AGENTS.md 或 CLAUDE.md 文件：

markdown
<!-- AGENTS.md -->
# 项目规则

- 使用 TypeScript
- 使用 pnpm 而不是 npm
- 代码注释使用中文

Q: 历史会话找不到了 ​

A:

bash
# 列出所有会话
opencode session list

# 或在 TUI 中查看
/sessions

Q: 如何导出对话记录 ​

A:

bash
# TUI 中导出
/export

📚 更多完整模板：Prompt 模板库

微信群