OpenCode
入门文档

从安装到第一次对话

OpenCode 把 AI 代理带进终端、桌面与 IDE，帮助你处理代码阅读、生成和调试任务。

ⓘ　桌面客户端正在公测 macOS、Windows 与 Linux 版本均可体验，适合希望保留图形化工作流的团队。

快速启动

选择你的系统习惯的安装方式：

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

或使用包管理器：

npm / bun / brew / paru
npm install -g opencode-ai
brew install anomalyco/tap/opencode
paru -S opencode-bin

在项目中运行

安装完成后进入项目目录，再运行：

bash
cd /path/to/your/project
opencode

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

常用能力

  • 代码上下文 - 让模型理解文件关系与项目约定
  • 隔离会话 - 为不同目标保留独立的讨论空间
  • 共享审阅 - 用链接同步修改思路和结果
  • 账号复用 - 连接你已经在使用的模型订阅
  • 云端与本地 - 根据任务选择模型来源
  • 跨端工作 - 在终端、桌面或 IDE 之间切换

配置你的工作区

OpenCode 使用支持注释的 JSONC 配置文件管理模型、工具与权限，文件名为 opencode.json 或 opencode.jsonc。

配置优先级

优先级位置说明
1自定义路径通过 --config 指定
2项目配置.opencode/opencode.json
3全局配置~/.config/opencode/opencode.json

配置结构

jsonc
{ "tui": { "theme": "opencode" }, "server": { "port": 8080 }, "models": { "default": "anthropic/claude-sonnet-4" } }

环境变量

  • $VAR - 引用环境变量 VAR
  • ${VAR:-default} - 未设置时使用默认值

连接模型提供商

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

Anthropic

提供 Claude 系列模型，可复用 Claude Pro 或 Max 账号。

ANTHROPIC_API_KEY

OpenAI

提供 GPT 系列模型，可连接 ChatGPT Plus 或 Pro。

OPENAI_API_KEY

Google

提供 Gemini Pro、Flash 等模型选项。

GOOGLE_API_KEY

DeepSeek

高性能编码模型。

DEEPSEEK_API_KEY

Ollama

本地运行开源模型。

OLLAMA_HOST

OpenRouter

用一个入口管理多个模型提供商。

OPENROUTER_API_KEY

连接已有账号

bash
opencode auth login anthropic
opencode auth login openai

网络与企业环境

在代理、企业证书或受限网络中运行时，按环境设置连接参数。

代理设置

bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

团队与企业使用

团队可以围绕身份、审计、策略和部署方式建立更可控的 AI 编程环境。

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

终端界面 (TUI)

终端界面适合需要快速浏览项目、调用工具和连续对话的开发者。

  • @filename - 引用文件
  • $ command - 运行 Bash 命令
  • /init - 初始化项目
  • /models - 切换模型
  • /share - 分享当前会话

命令行 (CLI)

CLI 适合脚本化任务、批处理和持续集成环境。

命令说明
opencode启动 TUI
opencode run非交互式运行
opencode auth认证管理
opencode models模型管理
opencode serve启动服务器

常用标志

bash
opencode --config /path/to/config.json
opencode --cwd /path/to/project
opencode --version

Web 界面

运行 opencode web --port 3000 后，在浏览器访问 http://localhost:3000。

IDE 扩展

在 VS Code、Cursor、Zed 等编辑器中使用 OpenCode，支持内联建议、侧边栏对话和上下文感知。

Zen

面向编码场景筛选的稳定模型组合。

分享

使用 /share 创建只读会话链接，方便团队参考和调试。

GitHub

连接 GitHub 后，OpenCode 可以分析 Issue、审查 Pull Request 和搜索代码。

GitLab

支持 GitLab Merge Request 审查与 Issue 跟踪。

工具

内置文件、Bash、编辑和搜索工具，可按项目权限进行控制。

规则

在项目中添加 AGENTS.md 或自定义指令，为模型提供长期上下文。

代理

使用不同代理处理规划、编码、审查等任务。

模型

使用 /models 在 75+ 模型间快速切换。

主题

使用 /theme 切换内置主题，也可以自定义颜色。

快捷键

快捷键功能
Ctrl+C取消当前操作
Ctrl+L清屏
Enter发送消息
Esc返回/取消

命令

在 opencode.json 中定义团队自定义命令。

格式化器

保存文件时自动调用项目配置的格式化器。

权限

可以为读取、写入、执行工具分别设置允许、询问和拒绝。

LSP

OpenCode 自动检测语言服务器，也支持手动配置。

MCP 服务器

连接 Model Context Protocol 服务器，为会话添加外部工具。

ACP

通过 Agent Client Protocol 连接外部客户端。

技能

使用可复用技能扩展代理的专业能力。

自定义工具

通过插件和 SDK 定义自定义工具。

SDK

安装 SDK，将 OpenCode 能力集成到自己的应用。

bash
npm install @opencode/sdk

服务器

使用服务器模式提供 API。

bash
opencode serve --port 8080

插件

使用 opencode plugin install <plugin-name> 扩展 OpenCode 功能。

生态系统

欢迎参与社区贡献，访问 GitHub 仓库、Discord 和贡献指南。