OpenCode 是一个开源 AI 编码助手，帮助您在终端、IDE 或桌面应用中编写代码。

快速开始

选择您喜欢的安装方式：

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

或使用包管理器：

# NPM
npm install -g opencode-ai

# Bun
bun install -g opencode-ai

# Homebrew
brew install anomalyco/tap/opencode

# Arch Linux (paru)
paru -S opencode-bin

基本使用

安装完成后，在项目目录中运行：

cd /path/to/your/project
opencode

首次使用时，运行 /init 命令初始化项目配置。

核心功能

• LSP 支持 - 自动为 LLM 加载正确的语言服务器
• 多会话 - 在同一项目上并行启动多个助手会话
• 分享链接 - 分享会话链接供参考或调试
• Claude Pro - 使用您的 Claude Pro 或 Max 订阅
• ChatGPT Plus/Pro - 使用您的 ChatGPT 订阅
• 75+ 模型 - 支持 75+ LLM 提供商
• 任何编辑器 - 终端、桌面应用、IDE 扩展

配置

OpenCode 使用 JSONC（带注释的 JSON）配置文件，支持多级配置优先级。

配置文件格式

配置文件使用 JSONC 格式（带注释的 JSON）。文件名为 opencode.json 或 opencode.jsonc。

配置优先级

配置按以下优先级加载（从高到低）：

配置结构

完整的配置文件结构如下：

{
  // TUI 设置
  "tui": {
    "theme": "opencode"
  },
  
  // 服务器设置
  "server": {
    "port": 8080
  },
  
  // 工具设置
  "tools": {
    "bash": {
      "enabled": true
    }
  },
  
  // 模型设置
  "models": {
    "default": "anthropic/claude-sonnet-4-20250514",
    "big": "anthropic/claude-sonnet-4-20250514",
    "fast": "anthropic/claude-3-5-haiku-latest"
  },
  
  // 代理设置
  "agents": {
    "default": "default"
  },
  
  // 自定义命令
  "commands": {},
  
  // 提供商设置
  "providers": {},
  
  // LSP 设置
  "lsp": {},
  
  // MCP 服务器
  "mcp": {
    "servers": {}
  },
  
  // 权限
  "permissions": {
    "auto_approve": []
  },
  
  // 快捷键
  "keybinds": {},
  
  // 其他
  "disabled_providers": [],
  "custom_instructions": ""
}

环境变量

配置值支持环境变量替换：

• $VAR - 引用环境变量 VAR
• ${VAR} - 同上
• ${VAR:-default} - 如果 VAR 未设置，使用默认值

提供商

OpenCode 支持 75+ LLM 提供商。通过 models.dev 提供统一的模型访问。

主要提供商

配置提供商

在配置文件中设置提供商：

{
  "providers": {
    "anthropic": {
      "apiKey": "$ANTHROPIC_API_KEY"
    },
    "openai": {
      "apiKey": "$OPENAI_API_KEY",
      "baseUrl": "https://api.openai.com/v1"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  }
}

使用 Claude Pro / ChatGPT Plus

OpenCode 支持使用您现有的 AI 订阅账号：

# 使用 Anthropic 账号登录（Claude Pro/Max）
opencode auth login anthropic

# 使用 OpenAI 账号登录（ChatGPT Plus/Pro）
opencode auth login openai

网络

配置代理、SSL 证书和网络相关设置。

代理设置

OpenCode 支持通过环境变量配置 HTTP/HTTPS 代理：

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

自定义 CA 证书

对于企业网络，可以配置自定义 CA 证书：

export NODE_EXTRA_CA_CERTS=/path/to/ca-certificates.crt

企业版

OpenCode 企业版为组织提供增强的安全性、合规性和管理功能。

企业功能

• SSO 集成 - 支持 SAML、OIDC 单点登录
• 审计日志 - 完整的使用审计跟踪
• 集中管理 - 统一配置和策略管理
• 私有部署 - 支持本地部署
• 优先支持 - 专属技术支持通道

终端界面 (TUI)

OpenCode TUI 是功能最全面的客户端，提供丰富的终端界面体验。

启动 TUI

cd /path/to/your/project
opencode

文件引用

在对话中引用文件：

• @filename - 引用文件
• @folder/ - 引用文件夹
• @**/*.ts - 使用 glob 模式

Bash 命令

直接运行 bash 命令：

• $ command - 运行并返回输出
• $$ command - 运行并将输出添加到上下文

斜杠命令

快捷键

命令行 (CLI)

OpenCode CLI 提供强大的命令行工具，支持自动化和脚本集成。

主要命令

常用标志

# 指定配置文件
opencode --config /path/to/config.json

# 指定工作目录
opencode --cwd /path/to/project

# 详细输出
opencode --verbose

# 版本信息
opencode --version

非交互式运行

# 单次执行
opencode run "解释这个代码"

# 从文件读取
opencode run --file prompt.txt

# 指定模型
opencode run --model anthropic/claude-sonnet-4-20250514 "你的问题"

# 管道输入
echo "解释这段代码" | opencode run

环境变量

Web 界面

OpenCode 提供基于 Web 的界面，可通过浏览器访问。

启动 Web 界面

# 启动 Web 服务器
opencode web

# 指定端口
opencode web --port 3000

# 指定主机
opencode web --host 0.0.0.0

启动后，在浏览器中访问 http://localhost:3000。

IDE 扩展

OpenCode 提供 VS Code 等 IDE 的扩展，实现无缝集成。

VS Code 扩展

在 VS Code 扩展市场搜索 "OpenCode" 或使用命令：

code --install-extension opencode.opencode

功能特性

• 内联建议 - 在编辑器中获取 AI 建议
• 侧边栏面板 - 专用的对话面板
• 上下文感知 - 自动包含相关文件上下文
• 快捷命令 - 通过命令面板快速访问

Zen

OpenCode Zen 提供经过优化和测试的 AI 模型访问服务。

什么是 Zen？

Zen 是 OpenCode 的托管服务，提供一套精选的 AI 模型。这些模型经过 OpenCode 团队针对编码助手场景进行了专门测试和基准测试，确保一致的性能和质量。

Zen 的优势

• 经过验证的模型 - 所有模型都经过编码场景测试
• 稳定性能 - 不必担心不同提供商的质量差异
• 简化配置 - 无需管理多个 API 密钥
• 自动更新 - 自动获取最新的模型改进

启用 Zen

opencode auth login zen

分享

分享会话链接，便于团队协作和调试。

分享会话

使用 /share 命令或快捷键生成分享链接：

/share

隐私说明

• 分享是可选的，默认不会分享任何内容
• 分享的链接只包含对话历史，不包含本地文件
• 您可以随时撤销分享链接

GitHub

OpenCode 与 GitHub 深度集成，支持 PR 审查、Issue 处理等功能。

GitHub 认证

opencode github login

功能特性

• PR 审查 - 使用 AI 审查 Pull Request
• Issue 分析 - 分析和回复 Issue
• 代码搜索 - 搜索仓库中的代码
• 自动提交 - 生成提交消息

GitLab

OpenCode 同样支持 GitLab 集成。

GitLab 认证

opencode gitlab login

工具

OpenCode 提供丰富的内置工具，扩展 AI 助手的能力。

内置工具

配置工具

{
  "tools": {
    "bash": {
      "enabled": true,
      "timeout": 30000
    },
    "edit": {
      "enabled": true
    },
    "webfetch": {
      "enabled": true,
      "maxSize": 1048576
    }
  }
}

规则

使用规则文件自定义 AI 助手的行为。

规则文件

在项目根目录创建 .opencode/rules.md 或 AGENTS.md 文件：

# 项目规则

## 编码规范
- 使用 TypeScript 严格模式
- 所有函数必须有 JSDoc 注释
- 使用 ESLint 和 Prettier

## 架构
- 遵循 Clean Architecture 原则
- 使用依赖注入

## 测试
- 所有新功能必须有单元测试
- 测试覆盖率 > 80%

自定义指令

在配置文件中设置全局自定义指令：

{
  "custom_instructions": "始终使用中文回复。代码注释使用英文。"
}

代理

代理是预配置的 AI 角色，针对特定任务进行了优化。

内置代理

• default - 通用编码助手
• code-review - 代码审查专家
• test-writer - 测试用例编写
• doc-writer - 文档编写

切换代理

opencode agent use code-review

自定义代理

{
  "agents": {
    "my-agent": {
      "name": "My Custom Agent",
      "description": "专注于 React 开发",
      "system_prompt": "你是一个专业的 React 开发专家...",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

模型

配置和管理 AI 模型。

模型配置

{
  "models": {
    // 默认模型
    "default": "anthropic/claude-sonnet-4-20250514",
    
    // 大型复杂任务
    "big": "anthropic/claude-sonnet-4-20250514",
    
    // 快速简单任务
    "fast": "anthropic/claude-3-5-haiku-latest"
  }
}

推荐模型

切换模型

在 TUI 中使用 /models 命令切换模型。

主题

自定义 OpenCode TUI 的外观。

内置主题

• opencode - 默认主题
• catppuccin - Catppuccin 风格
• dracula - Dracula 风格
• gruvbox - Gruvbox 风格
• nord - Nord 风格
• solarized - Solarized 风格
• tokyo-night - Tokyo Night 风格

切换主题

在 TUI 中使用 /theme 命令，或在配置中设置：

{
  "tui": {
    "theme": "catppuccin"
  }
}

自定义主题

在 ~/.config/opencode/themes/ 目录创建 JSON 主题文件。

快捷键

自定义键盘快捷键。

默认快捷键

自定义快捷键

{
  "keybinds": {
    "ctrl+k": "clear",
    "ctrl+m": "models",
    "ctrl+t": "theme"
  }
}

命令

自定义快捷命令。

定义自定义命令

{
  "commands": {
    "test": {
      "description": "运行测试",
      "command": "npm test"
    },
    "build": {
      "description": "构建项目",
      "command": "npm run build"
    },
    "lint": {
      "description": "代码检查",
      "command": "npm run lint"
    }
  }
}

格式化器

配置代码格式化工具。

支持的格式化器

• prettier - JavaScript/TypeScript/CSS/HTML
• black - Python
• gofmt - Go
• rustfmt - Rust
• clang-format - C/C++

自动格式化

OpenCode 会自动检测项目中的格式化配置文件（如 .prettierrc）并应用。

权限

控制 AI 助手的操作权限。

权限配置

{
  "permissions": {
    // 自动批准的操作
    "auto_approve": [
      "read",
      "grep",
      "glob",
      "list"
    ],
    
    // 需要确认的操作
    "require_confirm": [
      "write",
      "edit",
      "bash"
    ],
    
    // 禁止的操作
    "deny": []
  }
}

操作类型

• read - 读取文件
• write - 写入文件
• edit - 编辑文件
• bash - 执行命令
• webfetch - 获取网页

LSP

语言服务器协议支持，为 AI 提供代码智能。

自动检测

OpenCode 会自动检测项目类型并加载相应的语言服务器。

支持的语言

• TypeScript / JavaScript
• Python
• Go
• Rust
• Java
• C / C++
• Ruby
• PHP

手动配置

{
  "lsp": {
    "typescript": {
      "enabled": true,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": {
      "enabled": true,
      "command": "pylsp"
    }
  }
}

MCP 服务器

Model Context Protocol 服务器扩展 AI 能力。

什么是 MCP？

MCP（Model Context Protocol）是一个开放协议，允许 AI 模型与外部工具和服务交互。 通过 MCP 服务器，您可以扩展 OpenCode 的能力。

配置 MCP 服务器

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "$GITHUB_TOKEN"
        }
      }
    }
  }
}

常用 MCP 服务器

• filesystem - 文件系统访问
• github - GitHub API 访问
• postgres - PostgreSQL 数据库
• puppeteer - 浏览器自动化
• brave-search - 网页搜索

ACP

Agent Communication Protocol - 代理通信协议。

关于 ACP

ACP 允许多个 AI 代理之间进行通信和协作，实现复杂的多代理工作流。

技能

技能是可复用的 AI 工作流模板。

内置技能

• refactor - 代码重构
• explain - 代码解释
• test - 生成测试
• document - 生成文档
• optimize - 性能优化

使用技能

# 在对话中使用
@skill refactor @myfile.ts

自定义工具

创建自定义工具扩展 AI 能力。

定义自定义工具

{
  "tools": {
    "custom": {
      "my-tool": {
        "name": "my-tool",
        "description": "我的自定义工具",
        "command": "python",
        "args": ["my-tool.py"],
        "parameters": {
          "type": "object",
          "properties": {
            "input": {
              "type": "string",
              "description": "输入参数"
            }
          },
          "required": ["input"]
        }
      }
    }
  }
}

SDK

使用 OpenCode SDK 构建自定义集成。

安装 SDK

npm install @opencode/sdk

基本使用

import { OpenCode } from '@opencode/sdk';

const client = new OpenCode({
  apiKey: process.env.OPENCODE_API_KEY
});

const response = await client.chat({
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});

console.log(response.content);

服务器

运行 OpenCode 服务器模式。

启动服务器

# 启动服务器
opencode serve

# 指定端口
opencode serve --port 8080

# 启用认证
opencode serve --auth

API 端点

• POST /api/chat - 对话接口
• GET /api/sessions - 会话列表
• GET /api/models - 可用模型
• GET /api/health - 健康检查

插件

使用插件扩展 OpenCode 功能。

安装插件

opencode plugin install <plugin-name>

插件目录

浏览社区插件：opencode.ai/plugins

生态系统

OpenCode 生态系统和社区资源。

官方资源

• GitHub 仓库
• Discord 社区
• X (Twitter)

相关项目

• Models.dev - LLM 模型目录
• MCP - Model Context Protocol

贡献指南

我们欢迎社区贡献！请查看 贡献指南 了解如何参与。