docs: improve zh-cn and zh-tw documentation translations (#13942)
This commit is contained in:
@@ -1,67 +1,67 @@
|
||||
---
|
||||
title: 故障排除
|
||||
description: 常见问题以及如何解决它们。
|
||||
description: 常见问题及其解决方法。
|
||||
---
|
||||
|
||||
要排除 opencode 的问题,请首先检查其存储在磁盘上的日志和本地数据。
|
||||
要调试 OpenCode 的问题,请先检查其存储在磁盘上的日志和本地数据。
|
||||
|
||||
---
|
||||
|
||||
## 日志
|
||||
|
||||
日志文件写入:
|
||||
日志文件写入位置:
|
||||
|
||||
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
||||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode\log`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode\log`
|
||||
|
||||
日志档案以时间命名(例如`2025-01-09T123456.log`),并保留最近10个日志档案。
|
||||
日志文件以时间戳命名(例如 `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`.
|
||||
你可以通过 `--log-level` 命令行选项设置日志级别以获取更详细的调试信息。例如:`opencode --log-level DEBUG`。
|
||||
|
||||
---
|
||||
|
||||
## 存储
|
||||
|
||||
opencode程序将会话数据和其他应用程序数据存储在磁碟上:
|
||||
OpenCode 将会话数据和其他应用数据存储在磁盘上:
|
||||
|
||||
- **macOS/Linux**: `~/.local/share/opencode/`
|
||||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode`
|
||||
|
||||
该目录包含:
|
||||
|
||||
- `auth.json` - 身份验证凭据,例如 API 密钥、OAuth Tokens
|
||||
- `auth.json` - 身份验证数据,如 API 密钥、OAuth Token
|
||||
- `log/` - 应用日志
|
||||
- `project/` - 项目特定数据,例如会话和消息数据
|
||||
- 如果项目位于 Git 仓库中,则存储在 `./<project-slug>/storage/` 中
|
||||
- 如果不是 Git 存储库,则存储在 `./global/storage/` 中
|
||||
- `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.
|
||||
OpenCode Desktop 会在后台运行一个本地 OpenCode 服务器(即 `opencode-cli` 附属进程)。大多数问题是由插件异常、缓存损坏或错误的服务器设置引起的。
|
||||
|
||||
### 快速检查
|
||||
|
||||
- 完全退出并重新启动应用程序。
|
||||
- 如果应用程序显示错误界面,请单击“**重新启动**”并复制错误详细信息。
|
||||
- macOS only: `OpenCode` menu -> **Reload Webview** (helps if the UI is blank/frozen).
|
||||
- 完全退出并重新启动应用。
|
||||
- 如果应用显示错误页面,请点击**重新启动**并复制错误详情。
|
||||
- 仅限 macOS:`OpenCode` 菜单 -> **Reload Webview**(当 UI 空白或冻结时有效)。
|
||||
|
||||
---
|
||||
|
||||
### 禁用插件
|
||||
|
||||
如果桌面应用程序在启动时崩溃、挂起或行为异常,请首先禁用插件。
|
||||
如果桌面应用在启动时崩溃、卡住或行为异常,请先禁用插件。
|
||||
|
||||
#### 检查全域性配置
|
||||
#### 检查全局配置
|
||||
|
||||
开启全域性文件并查询`plugin`键。
|
||||
打开你的全局配置文件,查找 `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`
|
||||
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc`(或 `~/.config/opencode/opencode.json`)
|
||||
- **macOS/Linux**(旧版安装): `~/.local/share/opencode/opencode.jsonc`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.config\opencode\opencode.jsonc`
|
||||
|
||||
如果您配置了插件,请通过删除密钥或将其设置为空数组来暂时禁用它们:
|
||||
如果你配置了插件,请通过移除该键或将其设置为空数组来临时禁用它们:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
@@ -72,118 +72,118 @@ opencode Desktop runs a local opencode server (the `opencode-cli` sidecar) in th
|
||||
|
||||
#### 检查插件目录
|
||||
|
||||
opencode 还可以从磁碟加载本地外挂。暂时将它们移开(或重新命名资料夹)并重新启动桌面应用程序:
|
||||
OpenCode 还可以从磁盘加载本地插件。临时将这些插件移走(或重命名文件夹),然后重新启动桌面应用:
|
||||
|
||||
- **全域性插件**
|
||||
- **全局插件**
|
||||
- **macOS/Linux**: `~/.config/opencode/plugins/`
|
||||
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\plugins`
|
||||
- **项目插件**(仅当您使用每个项目配置时)
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.config\opencode\plugins`
|
||||
- **项目插件**(仅当你使用了项目级配置时)
|
||||
- `<your-project>/.opencode/plugins/`
|
||||
|
||||
如果应用程序再次开始工作,请一次重新启用一个插件,以找出导致问题的插件。
|
||||
如果应用恢复正常,请逐个重新启用插件,找出导致问题的那个。
|
||||
|
||||
---
|
||||
|
||||
### 清除缓存
|
||||
|
||||
如果取消外挂没有帮助(或者外挂安装被卡住),请清除缓存,方便opencode可以重建它。
|
||||
如果禁用插件没有帮助(或插件安装卡住了),请清除缓存以便 OpenCode 重新构建。
|
||||
|
||||
1. 完全退出 opencode 桌面。
|
||||
1. 完全退出 OpenCode Desktop。
|
||||
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`
|
||||
- **macOS**: Finder -> `Cmd+Shift+G` -> 粘贴 `~/.cache/opencode`
|
||||
- **Linux**: 删除 `~/.cache/opencode`(或运行 `rm -rf ~/.cache/opencode`)
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.cache\opencode`
|
||||
|
||||
3. 重新启动 opencode 桌面。
|
||||
3. 重新启动 OpenCode Desktop。
|
||||
|
||||
---
|
||||
|
||||
### 修复服务器连接问题
|
||||
|
||||
opencode Desktop 可以启动自己的本地服务器(默认配置)或连线到您的服务器 URL。
|
||||
OpenCode Desktop 可以启动自己的本地服务器(默认行为),也可以连接到你配置的服务器 URL。
|
||||
|
||||
如果您看到**“连线失败”**对话中断(或者应用程序永远无法穿透启动萤幕),请检查自定义服务器URL。
|
||||
如果你看到**"Connection Failed"**对话框(或应用始终停留在启动画面),请检查自定义服务器 URL。
|
||||
|
||||
#### 清除桌面桌面服务器 URL
|
||||
#### 清除桌面默认服务器 URL
|
||||
|
||||
在主屏幕中,单击服务器名称(带有状态点)以打开服务器选择器。在“**默认服务器**”部分中,单击“**清除**”。
|
||||
在主页面上,点击服务器名称(带有状态指示点)以打开服务器选择器。在**默认服务器**部分,点击**清除**。
|
||||
|
||||
#### 从配置中删除 `server.port` / `server.hostname`
|
||||
#### 从配置中移除 `server.port` / `server.hostname`
|
||||
|
||||
If your `opencode.json(c)` contains a `server` section, temporarily remove it and restart the desktop app.
|
||||
如果你的 `opencode.json(c)` 包含 `server` 部分,请临时移除该部分并重新启动桌面应用。
|
||||
|
||||
#### 检查环境变量
|
||||
|
||||
如果您在环境中设置了 `OPENCODE_PORT`,桌面应用程序将尝试将交换机用于本地服务器。
|
||||
如果你在环境中设置了 `OPENCODE_PORT`,桌面应用将尝试使用该端口作为本地服务器端口。
|
||||
|
||||
- 取消设置`OPENCODE_PORT`(或选择一个休闲摊)并重新启动。
|
||||
- 取消设置 `OPENCODE_PORT`(或选择一个空闲端口)并重新启动。
|
||||
|
||||
---
|
||||
|
||||
### Linux:Wayland / X11 问题
|
||||
### Linux: Wayland / X11 问题
|
||||
|
||||
在 Linux 上,某些 Wayland 设置可能会导致空白视窗或合成器错误。
|
||||
在 Linux 上,某些 Wayland 设置可能会导致窗口空白或合成器错误。
|
||||
|
||||
- 如果您在 Wayland 程序上并且应用的是 blank/crashing,请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
|
||||
- 如果这让事情变得更糟糕,请完成其删除并尝试在 X11 会话下启动。
|
||||
- 如果你使用 Wayland 且应用出现空白或崩溃,请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
|
||||
- 如果情况变得更糟,请移除该设置并尝试在 X11 会话下启动。
|
||||
|
||||
---
|
||||
|
||||
### Windows:WebView2执行时
|
||||
### Windows: WebView2 运行时
|
||||
|
||||
在 Windows 上,opencode 桌面需要 Microsoft Edge **WebView2 执行时**。如果应用程序打开为空白视窗或无法启动,请 install/update WebView2 并重试。
|
||||
在 Windows 上,OpenCode Desktop 需要 Microsoft Edge **WebView2 Runtime**。如果应用打开后是空白窗口或无法启动,请安装或更新 WebView2 后重试。
|
||||
|
||||
---
|
||||
|
||||
### Windows:一般问题
|
||||
### 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.
|
||||
如果你在 Windows 上遇到性能缓慢、文件访问问题或终端问题,请尝试使用 [WSL (Windows Subsystem for Linux)](/docs/windows-wsl)。WSL 提供了一个 Linux 环境,能更好地与 OpenCode 的功能兼容。
|
||||
|
||||
---
|
||||
|
||||
### 通知不显示
|
||||
|
||||
opencode 桌面仅在以下情况下显示系统通知:
|
||||
OpenCode Desktop 仅在以下情况下显示系统通知:
|
||||
|
||||
- 在您的作业系统中设置为 opencode 启用了通知,并且
|
||||
- 应用程序视窗未聚焦。
|
||||
- 在操作系统设置中已为 OpenCode 启用通知,且
|
||||
- 应用窗口未处于焦点状态。
|
||||
|
||||
---
|
||||
|
||||
### 重置桌面应用程序储存(最后的手段)
|
||||
### 重置桌面应用存储(最后手段)
|
||||
|
||||
如果应用程序无法并且启动您无法从 UI 内部清除设置,请重置桌面应用程序的存储状态。
|
||||
如果应用无法启动且你无法从 UI 内部清除设置,请重置桌面应用的保存状态。
|
||||
|
||||
1. 退出 opencode 桌面。
|
||||
2. 查询并删除这些文件(它们位于 opencode 桌面应用程序数据目录中):
|
||||
1. 退出 OpenCode Desktop。
|
||||
2. 找到并删除以下文件(它们位于 OpenCode Desktop 应用数据目录中):
|
||||
|
||||
- `opencode.settings.dat` (desktop default server URL)
|
||||
- `opencode.global.dat` and `opencode.workspace.*.dat` (UI state like recent servers/projects)
|
||||
- `opencode.settings.dat`(桌面默认服务器 URL)
|
||||
- `opencode.global.dat` 和 `opencode.workspace.*.dat`(UI 状态,如最近的服务器/项目)
|
||||
|
||||
快速找到目录:
|
||||
快速找到该目录:
|
||||
|
||||
- **macOS**:Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`(然后搜索上面的档名)
|
||||
- **Linux**:在`~/.local/share`下搜索上述档名
|
||||
- **Windows**:按 `WIN+R` -> `%APPDATA%` (然后搜索上面的档名)
|
||||
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`(然后搜索上述文件名)
|
||||
- **Linux**: 在 `~/.local/share` 下搜索上述文件名
|
||||
- **Windows**: 按 `WIN+R` -> `%APPDATA%`(然后搜索上述文件名)
|
||||
|
||||
---
|
||||
|
||||
## 寻求帮助
|
||||
## 获取帮助
|
||||
|
||||
如果您遇到 opencode 问题:
|
||||
如果你遇到 OpenCode 的问题:
|
||||
|
||||
1. **报告 GitHub** 上的问题
|
||||
1. **在 GitHub 上报告问题**
|
||||
|
||||
报告错误或请求功能的最佳方式是利用我们的 GitHub 存储库:
|
||||
报告 Bug 或请求功能的最佳方式是通过我们的 GitHub 仓库:
|
||||
|
||||
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
|
||||
|
||||
在建立新问题之前,请搜索现有问题以查看您的问题是否已被报告。
|
||||
在创建新 Issue 之前,请先搜索已有的 Issue,看看你的问题是否已被报告。
|
||||
|
||||
2. **加入我们的不和谐**
|
||||
2. **加入我们的 Discord**
|
||||
|
||||
获得实时帮助和社群讨论,请加入我们的Discord服务器:
|
||||
如需实时帮助和社区讨论,请加入我们的 Discord 服务器:
|
||||
|
||||
[**opencode.ai/discord**](https://opencode.ai/discord)
|
||||
|
||||
@@ -191,35 +191,34 @@ opencode 桌面仅在以下情况下显示系统通知:
|
||||
|
||||
## 常见问题
|
||||
|
||||
以下是一些常见问题以及解决方法。
|
||||
以下是一些常见问题及其解决方法。
|
||||
|
||||
---
|
||||
|
||||
### opencode 无法启动
|
||||
### OpenCode 无法启动
|
||||
|
||||
1. 检查日志中是否有错误消息
|
||||
2. 尝试使用 `--print-logs` 执行以查看终端中的输出
|
||||
3. Ensure you have the latest version with `opencode upgrade`
|
||||
1. 检查日志中的错误消息
|
||||
2. 尝试使用 `--print-logs` 运行以在终端中查看输出
|
||||
3. 使用 `opencode upgrade` 确保你使用的是最新版本
|
||||
|
||||
---
|
||||
|
||||
### 身份验证问题
|
||||
|
||||
1. 尝试使用 TUI 中的 `/connect` 命令重新进行身份验证
|
||||
2. 检查您的API 密钥是否有效
|
||||
3. 保证您的网路允许连线到达辉煌的API
|
||||
1. 尝试在 TUI 中使用 `/connect` 命令重新进行身份验证
|
||||
2. 检查你的 API 密钥是否有效
|
||||
3. 确保你的网络允许连接到提供商的 API
|
||||
|
||||
---
|
||||
|
||||
### 模型不可用
|
||||
|
||||
1. 检查您是否已通过提供商的身份验证
|
||||
1. 检查你是否已通过提供商的身份验证
|
||||
2. 验证配置中的模型名称是否正确
|
||||
3. 某些模型可能需要特定的访问权限或订阅
|
||||
|
||||
如果您遇到 `ProviderModelNotFoundError` 您很可能是错误的
|
||||
在某处引用模型。
|
||||
模型应该像这样引用:`<providerId>/<modelId>`
|
||||
如果你遇到 `ProviderModelNotFoundError`,很可能是在某处错误地引用了模型。
|
||||
模型应按如下方式引用:`<providerId>/<modelId>`
|
||||
|
||||
示例:
|
||||
|
||||
@@ -227,54 +226,54 @@ opencode 桌面仅在以下情况下显示系统通知:
|
||||
- `openrouter/google/gemini-2.5-flash`
|
||||
- `opencode/kimi-k2`
|
||||
|
||||
To figure out what models you have access to, run `opencode models`
|
||||
要查看你有权访问哪些模型,请运行 `opencode models`
|
||||
|
||||
---
|
||||
|
||||
### 提供商初始化错误
|
||||
### ProviderInitError
|
||||
|
||||
如果遇到 ProviderInitError,您的配置可能无效或损坏。
|
||||
如果你遇到 ProviderInitError,很可能是配置无效或已损坏。
|
||||
|
||||
要解决这个问题:
|
||||
要解决此问题:
|
||||
|
||||
1. 首先,按照[提供商指南](/docs/providers) 验证您的事业是否已正确设置
|
||||
2. 如果问题仍然存在,请尝试清除储存的配置:
|
||||
1. 首先,按照[提供商指南](/docs/providers)验证你的提供商是否已正确设置
|
||||
2. 如果问题仍然存在,请尝试清除已存储的配置:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.local/share/opencode
|
||||
```
|
||||
|
||||
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.local\share\opencode`
|
||||
在 Windows 上,按 `WIN+R` 并删除:`%USERPROFILE%\.local\share\opencode`
|
||||
|
||||
3. 使用 TUI 中的 `/connect` 命令指示您的企业重新进行身份验证。
|
||||
3. 在 TUI 中使用 `/connect` 命令重新与提供商进行身份验证。
|
||||
|
||||
---
|
||||
|
||||
### AI_API_CallError 和提供包问题
|
||||
### AI_APICallError 和提供商包问题
|
||||
|
||||
如果您遇到 API 呼叫错误,这可能是由于过去提供包造成的。 opencode 根据需要动态安装提供包(OpenAI、Anthropic、Google 等)将其缓存放在本地。
|
||||
如果你遇到 API 调用错误,可能是由于提供商包过期导致的。OpenCode 会根据需要动态安装提供商包(OpenAI、Anthropic、Google 等)并将它们缓存到本地。
|
||||
|
||||
要解决provider 包问题:
|
||||
要解决提供商包问题:
|
||||
|
||||
1. 清除provider 包缓存:
|
||||
1. 清除提供商包缓存:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.cache/opencode
|
||||
```
|
||||
|
||||
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`
|
||||
在 Windows 上,按 `WIN+R` 并删除:`%USERPROFILE%\.cache\opencode`
|
||||
|
||||
2. 重新启动 opencode 以重新安装最新的提供包
|
||||
2. 重新启动 OpenCode 以重新安装最新的提供商包
|
||||
|
||||
这将需要 opencode 下载最新版本的提供包,这通常可以解决模型参数和 API 更改的兼容性问题。
|
||||
这将强制 OpenCode 下载最新版本的提供商包,通常可以解决模型参数和 API 变更带来的兼容性问题。
|
||||
|
||||
---
|
||||
|
||||
### 复制/粘贴在 Linux 上不可用
|
||||
### 在 Linux 上复制/粘贴不可用
|
||||
|
||||
Linux 用户需要安装以下剪贴簿实用程序之一才能使 copy/paste 功能正常工作:
|
||||
Linux 用户需要安装以下剪贴板工具之一,复制/粘贴功能才能正常工作:
|
||||
|
||||
**对于X11系统:**
|
||||
**对于 X11 系统:**
|
||||
|
||||
```bash
|
||||
apt install -y xclip
|
||||
@@ -282,7 +281,7 @@ apt install -y xclip
|
||||
apt install -y xsel
|
||||
```
|
||||
|
||||
** 对于 Wayland 系统:**
|
||||
**对于 Wayland 系统:**
|
||||
|
||||
```bash
|
||||
apt install -y wl-clipboard
|
||||
@@ -297,4 +296,4 @@ Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
|
||||
export DISPLAY=:99.0
|
||||
```
|
||||
|
||||
opencode 将检测您是否正在使用 Wayland 并更喜欢 `wl-clipboard`,否则将尝试按以下顺序剪贴簿工具:`xclip` 和 `xsel`。
|
||||
OpenCode 会检测你是否正在使用 Wayland 并优先使用 `wl-clipboard`,否则将按以下顺序尝试查找剪贴板工具:`xclip` 和 `xsel`。
|
||||
|
||||
Reference in New Issue
Block a user