Windows 环境下部署 Open Code完整指南V4.9

一、前言

请仔细参考本文操作，如有遇到问题，建议询问AI

AI推荐：

https://duck.ai/

https://www.google.com/ 选择AI模式

https://copilot.microsoft.com/

项目相关网站如下，官网有DOCS

opencode官网：https://opencode.ai/ GitHub项目链接：https://github.com/anomalyco/opencode

本文撰写时，opencode版本为1.4.7，如后续版本更新，有差异，请尝试AI解决

二、软件环境准备

2.1 安装 Node.js

访问官网下载地址：https://nodejs.org/zh-cn/download下载 LTS 版本（64-bit .msi）

执行安装程序

双击已下载的.msi文件

按照安装向导选择默认选项

确保勾选"Add to PATH"选项

点击"Install"完成安装

安装完成后，验证安装是否成功：


node --version
npm --version

应该能输出类似：


v24.x.x
11.x.x

2.2 npm 全局路径配置（可选）

仅当遇到权限错误（"ERR! Permission denied"）时参考本步骤

在PowerShell中执行以下命令，配置npm全局安装路径，避免权限问题：

powershell
# 1. 创建全局安装目录
mkdir -p $env:USERPROFILE\.npm-global

# 2. 告诉 npm 使用这个新目录
npm config set prefix "$env:USERPROFILE\.npm-global"

# 3. 获取当前用户已有的 Path（不含系统 Path），避免重复和混乱
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
$npmPath = "$env:USERPROFILE\.npm-global"

# 4. 如果 Path 里还没这个路径，就加进去 
if ($currentPath -notlike "*$npmPath*") {
    $newPath = "$npmPath;" + $currentPath
    [Environment]::SetEnvironmentVariable("PATH", $newPath, "User")
    $env:PATH = "$npmPath;" + $env:PATH
    Write-Host "环境变量已更新！" -ForegroundColor Green
} else {
    Write-Host "环境变量已存在，无需重复添加。" -ForegroundColor Yellow
}

验证配置：

powershell
npm config get prefix

三、工作区初始化

3.1 创建工作区目录结构

步骤1：创建目录

在PowerShell中执行以下命令：

powershell
New-Item -ItemType Directory -Force -Path "D:\opencode"
New-Item -ItemType Directory -Force -Path "D:\opencode\projects"
New-Item -ItemType Directory -Force -Path "D:\opencode\config"

步骤2：验证目录创建

powershell
Get-Item D:\opencode
Get-Item D:\opencode\projects
Get-Item D:\opencode\config

3.2 创建配置并链接（关键步骤）

创建配置文件

在D:\opencode\config目录下，创建opencode.json配置文件：

powershell
New-Item -Path "D:\opencode\config\opencode.json" -ItemType File -Force

编辑该文件，添加以下内容：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myproxy": {
      "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "https://api.aiguoguo199.com/v1"
      },
      "models": {
        "gpt-5.4-nano": {
          "name": "GPT-5.4-nano"
        }
      }
    }
  },
  "model": "myproxy/gpt-5.4-nano",
  "autoupdate": true
}

baseURL 必须以 /v1 结尾（不能是 /chat/completions）

apiKey 留空，后面通过auth命令单独设置

models 列出中转站支持的模型

如果需要配置模型为配Gemini 或 Claude，对应的npm包名称为@ai-sdk/google，@ai-sdk/anthropic

创建软链接（管理员 PowerShell）

在用户主目录和应用数据目录创建软链接，在管理员 PowerShell 中运行以下命令

powershell
# 创建配置文件软链接
New-Item -ItemType SymbolicLink -Path "$HOME\.opencode.json" -Target "D:\opencode\config\opencode.json" -Force

验证软链接

powershell
Get-Item "$HOME\.opencode.json" -ErrorAction SilentlyContinue | Select-Object LinkType, Target, FullName

输出应显示 SymbolicLink，且 Target 指向 D:\opencode\config 下的相应文件。

3.3 配置环境变量

步骤1：设置OPENCODE_HOME环境变量

打开PowerShell（以管理员身份运行），执行：


# 设置环境变量
[Environment]::SetEnvironmentVariable("OPENCODE_HOME", "D:\opencode", "User")
[Environment]::SetEnvironmentVariable("OPENCODE_WORKSPACE", "D:\opencode\projects", "User")
[Environment]::SetEnvironmentVariable("OPENCODE_CONFIG", "$HOME\.opencode.json", "User")

# 刷新当前会话
$env:OPENCODE_HOME = "D:\opencode"
$env:OPENCODE_WORKSPACE = "D:\opencode\projects"
$env:OPENCODE_CONFIG = "$HOME\.opencode.json"

# 验证
echo $env:OPENCODE_HOME
echo $env:OPENCODE_WORKSPACE
echo $env:OPENCODE_CONFIG

输出应分别显示：


D:\opencode
D:\opencode\projects

位置	含义	谁来用	什么时候用
C:\Users$env .opencode.json	用户全局配置（Unix/Linux传统）	opencode程序本身	程序启动时读取
%APPDATA%\opencode\opencode.json	Windows应用配置目录	opencode程序	可选的备选方案
D:\opencode\projects	你的工作区（代码项目存放）	你的项目文件	运行时存放代码

opencode的****配置文件查找顺序****（优先级从高到低）：


1️⃣ OPENCODE_CONFIG 环境变量指定的文件
        ↓ 如果找不到
2️⃣ ~/.opencode.json （用户主目录的隐藏文件）
        ↓ 如果找不到
3️⃣ %APPDATA%\opencode\opencode.json （Windows应用数据目录）
        ↓ 如果找不到
4️⃣ 项目目录下的.opencode.json
        ↓ 如果找不到
5️⃣ 内置默认配置

四、OpenCode环境安装

4.1 NPM方式安装OpenCode

使用npm全局安装

在PowerShell中执行：

powershell
npm install -g opencode-ai@latest

OpenCode 并不自带所有接口驱动。要连接 OpenAI 兼容格式的中转站，必须先在 PowerShell 中全局安装驱动包：


npm install -g @ai-sdk/openai

如果需要配置模型为配Gemini 或 Claude，对应的npm包名称为@ai-sdk/google，@ai-sdk/anthropic

4.2 验证安装

执行以下命令确认安装成功：


opencode --version

输出示例（版本号可能不同）：


1.4.7

如果显示"command not found"错误，执行以下命令：

powershell
npm list -g opencode-ai

查看实际安装路径，然后将该路径添加到环境变量PATH中。

4.3 配置LLM提供商中转API key（关键步骤）

由于 OpenCode 默认只列出主流官方提供商，若要使用中转站（如 aiguoguo199.com）提供的 gpt-5.4 模型，必须手动更改配置文件并输入API Key。

打开PowerShell（以管理员身份运行），输入opencode auth login，回车
在Select provider中直接拉到最下面，选择Other，输入Enter provider id为myproxy，回车
粘贴API Key，回车，完成

Enter provider id需要跟opencode.json的内容对应，具体位置可见json文件配置

powershell
PS C:\Users\test> opencode auth login

T  Add credential
|
o  Select provider
|  Other
|
o  Enter provider id
|  myproxy
|
!  This only stores a credential for myproxy - you will need configure it in opencode.json, check the docs for examples.
|
o  Enter your API key
|  •••••••••••••••••••••••••••••••••••••••••••••••••••
|
—  Done

4.4 启动OpenCode TUI

在PowerShell中执行：

powershell
cd D:\opencode\projects
opencode

进入TUI后输入：


/models

**成功标志：**能看到 myproxy/gpt-5.4 等配置的模型

如后期执行部署，需要选择自己喜欢的模行，在OpenCode TUI界面中，输入以下命令连接提供商：
/connect
系统将提示选择提供商。根据需要选择：

OpenCode Zen（推荐）：https://opencode.ai/auth

OpenAI: 提供OpenAI API密钥

Google Gemini: 提供Gemini API密钥

GitHub Copilot: 需要GitHub认证

输入API密钥

按照TUI提示，粘贴相应的API密钥。OpenCode将自动保存该密钥。

在TUI中输入：
/models
验证自己选择的模型即可

五、权限限制配置

5.1 配置权限文件

在你的 D:\opencode\config\opencode.json 中添加 permission 字段：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": { ... },
  "model": "myproxy/gpt-5.4",
  "permission": {
    "external_directory": {
      "*": "deny"
    },
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny"
    },
    "edit": "*: allow",
    "bash": "ask"
  }
}

5.2 启动OpenCode的正确方式

必须从项目目录启动：

powershell
cd D:\opencode\projects
opencode

5.3 验证权限限制

操作	命令	预期结果
列出当前目录	`/ls .`	✅ 允许
访问上级目录	`/ls ..`	❌ 拒绝
访问C盘	`/read C:\Windows\test.txt`	❌ 拒绝
编辑文件	`/edit src/app.js`	✅ 允许
运行命令	`/bash npm install`	⚠️ 需确认

5.4 常见权限问题

问题：尝试访问外部目录时显示permission denied

原因：你启动OpenCode的位置错误，或者从不同驱动器启动。

解决方案：

powershell
# 确保从项目目录启动
cd D:\opencode\projects
opencode

六、常用使用命令与功能

OpenCode 有两类方式与你交互：内置命令（你输入）和AI工具（AI自动使用）。

6.1内置命令（用户手动输入）

命令	功能说明	使用示例	说明
`opencode`	启动OpenCode TUI	`cd D:\opencode\projects && opencode`	必须从项目目录启动
`/init`	初始化项目，生成AGENTS.md	`/init`	帮助OpenCode理解项目结构
`/connect`	连接AI提供商，配置API密钥	`/connect`	选择提供商并输入密钥
`/models`	列出所有可用的AI模型	`/models`	查看已配置的模型列表
`/undo`	撤销上一步操作	`/undo`	回退最后一次AI修改
`/redo`	重做撤销操作	`/redo`	恢复被撤销的修改
`/share`	生成对话分享链接	`/share`	复制链接分享给团队成员
`/help`	显示所有可用命令	`/help`	查看命令帮助信息

6.2AI工具（AI自动使用，无需手动输入）

这些是OpenCode AI可以自动调用的能力。你不需要手动输入/ 来触发它们，而是直接和AI交互，AI会根据需要使用这些工具。

工具	功能	工作方式	示例场景
`ls`	列出目录文件	你说："查看src目录的内容" → AI使用ls工具	探索项目结构
`view`	查看文件内容	你说："看看package.json" → AI使用view工具	理解文件结构
`read`	读取文件（同view）	你说："读取配置文件" → AI使用read工具	分析代码
`write`	创建或完全覆写文件	你说："创建一个新组件" → AI使用write工具	生成新文件
`edit`	修改现有文件	你说："修改这个函数" → AI使用edit工具	代码编辑
`patch`	应用补丁（精确修改）	AI识别需要修改→应用patch	精确代码修改
`glob`	按模式查找文件	你说："找所有.ts文件" → AI使用glob工具	文件搜索
`grep`	在文件中搜索文本	你说："找所有import语句" → AI使用grep工具	内容搜索
`bash`	执行Shell命令	你说："运行npm install" → AI使用bash工具	运行脚本/命令

6.3两种工作模式（Tab键切换）

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

模式	功能	工具可用性	使用场景
*Build模式*（默认）	完整功能，可读写文件	✅ 所有工具可用	写代码、修改文件、运行命令
*Plan模式*（只读）	分析规划，不修改代码	❌ 禁用：write, edit, patch, bash	制定计划、分析代码、方案设计

切换方式：


按 Tab 键 → 看右下角的模式指示器切换

6.4完整的工作流示例

场景：我想添加一个新功能，但先让AI规划


1️⃣ 启动OpenCode（在项目目录）   cd D:\opencode\projects   opencode
2️⃣ 切换到Plan模式（只读、安全）   按 Tab 键 → 看右下角显示 "Plan"
3️⃣ 问AI如何实现   你输入：当用户点击删除按钮时，标记为软删除。然后创建一个恢复页面。   AI使用 ls, view, grep 等工具分析，给出计划
4️⃣ 满意计划后，切换到Build模式   按 Tab 键 → 看右下角显示 "Build"
5️⃣ 让AI执行   你输入：好的，开始实现   AI使用 edit, write, bash 等工具修改代码
6️⃣ 如果不满意，撤销   /undo → 回到步骤5之前   /redo → 恢复修改

6.5模式详解

Build模式（默认）

所有操作都允许：

✅ 读取文件（read, view）
✅ 创建文件（write）
✅ 修改文件（edit, patch）
✅ 运行命令（bash）
✅ 搜索文件（glob, grep）

*适用于：* 实际开发、调试、优化代码

Plan模式（规划模式）

只读操作允许，写操作被禁用：

✅ 读取文件（read, view）
✅ 搜索文件（glob, grep）
❌ 创建文件（write 禁用）
❌ 修改文件（edit, patch 禁用）
❌ 运行命令（bash 禁用）

适用于： 分析现有代码、制定实现方案、审查代码

6.6常见操作方式

方式1：直接对话（最常用）


你：在src/components中创建一个用户卡片组件AI：自动使用glob找.tsx文件 → view查看现有组件 → write创建新组件

方式2：引用文件


你：@src/types.ts 定义一个新的User接口AI：自动view查看当前的types → edit添加新接口

方式3：命令方式


你：/initOpenCode：生成AGENTS.md文件，记录项目信息

七、多项目配置

7.1 多项目管理原理

OpenCode 的配置优先级：

远程配置 - 组织默认配置（.well-known/opencode 端点）
全局配置 - 用户级配置（~/.config/opencode/opencode.json）
自定义配置 - 环境变量指定（OPENCODE_CONFIG 环境变量）
项目配置 - 项目级配置（项目目录下的 opencode.json）
代理配置 - .opencode 目录中的代理、命令、插件
内联配置 - 运行时环境变量（OPENCODE_CONFIG_CONTENT）

关键点：配置文件会自动合并，而不是覆盖。后加载的配置只覆盖有冲突的键，不影响其他设置。

7.2 创建多项目结构

推荐的目录结构：


D:\opencode\
├── config\                    # 全局配置（前面1-3章创建）
│   ├── opencode.json
│   └── auth.json
│
├── projects\                  # 项目根目录
│   ├── project-1\
│   │   ├── opencode.json      # 项目1特定配置
│   │   ├── src\
│   │   ├── package.json
│   │   └── .opencode\         # 代理、命令、技能目录
│   │
│   ├── project-2\
│   │   ├── opencode.json      # 项目2特定配置
│   │   ├── src\
│   │   ├── package.json
│   │   └── .opencode\
│   │
│   └── project-3\
│       ├── opencode.json      # 项目3特定配置
│       ├── src\
│       ├── package.json
│       └── .opencode\

7.3 项目特定配置文件

为项目1创建配置（D:\opencode\projects\project-1\opencode.json）：

json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "myproxy/gpt-5.4",
  
  "permission": {
    "external_directory": {
      "D:\\opencode\\projects\\**": "allow"
    },
    "bash": {
      "*": "ask",
      "npm *": "allow",
      "git *": "allow",
      "git push *": "deny",
      "rm *": "deny"
    },
    "edit": "allow",
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny"
    }
  },
  
  "snapshot": true,
  
  "formatter": {
    "prettier": {
      "extensions": [".js", ".jsx", ".ts", ".tsx", ".json"]
    }
  }
}

为项目2创建配置（D:\opencode\projects\project-2\opencode.json）：

json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "myproxy/gpt-5.4",
  
  "permission": {
    "external_directory": {
      "D:\\opencode\\projects\\**": "allow"
    },
    "bash": "ask",
    "edit": "allow"
  },
  
  "snapshot": true
}

7.4 启动特定项目

启动项目1：

powershell
cd D:\opencode\projects\project-1
opencode

启动项目2：

powershell
cd D:\opencode\projects\project-2
opencode

OpenCode 会自动在启动目录查找 opencode.json，然后与全局配置合并。无需指定 --config 参数。

7.5 项目级权限隔离

如果需要严格隔离（项目1完全不能访问项目2的代码），使用 external_directory：

项目1的隔离配置：

json
{
  "$schema": "https://opencode.ai/config.json",
  
  "permission": {
    "external_directory": {
      "D:\\opencode\\projects\\project-1\\**": "allow",
      "*": "deny"
    },
    "read": {
      "*": "allow",
      "*.env": "deny"
    },
    "edit": "allow"
  }
}

现在OpenCode在项目1中只能访问项目1目录，对其他外部目录（包括项目2）的访问会被拒绝。

7.6 使用环境变量指定全局配置

如果想为所有项目使用统一的全局配置，使用 OPENCODE_CONFIG 环境变量（opencode.ai1）：

powershell
# 设置全局配置路径
[Environment]::SetEnvironmentVariable("OPENCODE_CONFIG", "D:\opencode\config\opencode.json", "User")

# 刷新当前会话
$env:OPENCODE_CONFIG = "D:\opencode\config\opencode.json"

# 验证
echo $env:OPENCODE_CONFIG

此后，启动任何项目的OpenCode时，都会先读取这个全局配置，然后与项目目录下的 opencode.json 合并。

7.7 配置合并示例

全局配置 (D:\opencode\config\opencode.json)：

json
{
  "model": "myproxy/gpt-5.4",
  "autoupdate": true,
  "permission": {
    "bash": "ask"
  }
}

项目1配置 (D:\opencode\projects\project-1\opencode.json)：

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

合并结果（项目1实际生效的配置）：

json
{
  "model": "myproxy/gpt-5.4",           // 继承全局
  "autoupdate": true,                   // 继承全局
  "permission": {
    "bash": "allow",                    // 项目级覆盖
    "edit": "deny"                      // 项目级新增
  }
}

7.8 避免的常见错误

错误做法	❌ 为什么不对	✅ 正确做法
在config中写`workspaceDirectory`	此字段不存在	直接从项目目录启动opencode
使用`opencode --config path`	不支持此参数	设置`OPENCODE_CONFIG`环境变量
在permission中直接写path规则	应该用`external_directory`	见7.5示例
配置`ignorePatterns`	此字段不存在	使用`.opencodeignore`文件（如果支持）
在json配置中设`maxTokens`	这是实验功能环境变量	使用`OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`

7.9 配置文件位置总结表

位置	用途	创建位置	何时读取
全局配置	所有项目通用设置	`~/.config/opencode/opencode.json`（Linux/Mac）或 `%APPDATA%\opencode\opencode.json`（Windows）	OpenCode启动时
Windows用户主目录	Windows特定全局配置	`C:\Users\$env:USERNAME\.opencode.json`	如果`~/.config`不存在
项目配置	该项目特定配置	项目根目录下 `opencode.json`	启动该项目时
环境变量指定	自定义全局配置位置	由`OPENCODE_CONFIG`指向的任意路径	优先级最高（除托管配置）
项目代理/命令	项目特定代理、命令、技能	项目根目录下 `.opencode/` 目录	启动项目时自动加载

八、扩展使用方法

8.1 插件（Plugins）安装与使用

插件是 OpenCode 最强大的扩展方式，可添加自定义工具、事件钩子、外部集成。

配置方式

在 opencode.json（全局或项目级）中添加 plugin 数组：

json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session@latest",
    "@my-org/custom-plugin"
  ]
}

本地插件目录（推荐）

项目级（推荐多项目隔离）：D:\opencode\projects\您的项目\.opencode\plugins\
全局：C:\Users\您的用户名\.opencode\plugins\（或软链接指向的位置）

插件文件为 .js 或 .ts，自动加载。
安装 npm 插件后执行 opencode 重启即可生效（或 opencode update）。

创建简单插件示例（notification.js）：

js
export const NotificationPlugin = async ({ $ }) => ({
  "session.idle": async () => {
    await $`echo "OpenCode 会话已空闲" > session.log`
  }
})

更多钩子（command、tool、lsp、file 等）详见官方 https://opencode.ai/docs/plugins/。

8.2 自定义 Agents（智能代理）

Agents 是专用 AI 助手，可为不同任务（代码审查、文档生成等）定制模型、提示词和权限。

创建方式（推荐两种，均支持）

方式一：Markdown 文件（最灵活，推荐）

powershell
mkdir D:\opencode\projects\您的项目\.opencode\agents

新建 code-reviewer.md（文件名即 Agent 名）

markdown
---
description: AI代码审查agent
mode: subagent
model: gpt-4o          # 或 anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
You are an expert code reviewer. Analyze code for bugs, performance issues, security vulnerabilities, and best practices. Provide constructive feedback only.

方式二：opencode.json 中定义

json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "AI代码审查agent",
      "mode": "subagent",
      "model": "gpt-4o",
      "prompt": "You are an expert code reviewer...",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

使用命令：

交互式创建：opencode agent create（推荐，会自动生成 MD 文件）
TUI 中调用子代理：@code-reviewer 帮我审查这段代码
主代理切换：按 Tab 键循环

权限支持 ask / allow / deny 以及 glob 细粒度控制（如 "bash": { "git push": "ask" }）。

8.3 自定义 Commands（自定义命令）

自定义命令让您用 /test、/review 等快捷方式执行重复提示词任务。

创建方式

方式一：Markdown 文件（推荐）

powershell
mkdir D:\opencode\projects\您的项目\.opencode\commands

新建 test.md：

markdown
---
description: 运行测试套件
agent: build
model: gpt-4o
---
Run the full test suite: !`npm test -- --coverage`
Focus on failing tests and suggest fixes.

方式二：opencode.json

json
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "description": "运行测试套件",
      "template": "Run the full test suite: !`npm test -- --coverage` ...",
      "agent": "build"
    }
  }
}

高级用法（在模板中支持）：

参数：$ARGUMENTS 或 $1、$2（例：/component Button）
执行 Shell：!npm run build``（反引号）
引用文件：@src/utils.js（自动注入文件内容）

使用：在 TUI 直接输入 /test 或 /review src/App.tsx

8.4 自定义 Tools（自定义工具）

允许 LLM 在对话中调用您编写的函数（可封装任意语言脚本）。

创建位置：

项目级：D:\opencode\projects\您的项目\.opencode\tools\
全局：~/.config/opencode/tools/

示例（database.ts）：

ts
import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "查询项目数据库",
  args: { query: tool.schema.string().describe("SQL 查询语句") },
  async execute(args) {
    return `执行结果：${args.query}`
  }
})

文件名即工具名，可在 Agent/Commands 中被 LLM 自动调用。自定义工具优先于内置工具。

8.5 多模型与 Provider 配置

支持同时配置多个 LLM 提供商，并随时切换。

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "apiKey": "sk-...",
      "models": {
        "gpt-4o": { "name": "gpt-4o" }
      }
    },
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "google": {
      "apiKey": "AIza..."
    }
  },
  "defaultProvider": "openai"
}

TUI 操作：

/models —— 列出所有可用模型
/model gpt-4o —— 切换模型

8.6 TUI 界面自定义（快捷键与外观）

快捷键、主题等在独立配置文件 tui.json 中设置（非 opencode.json）。

创建位置：

项目级：D:\opencode\projects\您的项目\tui.json
全局：~/.config/opencode/tui.json

示例：

json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "keybinds": {
    "leader": "ctrl+x",
    "switchAgent": "tab"
  },
  "scroll_speed": 3
}

使用建议

所有 .opencode/ 修改后重启 opencode 生效。

多项目推荐项目级 .opencode/ 配置。

全局配置放软链接目录，便于所有项目共享。

查看当前加载的扩展：输入 /debug config 或 /help。

九、性能优化建议

OpenCode 性能优化主要通过 opencode.json（或 opencode.jsonc）中的 snapshot、compaction 以及 provider 配置实现。

9.1 大型项目优化

对于大型仓库（超过 1000 个文件、多个子模块或文件列表极长的项目）：

快照（snapshot）系统会使用内部 Git 仓库跟踪所有更改，在大型项目中可能导致索引变慢和显著的磁盘占用。

推荐配置（在项目根目录或配置目录下的 opencode.json 中添加）：

json
{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false
}

snapshot: false 可大幅提升大型项目启动和操作速度，同时禁用 UI 回滚功能（代理修改无法通过界面撤销）。
v1.4.6 已优化“快照分级性能”，并让快照完全尊重 .gitignore（包括之前已被跟踪的文件）。
如果仍需保留快照功能，建议先清理 .gitignore 并确保排除 node_modules/**、.git/**、 dist/**、 build/** 等目录。

9.2 上下文 / 内存管理（Compaction）

OpenCode 通过 compaction 自动管理会话上下文 token 占用，这是官方提供的内存/上下文优化手段。

推荐配置：

json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

参数说明：

auto: true —— 上下文满时自动压缩（默认开启）。
prune: true —— 自动移除旧的工具输出，释放 token。
reserved —— 保留的 token 数量（默认值通常为 10000，根据实际模型调整）。

此配置可有效防止长时间会话导致的内存占用过高问题。

9.3 网络请求优化

网络相关配置统一放在 provider 下（支持 Anthropic、OpenAI、Ollama 等所有提供商）。

推荐配置示例（以 Anthropic 为例，其他提供商同理）：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 300000,
        "chunkTimeout": 30000
      }
    }
  }
}