Token Switch 文档中心

中文

English

中文

English

Appearance

OpenCode配置 ​

1、安装 OpenCode ​

1.1、macOS / Linux 安装 ​

macOS：按 ⌘ Command + 空格，输入Terminal回车

Linux：点击左下角应用菜单，搜索Terminal并回车

在Terminal中运行以下命令安装OpenCode：

bash
curl -fsSL https://opencode.ai/install | bash

验证 OpenCode 安装

安装完成后，输入以下命令检查是否安装成功：

bash
opencode --version

1.2、Windows 安装 ​

点击"开始"按钮，在查询框输入：powershell，以管理员权限打开终端

使用 PowerShell 安装：

powershell
irm https://opencode.ai/install.ps1 | iex

其他安装方式：

  • 使用 Chocolatey：

    powershell
    choco install opencode

  • 使用 Scoop：

    powershell
    scoop install opencode

  • 使用 NPM：

    powershell
    npm install -g opencode-ai

验证 OpenCode 安装

安装完成后，输入以下命令检查是否安装成功：

powershell
opencode --version

建议使用 PowerShell 而不是 CMD，功能更强大

如果遇到权限问题，以管理员身份运行 PowerShell

2、配置凭证 ​

2.1、配置文件方式（推荐） ​

OpenCode 启动时会自动读取配置文件中的凭证，无需设置环境变量。

全局配置（用户级） ​

编辑 ~/.config/opencode/opencode.json 文件：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "你的令牌"
    }
  },
  "model": "anthropic/claude-sonnet-4-20250514"
}

项目级配置 ​

在项目根目录创建 opencode.json 文件（覆盖全局配置）：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "你的令牌",
      "baseUrl": {{apiUrl}}
    }
  }
}

配置优先级：

  1. 项目根目录 ./opencode.json （最高）
  2. 用户主目录 ~/.config/opencode/opencode.json
  3. 命令行参数 --api-key / --base-url （最低）

2.2、环境变量方式 ​

macOS / Linux 配置 ​

参照1.1小节，进入Terminal，编辑您的 shell 配置文件（根据您使用的 shell）：

对于 zsh（默认）：

bash
# 将opencode的环境变量添加到 ~/.zshrc 文件中：
echo 'export OPENCODE_API_KEY="■■API■■"' >> ~/.zshrc
echo 'export OPENCODE_BASE_URL={{apiUrl}}' >> ~/.zshrc
# 使配置生效：
source ~/.zshrc

对于 bash：

bash
# 将opencode的环境变量添加到 ~/.bash_profile
echo 'export OPENCODE_API_KEY="■■API■■"' >> ~/.bash_profile
echo 'export OPENCODE_BASE_URL={{apiUrl}}' >> ~/.bash_profile
# 使配置生效：
source ~/.bash_profile

Windows 配置 ​

在 PowerShell 中运行以下命令设置用户级环境变量：

powershell
[System.Environment]::SetEnvironmentVariable("OPENCODE_API_KEY", "■■API■■", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("OPENCODE_BASE_URL", {{apiUrl}}, [System.EnvironmentVariableTarget]::User)

或直接设置系统环境变量：右键此电脑 → 属性 → 高级系统设置 → 环境变量 → 新建用户变量

3、启动参数配置 ​

3.1、环境变量方式（推荐） ​

bash
# macOS / Linux
export OPENCODE_API_KEY="你的令牌"
export OPENCODE_BASE_URL={{apiUrl}}

3.2、命令行参数方式 ​

bash
opencode --api-key "你的令牌" --base-url {{apiUrl}}

3.3、配置文件方式 ​

在项目根目录创建 opencode.json 文件：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenswitch": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenSwitch",
      "options": {
        "baseURL": {{apiUrl}},
        "apiKey": "你的令牌"
      },
      "models": {
        "model-id": {
          "name": "模型名称"
        }
      }
    }
  }
}

3.4、完整启动参数说明 ​

参数说明示例
--api-keyAPI认证令牌--api-key "sk-xxx"
--base-url中转API地址--base-url
--model指定使用的模型--model "claude-sonnet-4-20250514"
--theme界面主题--theme "dark"
--no-git禁用git集成--no-git
--verbose详细日志输出--verbose

4、加载使用文件的路径注意事项 ​

4.1、配置文件加载路径 ​

OpenCode会按以下顺序查找配置文件：

  1. 当前项目根目录：./opencode.json 或 ./opencode.jsonc
  2. 用户主目录：~/.config/opencode/opencode.json

4.2、项目说明文件 ​

OpenCode会自动读取项目中的说明文件来理解项目上下文：

  • AGENTS.md - 项目级指令说明（推荐）
  • CLAUDE.md - 兼容Claude Code格式
  • README.md - 项目说明

建议在项目根目录创建 AGENTS.md 文件，写入项目规范（如：始终使用TypeScript、测试框架是Vitest、缩进用2空格）

4.3、MCP服务器配置 ​

MCP服务器配置文件路径：

~/.config/opencode/mcp.json

配置示例：

json
{
  "servers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

4.4、工作目录 ​

  • OpenCode默认在当前执行命令的目录下运行
  • 使用 cd 命令切换到项目目录后再启动OpenCode
  • 所有文件操作都基于当前工作目录

5、开始使用 ​

安装配置完成后，在项目根目录下输入 opencode：

bash
# 定位到项目所在文件夹
cd your-project

# 启动OpenCode
opencode

你可以直接通过对话的方式下指令与它交流：

  • 探索代码库： opencode "解释这个项目的权限校验逻辑是怎么实现的"
  • 修复 Bug： opencode "修复用户登录时 500 的错误，参考 logs/error.log 中的报错信息"
  • 编写测试： opencode "为 auth.service.ts 编写单元测试并运行，直到所有测试通过"
  • 自动化任务： opencode "把项目中所有过时的 API 调用更新为 v2 版本，并运行 lint 修复格式"

6、常用内置指令说明 ​

在 opencode 的交互界面中，可以使用斜杠进行命令交互：

6.1、基础指令 ​

指令说明
/help显示帮助信息
/init初始化项目，分析项目结构并创建 AGENTS.md 文件
/connect连接 LLM provider（OpenAI、Anthropic等）
/models查看和切换使用的 AI 模型
/clear清除当前对话上下文
/exit退出OpenCode
/quit退出OpenCode（同 /exit）

6.2、会话管理 ​

指令说明
/compact压缩对话历史，节省token
/history查看对话历史
/resume恢复之前的会话

6.3、文件操作 ​

指令说明
/read <file>读取指定文件内容
/edit <file>编辑指定文件
/write <file>写入文件

6.4、模型与配置 ​

指令说明
/model切换AI模型
/config查看/修改配置
/theme切换界面主题

6.5、开发辅助 ​

指令说明
/run <cmd>执行Shell命令
/gitGit相关操作
/test运行测试
/lint代码检查

6.6、计划模式与模式切换 ​

切换 Plan Mode（计划模式）

按 Tab 键进入或退出 Plan Mode

  • Plan Mode：OpenCode 只制定方案，不进行修改，用于大规模改动前的规划
  • Build Mode（默认）：OpenCode 可以进行代码修改

在要求OpenCode进行大规模改动前，先切换到计划模式让它说出计划，确认后再切换回 Build Mode 执行。避免理解错误后导致大量无效修改。

7、使用技巧 ​

7.1、及时使用 /clear ​

不要在一个会话里聊太久。当一个任务完成后，立即输入 /clear。过时的上下文会随着每一条新消息被重复发送，产生不必要的费用。

7.2、利用项目说明文件 ​

在项目根目录创建 AGENTS.md。在这里写入项目的规范（如：始终使用TypeScript、测试框架是Vitest、缩进用2空格）。

  • 好处： 这样你就不需要在每次对话中重复这些要求，减少了输入Token。

7.3、善用计划模式 ​

在要求OpenCode进行大规模改动前，按 Tab 键进入 Plan Mode。

在 Plan Mode 下，OpenCode 只会制定方案而不进行实际修改。确认方案无误后，再按 Tab 键切换回 Build Mode 执行。这样可以避免理解错误后导致大量无效修改和不必要的费用。

7.4、使用 /compact 压缩上下文 ​

当对话变长时，使用 /compact 指令压缩对话历史，可以在保持上下文的同时减少token消耗。

7.5、多模型切换 ​

使用 /model 指令可以随时切换不同的AI模型，根据任务复杂度选择合适的模型：

  • 简单任务：使用较轻量的模型
  • 复杂任务：使用更强大的模型