wip(docs): i18n (#12681)

This commit is contained in:
Adam
2026-02-09 11:34:35 -06:00
committed by GitHub
parent f74c0339cc
commit dc53086c1e
642 changed files with 192745 additions and 509 deletions

View File

@@ -0,0 +1,685 @@
---
title: 配置
description: 使用 OpenCode JSON 配置。
---
您可以使用 JSON 配置文件配置 OpenCode。
---
## 格式
OpenCode 支持 **JSON** 和 **JSONC**(带注释的 JSON格式。
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
// Theme configuration
"theme": "opencode",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true,
}
```
---
## 地點
您可以將配置放置在幾個不同的位置,它們有一個
不同的優先順序。
:::笔记
配置文件**合併在一起**,而不是替換。
:::
配置文件被合併在一起,而不是被替換。以下配置位置的設置被合併。僅當密鑰衝突時,後面的配置才會覆蓋前面的配置。保留所有配置中的非衝突設置。
例如,如果您的全局配置设置`theme: "opencode"`和`autoupdate: true`并且您的项目配置设置ZZPH最终2ZZ则配置将包括所有三个设置。
---
### 優先順序
配置源按以下順序加載(後面的源覆蓋前面的源):
1. **远程配置**(来自`.well-known/opencode`-组织默认值
2. **全局配置** (`~/.config/opencode/opencode.json`) - 用户首选项
3. **自定义配置** (`OPENCODE_CONFIG` env var) - 自定义覆盖
4. **项目配置**(项目中的`opencode.json`- 项目特定的设置
5. **`.opencode` 目录** - 代理、命令、插件
6. **内联配置** (`OPENCODE_CONFIG_CONTENT` env var) - 运行时覆盖
這意味著項目配置可以覆蓋全局默認值,全局配置可以覆蓋遠程組織默認值。
:::笔记
`.opencode` 和`~/.config/opencode` 目录对子目录使用**复数名称**`agents/`、`commands/`、`modes/`、`plugins/`、`skills/`、`tools/` 和`themes/`。为了坚固兼容,还支持单数名称(例如`agent/`)。
:::
---
### 偏僻的
组织可以通过 `.well-known/opencode` 端点提供默认配置。当您向支持的成功进行身份验证时,会自动获取该信息。
首先加載遠程配置,作為基礎層。所有其他配置源(全局、項目)都可以覆蓋這些默認值。
例如,如果您的组织提供默认取消的 MCP 服务器:
```json title="Remote config from .well-known/opencode"
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": false
}
}
}
```
您可以在本地配置中啟用特定服務器:
```json title="opencode.json"
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": true
}
}
}
```
---
### 全球的
将全局 OpenCode 配置放在 `~/.config/opencode/opencode.json` 中。使用全局配置来实现用户范围的首选项,例如主题、提供程序或按键绑定。
全局配置覆蓋遠程組織默認值。
---
### 每個項目
在项目根目录中添加`opencode.json`。项目配置在标准配置文件中具有最高优先级 - 它覆盖全局配置和远程配置。
:::提示
將項目特定配置放在項目的根目錄中。
:::
当OpenCode启动时它会在当前目录中查找配置文件或打开到最近的Git目录。
这也可以安全地签入 Git 并使用与全局模式相同的模式。
---
### 自定義路徑
使用 `OPENCODE_CONFIG` 环境变量指定自定义配置文件路径。
```bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"
```
自定義配置按優先順序在全局配置和項目配置之間加載。
---
### 自定義目錄
使用`OPENCODE_CONFIG_DIR`指定自定义配置目录
環境變量。將在該目錄中搜索代理、命令、
模式和插件类似于标准`.opencode`目录一样,并且应该
遵循相同的結構。
```bash
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"
```
自定义目录在全局配置和`.opencode`目录加载后,因此**可以覆盖**它们的设置。
---
## 模式
配置文件具有在 [**`opencode.ai/config.json`**](https://opencode.ai/config.json) 中配置的架构。
您的編輯器應該能夠根據架構進行驗證和自動完成。
---
### 途易
您可以通过 `tui` 选项配置特定于 TUI 的设置。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"tui": {
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto"
}
}
```
可用選項:
- `scroll_acceleration.enabled` - 启用 macOS 风格的滚动加速。 **优先于`scroll_speed`。 **
- `scroll_speed` - 自定义滚动速度倍增(默认值:`3`,简单:`1`)。如果`scroll_acceleration.enabled`是`true`,则忽略。
- `diff_style` - 控制差异渲染。 `"auto"` 适应宽度,`"stacked"` 始终显示单列。
[在此处了解有关使用 TUI 的更多信息](/docs/tui)。
---
### 伺服器
您可以通过`server` 选项为`opencode serve` 和`opencode web` 命令配置服务器设置。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"server": {
"port": 4096,
"hostname": "0.0.0.0",
"mdns": true,
"mdnsDomain": "myproject.local",
"cors": ["http://localhost:5173"]
}
}
```
可用選項:
- Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
- Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
- `mdns` - 启用 mDNS 服务发现。这允许网络上的其他设备发现您的 OpenCode 服务器。
- `mdnsDomain` - mDNS 服务的自定义域名。默认为 `opencode.local`。对于在同一个网络上运行多个实例很有用。
- `cors` - 从基于浏览器的客户端使用 HTTP 服务器时允许 CORS 的其他来源。值必须是完整来源(方案+主机+任选端口),例如 `https://app.example.com`。
[在此处了解有关服务器的更多信息](/docs/server)。
---
### 工具
您可以通过 `tools` 选项管理法学硕士可以使用的工具。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": false,
"bash": false
}
}
```
[在此处了解有关工具的更多信息](/docs/tools)。
---
### 型號
您可以通过 `provider`、`model` 和 `small_model` 选项来配置要在 OpenCode 配置中使用的提供的程序和模型。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"provider": {},
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}
```
`small_model` 选项为标题生成等轻量级任务配置单独的模型。默认情况下如果您的成功可以提供更便宜的模型OpenCode 会尝试使用更便宜的模型,否则它会退回到您的主模型。
Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"timeout": 600000,
"setCacheKey": true
}
}
}
}
```
- `timeout` - 请求超时以毫秒为单位默认值300000。设置为 `false` 以禁用。
- `setCacheKey` -确保始终为指定的提供者设置存储硬盘。
您还可以配置[本地模型](/docs/models#local)。[了解更多](/docs/models)。
---
#### 特定於提供商的選項
有些提供程序支持除通用 `timeout` 和 `apiKey` 之外的其他配置选项。
##### 亞馬遜基岩
Amazon Bedrock 支持 AWS 特定配置:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"amazon-bedrock": {
"options": {
"region": "us-east-1",
"profile": "my-aws-profile",
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
}
}
}
}
```
- Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
- `profile` - 来自 `~/.aws/credentials` 的 AWS 命名配置文件(默认为 `AWS_PROFILE` env var
- `endpoint` - VPC 终端节点的自定义节点 URL。这是使用 AWS 特定术语的通用 `baseURL` 选项的别名。如果两者都指定,`endpoint` 优先。
:::笔记
承载令牌(`AWS_BEARER_TOKEN_BEDROCK` 或`/connect`)优先于基于配置文件的身份验证。详情请参见【认证优先级](/docs/providers#authentication-precedence)。
:::
[了解有关 Amazon Bedrock 配置的更多信息](/docs/providers#amazon-bedrock)。
---
### 主題
您可以通过 OpenCode 配置中配置中的 `theme` 选项要使用的主题。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"theme": ""
}
```
[在这里了解更多](/docs/themes)。
---
### 代理商
您可以通过 `agent` 选项为特定任务配置专用代理。
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"code-reviewer": {
"description": "Reviews code for best practices and potential issues",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
"tools": {
// Disable file modification tools for review-only agent
"write": false,
"edit": false,
},
},
},
}
```
您还可以使用 `~/.config/opencode/agents/` 或 `.opencode/agents/` 中的 markdown 文件定义代理。 [在这里了解更多](/docs/agents)。
---
### 默認代理
您可以使用 `default_agent` 选项默认设置代理。当没有明确指定时,这将确定使用哪个代理。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"default_agent": "plan"
}
```
Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
此设置适用于所有界面TUI、CLI (`opencode run`)、桌面应用程序和 GitHub Action。
---
### 分享
您可以通过`share`选项配置[分享](/docs/share)功能。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"share": "manual"
}
```
這需要:
- Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
- `"auto"` - 自动分享新对话
- `"disabled"` - 完全禁用共享
默认情况下,共享设置为手动模式,您需要使用 `/share` 命令显式共享对话。
---
### 命令
您可以通过`command`选项为重复任务配置自定义命令。
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"command": {
"test": {
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
"description": "Run tests with coverage",
"agent": "build",
"model": "anthropic/claude-haiku-4-5",
},
"component": {
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
"description": "Create a new component",
},
},
}
```
您还可以使用 `~/.config/opencode/commands/` 或 `.opencode/commands/` 中的 Markdown 文件定义命令。 [在这里了解更多](/docs/commands)。
---
### 按鍵綁定
您可以通过 `keybinds` 选项自定义您的按键绑定。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"keybinds": {}
}
```
[在这里了解更多](/docs/keybinds)。
---
### 自動更新
OpenCode 将在启动时自动下载任何新的更新。您可以使用 `autoupdate` 选项取消此功能。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"autoupdate": false
}
```
如果您不想更新但希望在新版本可用时收到通知,则需将`autoupdate`设置为`"notify"`。
请注意,这仅在未使用 Homebrew 等包管理器安装时才有效。
---
### 格式化程序
您可以通过`formatter`选项配置代码初始化程序。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"disabled": true
},
"custom-prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"environment": {
"NODE_ENV": "development"
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
}
}
}
```
Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
---
### 權限
默认情况下opencode **允许所有操作**,无需明确批准。您可以使用 `permission` 选项更改此设置。
例如,要确保 `edit` 和 `bash` 工具需要用户批准:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"bash": "ask"
}
}
```
[在此处了解有关权限的更多信息](/docs/permissions)。
---
### 壓實
您可以通过 `compaction` 选项控制上下文压缩行为。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"compaction": {
"auto": true,
"prune": true
}
}
```
- Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
- `prune` - 删除旧工具以输出保存令牌(默认值:`true`)。
---
### 守望者
您可以通过`watcher`选项配置文件观察器忽略模式。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"watcher": {
"ignore": ["node_modules/**", "dist/**", ".git/**"]
}
}
```
模式遵循 glob 语法。使用它可以从文件监视中排除杂的目录。
---
### MCP服务器
您可以通过 `mcp` 选项配置要使用的 MCP 服务器。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"mcp": {}
}
```
[在这里了解更多](/docs/mcp-servers)。
---
### 插件
[插件](/docs/plugins) 使用自定义工具、挂钩和集成扩展 OpenCode。
将插件文件放置在`.opencode/plugins/` 或`~/.config/opencode/plugins/` 中。您还可以通过 `plugin` 选项从 npm 加载插件。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}
```
[在这里了解更多](/docs/plugins)。
---
### 指示
您可以通过 `instructions` 选项配置您正在使用的型号的说明。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}
```
這需要指令文件的路徑和全局模式數組。 [了解更多
关于规则在这里](/docs/rules)。
---
### 殘疾服務提供者
您可以通过 `disabled_providers` 选项取消自动加载的提供程序。当您想要阻止加载某些提供程序(即使其可用)时,这非常有用。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"disabled_providers": ["openai", "gemini"]
}
```
:::笔记
`disabled_providers` 优先于`enabled_providers`。
:::
`disabled_providers` 选项接受提供者 ID 内存。当提供者被取消时:
- 即使設置了環境變量也不會加載。
- 即使通过`/connect`命令配置API钥匙也不会加载它。
- 提供商的型號不會出現在型號選擇列表中。
---
### 啟用的提供商
Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"enabled_providers": ["anthropic", "openai"]
}
```
当您想要限制 OpenCode 仅使用特定的提供程序而不是一一禁止它们时,这非常有用。
:::笔记
`disabled_providers` 优先于`enabled_providers`。
:::
如果有人提供程序同时出现在`enabled_providers`和`disabled_providers`中,则`disabled_providers`优先考虑一致性。
---
### 實驗性的
`experimental` 键包含正在积极开发的选项。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"experimental": {}
}
```
:::警告
實驗選項不穩定。它們可能會更改或被刪除,恕不另行通知。
:::
---
## 變量
您可以在配置文件中使用變量替換來引用環境變量和文件內容。
---
### 環境變量
使用`{env:VARIABLE_NAME}`替换环境变量:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
"models": {},
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}
```
如果未設置環境變量,它將被替換為空字符串。
---
### 文件
Error 500 (Server Error)!!1500.Thats an error.There was an error. Please try again later.Thats all we know.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"instructions": ["./custom-instructions.md"],
"provider": {
"openai": {
"options": {
"apiKey": "{file:~/.secrets/openai-key}"
}
}
}
}
```
文件路徑可以是:
- 相對於配置文件目錄
- 或者以 `/` 或 `~` 開頭的絕對路徑
這些對於:
- 将API等敏感数据保存在单独的文件中。
- 包含大型指令文件,而不會弄亂您的配置。
- 跨多個配置文件共享通用配置片段。