301 lines
8.9 KiB
Plaintext
301 lines
8.9 KiB
Plaintext
---
|
||
title: 故障排除
|
||
description: 常見問題以及如何解決它們。
|
||
---
|
||
|
||
要排除 OpenCode 的问题，请首先检查其存储在磁碟上的日志和本地数据。
|
||
|
||
---
|
||
|
||
## 紀錄
|
||
|
||
日誌檔案寫入：
|
||
|
||
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode\log`
|
||
|
||
日志档案以时间命名（例如`2025-01-09T123456.log`），并保留最近10个日志档案。
|
||
|
||
You can set the log level with the `--log-level` command-line option to get more detailed debug information. For example, `opencode --log-level DEBUG`.
|
||
|
||
---
|
||
|
||
## 貯存
|
||
|
||
opencode程序将会话数据和其他应用程序数据存储在磁碟上：
|
||
|
||
- **macOS/Linux**: `~/.local/share/opencode/`
|
||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode`
|
||
|
||
該目錄包含：
|
||
|
||
- `auth.json` - 身份验证资料，例如API金密钥、OAuth令牌
|
||
- `log/` - 应用日志
|
||
- `project/` - 专案特定数据，例如会话和消息数据
|
||
- 如果專案位於 Git 儲存庫中，則它儲存在 `./<project-slug>/storage/` 中
|
||
- 如果不是 Git 存储库，则存储在 `./global/storage/` 中
|
||
|
||
---
|
||
|
||
## 桌面應用程式
|
||
|
||
OpenCode Desktop runs a local OpenCode server (the `opencode-cli` sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
|
||
|
||
### 快速檢查
|
||
|
||
- 完全退出並重新啟動應用程式。
|
||
- 如果應用程式顯示錯誤螢幕，請單擊“**重新啟動**”並複制錯誤詳細資訊。
|
||
- macOS only: `OpenCode` menu -> **Reload Webview** (helps if the UI is blank/frozen).
|
||
|
||
---
|
||
|
||
### 禁用外掛
|
||
|
||
如果桌面應用程式在啟動時崩潰、掛起或行為異常，請首先禁用外掛。
|
||
|
||
#### 檢查全域性配置
|
||
|
||
开启全域性文件并查询`plugin`键。
|
||
|
||
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (or `~/.config/opencode/opencode.json`)
|
||
- **macOS/Linux** (older installs): `~/.local/share/opencode/opencode.jsonc`
|
||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\opencode.jsonc`
|
||
|
||
如果您配置了外掛，請透過刪除金鑰或將其設定為空陣列來暫時禁用它們：
|
||
|
||
```jsonc
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"plugin": [],
|
||
}
|
||
```
|
||
|
||
#### 檢查外掛目錄
|
||
|
||
OpenCode 还可以从磁碟加载本地外挂。暂时将它们移开（或重新命名资料夹）并重新启动桌面应用程序：
|
||
|
||
- **全域性外掛**
|
||
- **macOS/Linux**: `~/.config/opencode/plugins/`
|
||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\plugins`
|
||
- **專案外掛**（僅當您使用每個專案配置時）
|
||
- `<your-project>/.opencode/plugins/`
|
||
|
||
如果應用程式再次開始工作，請一次重新啟用一個外掛，以找出導致問題的外掛。
|
||
|
||
---
|
||
|
||
### 清除快取
|
||
|
||
如果取消外挂没有帮助（或者外挂安装被卡住），请清除快取，方便OpenCode可以重建它。
|
||
|
||
1. 完全退出 OpenCode 桌面。
|
||
2. 刪除快取目錄：
|
||
|
||
- **macOS**: Finder -> `Cmd+Shift+G` -> paste `~/.cache/opencode`
|
||
- **Linux**: delete `~/.cache/opencode` (or run `rm -rf ~/.cache/opencode`)
|
||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.cache\opencode`
|
||
|
||
3. 重新启动 OpenCode 桌面。
|
||
|
||
---
|
||
|
||
### 修復伺服器連線問題
|
||
|
||
OpenCode Desktop 可以启动自己的本地服务器（默认配置）或连线到您的服务器 URL。
|
||
|
||
如果您看到**“连线失败”**对话中断（或者应用程序永远无法穿透启动萤幕），请检查自定义服务器URL。
|
||
|
||
#### 清除桌面桌面服务器 URL
|
||
|
||
在主螢幕中，單擊伺服器名稱（帶有狀態點）以開啟伺服器選擇器。在“**預設伺服器**”部分中，單擊“**清除**”。
|
||
|
||
#### 从配置中删除 `server.port` / `server.hostname`
|
||
|
||
If your `opencode.json(c)` contains a `server` section, temporarily remove it and restart the desktop app.
|
||
|
||
#### 檢查環境變數
|
||
|
||
如果您在环境中设置了 `OPENCODE_PORT`，桌面应用程序将尝试将交换机用于本地服务器。
|
||
|
||
- 取消设置`OPENCODE_PORT`（或选择一个休闲摊）并重新启动。
|
||
|
||
---
|
||
|
||
### Linux：Wayland / X11 问题
|
||
|
||
在 Linux 上，某些 Wayland 设置可能会导致空白视窗或合成器错误。
|
||
|
||
- 如果您在 Wayland 程序上并且应用的是 blank/crashing，请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
|
||
- 如果这让事情变得更糟糕，请完成其删除并尝试在 X11 会话下启动。
|
||
|
||
---
|
||
|
||
### Windows：WebView2执行时
|
||
|
||
在 Windows 上，OpenCode 桌面需要 Microsoft Edge **WebView2 执行时**。如果应用程序打开为空白视窗或无法启动，请 install/update WebView2 并重试。
|
||
|
||
---
|
||
|
||
### Windows：一般问题
|
||
|
||
If you're experiencing slow performance, file access issues, or terminal problems on Windows, try using [WSL (Windows Subsystem for Linux)](/docs/windows-wsl). WSL provides a Linux environment that works more seamlessly with OpenCode's features.
|
||
|
||
---
|
||
|
||
### 通知不顯示
|
||
|
||
OpenCode 桌面仅在以下情况下显示系统通知：
|
||
|
||
- 在您的作业系统中设置为 OpenCode 启用了通知，并且
|
||
- 應用程式視窗未聚焦。
|
||
|
||
---
|
||
|
||
### 重置桌面應用程式儲存（最後的手段）
|
||
|
||
如果应用程序无法并且启动您无法从 UI 内部清除设置，请重置桌面应用程序的存储状态。
|
||
|
||
1. 退出 OpenCode 桌面。
|
||
2. 查询并删除这些文件（它们位于 OpenCode 桌面应用程序数据目录中）：
|
||
|
||
- `opencode.settings.dat` (desktop default server URL)
|
||
- `opencode.global.dat` and `opencode.workspace.*.dat` (UI state like recent servers/projects)
|
||
|
||
快速找到目錄：
|
||
|
||
- **macOS**：Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`（然后搜索上面的档名）
|
||
- **Linux**：在`~/.local/share`下搜索上述档名
|
||
- **Windows**：按 `WIN+R` -> `%APPDATA%` （然后搜索上面的档名）
|
||
|
||
---
|
||
|
||
## 尋求幫助
|
||
|
||
如果您遇到 OpenCode 问题：
|
||
|
||
1. **报告 GitHub** 上的问题
|
||
|
||
报告错误或请求功能的最佳方式是利用我们的 GitHub 存储库：
|
||
|
||
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
|
||
|
||
在建立新問題之前，請搜尋現有問題以檢視您的問題是否已被報告。
|
||
|
||
2. **加入我們的不和諧**
|
||
|
||
获得实时帮助和社群讨论，请加入我们的Discord服务器：
|
||
|
||
[**opencode.ai/discord**](https://opencode.ai/discord)
|
||
|
||
---
|
||
|
||
## 常見問題
|
||
|
||
以下是一些常見問題以及解決方法。
|
||
|
||
---
|
||
|
||
### OpenCode 无法启动
|
||
|
||
1. 檢查日誌中是否有錯誤訊息
|
||
2. 尝试使用 `--print-logs` 执行以检视终端中的输出
|
||
3. Ensure you have the latest version with `opencode upgrade`
|
||
|
||
---
|
||
|
||
### 身份驗證問題
|
||
|
||
1. 尝试使用 TUI 中的 `/connect` 命令重新进行身份验证
|
||
2. 检查您的API金钥匙是否有效
|
||
3. 保证您的网路允许连线到达辉煌的API
|
||
|
||
---
|
||
|
||
### 型號不可用
|
||
|
||
1. 檢查您是否已透過提供商的身份驗證
|
||
2. 驗證配置中的型號名稱是否正確
|
||
3. 某些型號可能需要特定的訪問許可權或訂閱
|
||
|
||
如果您遇到 `ProviderModelNotFoundError` 您很可能是错误的
|
||
在某處引用模型。
|
||
模型應該像這樣引用：`<providerId>/<modelId>`
|
||
|
||
示例：
|
||
|
||
- `openai/gpt-4.1`
|
||
- `openrouter/google/gemini-2.5-flash`
|
||
- `opencode/kimi-k2`
|
||
|
||
To figure out what models you have access to, run `opencode models`
|
||
|
||
---
|
||
|
||
### 提供者初始化錯誤
|
||
|
||
如果遇到 ProviderInitError，您的配置可能无效或损坏。
|
||
|
||
要解決這個問題：
|
||
|
||
1. 首先，按照[提供商指南](/docs/providers) 验证您的事业是否已正确设置
|
||
2. 如果問題仍然存在，請嘗試清除儲存的配置：
|
||
|
||
```bash
|
||
rm -rf ~/.local/share/opencode
|
||
```
|
||
|
||
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.local\share\opencode`
|
||
|
||
3. 使用 TUI 中的 `/connect` 命令指示您的企业重新进行身份验证。
|
||
|
||
---
|
||
|
||
### AI_API_CallError 和提供程序包问题
|
||
|
||
如果您遇到 API 呼叫错误，这可能是由于过去提供程序包造成的。 opencode 根据需要动态安装提供程序包（OpenAI、Anthropic、Google 等）将其快取放在本地。
|
||
|
||
要解決提供程式包問題：
|
||
|
||
1. 清除提供程式包快取：
|
||
|
||
```bash
|
||
rm -rf ~/.cache/opencode
|
||
```
|
||
|
||
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`
|
||
|
||
2. 重新启动 opencode 以重新安装最新的提供程序包
|
||
|
||
这将需要 opencode 下载最新版本的提供程序包，这通常可以解决模型引数和 API 更改的相容性问题。
|
||
|
||
---
|
||
|
||
### 複製/paste 不适用 Linux
|
||
|
||
Linux 用户需要安装以下剪贴簿实用程序之一才能使 copy/paste 功能正常工作：
|
||
|
||
**对于X11系统：**
|
||
|
||
```bash
|
||
apt install -y xclip
|
||
# or
|
||
apt install -y xsel
|
||
```
|
||
|
||
** 对于 Wayland 系统：**
|
||
|
||
```bash
|
||
apt install -y wl-clipboard
|
||
```
|
||
|
||
**對於無頭環境：**
|
||
|
||
```bash
|
||
apt install -y xvfb
|
||
# and run:
|
||
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
|
||
export DISPLAY=:99.0
|
||
```
|
||
|
||
opencode 将检测您是否正在使用 Wayland 并更喜欢 `wl-clipboard`，否则将尝试按以下顺序剪贴簿工具：`xclip` 和 `xsel`。
|