OpenCode 完全指南：2026 年开始使用 OpenCode 必知的一切

什么是 OpenCode

凌晨 2 点，你的 Docker 又挂了。你盯着终端，心想：肯定有更好的办法。OpenCode 不会帮你修 Docker，但它能帮你少熬夜写代码——这就够了。

这东西不仅能在终端（TUI）、IDE 和桌面端运行，还兼容 Claude、GPT、Gemini 等 75+ 模型提供商。

和一般的聊天机器人不一样，它能深度集成到你的开发工作流。它可以读取和编辑文件、执行 Shell 命令、审查 Pull Request、管理会话，甚至编排多 Agent 编码任务——全部在终端中完成。

本文就带你从零开始安装到精通 OpenCode 的各种功能，一次性搞定所有问题。

需要什么才能开始

说一个你可能不想听的实话：你大概率已经满足了。Linux/Mac 用户开箱即用，Windows 用户开个 WSL2 就行。

操作系统：Linux（推荐 Ubuntu/WSL2）、macOS 或 Windows（PowerShell / WSL2）
终端：Bash、Zsh 或 Fish
架构：x86_64 或 ARM64
网络：能访问 GitHub 和 opencode.ai
硬盘空间：至少 500 MB（opencode 二进制约 150 MB）
Node.js（可选）：仅 npm 安装方式需要

安装方法

安装 OpenCode 最痛苦的不是装不上，而是装好了发现版本不对。来，直接抄答案：

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

这条命令搞定所有平台（Linux/Mac/WSL2），脚本自动检测架构、下载、安装、配 PATH。装完跑 opencode --version 确认就行。

另外三种方式看你情况选（不用逐条试）：

方式	适合谁	一句话
npm `npm install -g @opencode/cli`	已有 Node.js 18+ 的开发者	方便更新，但可能不是最新版
Homebrew `brew install opencode`	macOS 用户	跟你的 brew 生态一致
手动 GitHub Releases	离线安装 / 特定版本	下载 → 解压 → `mv` 到 PATH
Windows `iwr ... install.ps1 \| iex`	PowerShell 用户	或通过 Scoop

要我推荐？无脑用第一条 curl 脚本，30 秒搞定。

如果安装后 opencode 提示 command not found，加 PATH：

export PATH="$HOME/.local/bin:$PATH"

然后 source ~/.bashrc 或开新终端。

首次配置

1. 配置 AI 提供商

OpenCode 自带免费模型能用，但说实话，免费的东西你懂的——慢、有限制、关键时刻掉链子。想体验真正的速度，绑你自己的 API Key：

opencode providers

这会打开交互式界面，你可以添加以下提供商的凭据：

OpenAI — GPT-4、GPT-4o、o1、o3
Anthropic — Claude Sonnet 4、Claude Opus（我的首选，写代码真快）
Google — Gemini 2.0 Pro、Gemini 2.0 Flash
OpenRouter — 统一访问 200+ 模型
本地模型 — Ollama、vLLM、LM Studio
70+ 其他提供商

你也可以通过环境变量设置提供商凭据：

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-..."

2. 启动 OpenCode

进入项目目录并启动会话：

cd your-project
opencode

这会启动 TUI（终端用户界面），你可以在其中与 AI 对话、读写文件和执行命令。

小贴士：如果在启动后发现窗口太小，可以调整终端大小，或者使用 opencode web 启动网页界面，更方便操作。

核心命令参考

下面这张表你最好收藏一下。我当初就是没记住 opencode pr 这命令，白白手动 clone 了好几次 PR 来 review。

命令	说明
`opencode`	启动 TUI 交互界面（默认）
`opencode run "提示词"`	从命令行单次执行任务
`opencode serve`	启动无头服务器模式
`opencode web`	启动网页界面
`opencode pr <编号>`	抓取并检出 GitHub PR 分支
`opencode session`	管理对话会话
`opencode models [提供商]`	列出可用模型
`opencode providers`	管理 AI 提供商配置
`opencode stats`	查看 Token 使用统计
`opencode mcp`	管理 MCP（模型上下文协议）服务器
`opencode agent`	管理自定义 Agent
`opencode upgrade`	升级到最新版本
`opencode uninstall`	从系统中移除 OpenCode

TUI 模式详解

TUI 才是 OpenCode 的正确打开方式。别去 IDE 插件那折腾了，终端里一把梭，什么都有了。纯键盘操作，写代码的时候手不用离开终端。

启动 TUI

# 在当前目录启动
cd /path/to/project
opencode

# 指定项目路径
opencode /path/to/project

# 继续上次会话
opencode --continue
# 或
opencode -c

# 继续指定会话
opencode --session ses_abc123
# 或
opencode -s ses_abc123

# 启动 TUI 并立即发送提示
opencode -p "分析这个项目的架构并给出改进建议"

常用快捷键

快捷键	功能
`Enter`	提交消息（偶尔需按两次）
`Tab`	在 Agent 之间切换（build / plan 等）
`Ctrl+P`	打开命令面板
`Ctrl+X L`	切换当前会话
`Ctrl+X M`	切换模型
`Ctrl+X N`	新建会话
`Ctrl+X E`	打开编辑器
`Ctrl+C`	退出 OpenCode

TUI 使用技巧

使用 Tab 在不同 Agent 间快速切换，应对不同类型的任务
命令面板（Ctrl+P）提供所有操作的快速入口，无需记忆快捷键
可在后台运行 TUI 以执行长时间任务：opencode --demo "介绍一下你自己，然后等待指令" &

CLI 模式详解

CLI 模式是给那些懒得开 TUI 或者想写脚本自动化的硬核玩家准备的。实际用下来你会发现 opencode run 比开 TUI 快得多——尤其是跑一些固定任务的时候。TUI 能做的，CLI 只会做得更快。

基本用法

# 简单任务
opencode run "为 API 客户端添加重试逻辑"

# 附加文件提供上下文
opencode run "审查这个配置文件的安全问题" -f config.yaml -f .env.example

# 显示模型思考过程
opencode run "调试 CI 测试失败的原因" --thinking

# 指定模型
opencode run "重构 auth 模块" --model openrouter/anthropic/claude-sonnet-4

完整选项

opencode run [message..]

选项:
  --command                   要执行的命令（默认使用提示词）
  --continue, -c             继续上次会话
  --session                  按 ID 恢复指定会话
  --share                    分享会话
  --model, -m                指定模型（provider/model 格式）
  --agent                    指定使用的 Agent
  --format                   输出格式：default 或 json
  --file, -f                 附加文件（可重复使用）
  --title                    会话标题
  --attach                   连接到运行中的 opencode 服务器
  --port                     本地服务器端口
  --variant                  模型变体：high / max / minimal
  --thinking                 显示模型的思考过程
  --replay                   恢复交互历史（默认：true）
  --dangerously-skip-permissions   自动批准未明确拒绝的权限（危险！）

AI 提供商配置

75+ 个模型提供商，听起来很唬人对吧？但你真正用得上的其实就那几个。我的真实用法：日常 Claude Sonnet 写代码，GPT-4 做 brainstorm，Gemini 偶尔换换口味。别在选模型上纠结太久。

列出可用提供商

opencode providers list
opencode auth list

登录提供商

# 交互式登录
opencode providers login

# 或通过环境变量设置（优先级更高）
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-..."

提供商配置示例

添加到 ~/.config/opencode/opencode.json：

{
  "provider": {
    "anthropic": {
      "api": "https://api.anthropic.com",
      "env": ["ANTHROPIC_API_KEY"]
    },
    "openrouter": {
      "npm": "@opencode/plugin-openrouter",
      "env": ["OPENROUTER_API_KEY"]
    }
  },
  "enabled_providers": ["anthropic", "openrouter"],
  "disabled_providers": ["openai"]
}

查看可用模型

# 列出所有模型
opencode models

# 列出特定提供商的模型
opencode models openrouter

MCP 集成

MCP 是 OpenCode 的外挂系统。你写代码需要访问数据库？查文件系统？调 API？接个 MCP 服务器就行。听起来抽象？说个真实场景：你让 OpenCode “帮我把数据库里最近三个月的订单导成 CSV”，它自己连数据库、写 SQL、导文件——因为你给它接了个数据库 MCP 服务器。

列出 MCP 服务器

opencode mcp list
opencode mcp ls

添加 MCP 服务器

# 添加 stdio 服务器
opencode mcp add filesystem -- "npx -y @modelcontextprotocol/server-filesystem /path/to/data"

# 在自定义端口添加 SSE 服务器
opencode mcp add --port 3001 -- "node my-mcp-server.js"

认证 MCP 服务器

opencode mcp auth myserver
opencode mcp logout myserver
opencode mcp debug myserver

Agent 系统

Agent 就是你的专属 AI 分身。一个 Agent 相当于一个”角色设定”——它有自己的模型偏好、权限范围、行为模式。你想要一个只审代码安全的审查员？给它配 read + edit 权限，禁用 bash。想要一个专门修 bug 的猎人？给它最高权限和 high 模型变体。

列出 Agent

opencode agent list

创建 Agent

opencode agent create my-agent \
  --description "专门处理 React 组件开发" \
  --mode subagent \
  --model openrouter/anthropic/claude-sonnet-4

Agent 配置示例

在 ~/.config/opencode/opencode.json 中：

{
  "agent": {
    "code-reviewer": {
      "name": "Code Reviewer",
      "description": "安全性和正确性审查专家",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4",
      "color": "#E74C3C",
      "permissions": ["read", "edit"]
    },
    "bug-hunter": {
      "name": "Bug Hunter",
      "description": "调试和修复专家",
      "mode": "subagent",
      "model": "openai/gpt-4",
      "variant": "high",
      "permissions": ["bash", "read", "edit"]
    }
  }
}

使用 Agent

opencode run "审查这段代码的安全性" --agent code-reviewer

在 TUI 模式下，使用 Tab 键在不同 Agent 之间切换。

会话管理

会话管理就是你的对话存档系统。写了一半的代码、讨论了一小时的架构方案、跟 AI 吵了半天才 debug 出来的问题——全都能存下来下次接着聊。我最常用的是导出功能，把复杂对话存成文件发给同事，省得重新说一遍。

列出会话

opencode session list

删除会话

opencode session delete ses_abc123

导出会话

# 导出当前会话
opencode export

# 导出特定会话
opencode export ses_abc123

# 导出并脱敏敏感信息
opencode export ses_abc123 --sanitize

导入会话

# 从本地文件导入
opencode import session.json

# 从分享链接导入
opencode import https://opencode.ai/share/xxx

GitHub 集成

Code Review 是开发里最烦的事之一，对吧？OpenCode 直接给你安排一个 AI Review 小弟。你只管写代码，review 交给它。

安装 GitHub Agent

opencode github install

运行 GitHub Agent

opencode github run

审查 Pull Request

# 抓取 PR #42 并用 opencode 审查
opencode pr 42

# 克隆到临时目录审查 PR
REVIEW=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW
cd $REVIEW
opencode run "审查此 PR 与 main 分支的差异。报告 bug、安全风险、测试缺口和样式问题。"

服务器模式

把 OpenCode 跑成服务器，你的整个团队就都能用了。或者你出差的时候从笔记本连回台式机，想在哪儿写代码都行。我在 NAS 上挂了一个，写代码时直接 opencode attach 连过去，跟本地体验一样。

启动无头服务器

# 基本启动
opencode serve

# 指定端口
opencode serve --port 4096

# 启用 mDNS 发现
opencode serve --mdns
# 可通过 http://opencode.local:4096 访问

启动 Web 界面

opencode web
# 或指定端口
opencode web --port 3096

连接到远程服务器

opencode attach http://hostname:4096

配置详解

配置是 OpenCode 的心脏。改好了，它就是你的专属编码搭档；不改，它也能用，但你将错过 80% 的进阶功能。配置文件在 ~/.config/opencode/opencode.json，支持 JSON Schema 验证，IDE 里写的时候有自动补全。

完整配置示例

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

  "shell": "/bin/bash",

  "logLevel": "INFO",

  "server": {
    "port": 0,
    "hostname": "127.0.0.1",
    "mdns": false,
    "mdnsDomain": "opencode.local",
    "cors": []
  },

  "skills": {
    "paths": ["~/.config/opencode/skills"]
  },

  "model": "anthropic/claude-sonnet-4",
  "small_model": "openai/gpt-3.5-turbo",
  "default_agent": "build",
  "username": "developer",

  "share": "manual",

  "agent": {
    "build": {
      "name": "Build Agent",
      "description": "默认的编码助手 Agent",
      "model": "anthropic/claude-sonnet-4",
      "mode": "primary"
    }
  },

  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    }
  },

  "formatter": true,

  "lsp": true,

  "instructions": [
    "~/.config/opencode/instructions.md"
  ],

  "permission": {
    "read": {
      "~/**": "allow",
      "/etc/**": "deny"
    },
    "edit": {
      "**/*.go": "allow",
      "**/*": "ask"
    },
    "bash": "ask"
  }
}

权限配置说明

权限类型	说明	可选值
`read`	文件读取权限	`ask`（询问）、`allow`（允许）、`deny`（拒绝）
`edit`	文件编辑权限	`ask`、`allow`、`deny`
`bash`	终端命令执行权限	`ask`、`allow`、`deny`

权限条目支持 Glob 模式匹配。例如：

"~/projects/**": "allow" — 允许读取 ~/projects 下的所有文件
"/etc/**": "deny" — 拒绝访问系统配置文件
"**/*": "ask" — 其他文件每次询问

bash 权限尤其敏感——只有在你完全信任模型和环境时才设为 "allow"。

进阶技巧

以下这些技巧是我自己用了半年才摸出来的。早点看到能省你不少时间。第 5 条和第 6 条我几乎每天用。

1. 调试工具

# 查看当前配置
opencode debug config

# 查看系统调试信息
opencode debug info

# 检查 LSP 调试信息
opencode debug lsp

# 查看启动时间
opencode debug startup

# 查看 Agent 配置
opencode debug agent build

2. 使用统计与成本管理

# 查看所有统计
opencode stats

# 查看最近 7 天
opencode stats --days 7

# 显示使用最多的 5 个模型
opencode stats --models 5

# 按项目筛选
opencode stats --project myproject

3. 插件管理

OpenCode 支持通过插件扩展功能：

# 安装插件
opencode plugin opencode-plugin-github

# 全局安装
opencode plugin --global opencode-plugin-docs

# 强制重新安装
opencode plugin opencode-plugin-github --force

4. 升级与卸载

# 升级到最新版本
opencode upgrade

# 升级到指定版本
opencode upgrade 1.15.0

# 卸载 OpenCode
opencode uninstall

5. 一些实用小命令

# Shell 补全（bash/zsh）
opencode completion >> ~/.zsh/completion/_opencode

# Agent 间通信协议
opencode acp

# 快速验证 OpenCode 是否正常
opencode run '请只回复: OPENCODE_SMOKE_OK'

6. 并行任务执行

同时运行多个任务：

# 两个任务并行
opencode run "修复 issue #101" -m &
opencode run "添加解析器回归测试" -m
wait

-m 标志启用最小模式（无 TUI），& 将进程推入后台。

常见问题与踩坑记录

这些坑我全踩过。你看完至少能少走三天弯路。

坑 1：TUI 需要 PTY 模式

现象：TUI 卡住或无法接收输入。

原因：交互模式需要伪终端（PTY）。在后台运行或通过某些包装脚本启动时，PTY 分配可能丢失。

解决：使用 --continue 配合 -p 参数在后台运行：

# 正确——可在后台工作
opencode --continue -p "请等待下一指令"

# 错误——前台模式会卡住
opencode --continue

坑 2：不要用 `/exit` 退出

现象：输入 /exit 会打开 Agent 选择器而不是退出。

原因：/exit 不是 OpenCode 的有效命令。

解决：使用 Ctrl+C 或发送 kill 信号：

Ctrl+C

# 或从另一个终端
pkill -f opencode

坑 3：PATH 二进制冲突

现象：运行 opencode 时使用了错误的版本。

解决：检查是否安装了多个版本：

which -a opencode
opencode --version

如果看到多个路径，移除多余的版本或调整 PATH 顺序。

坑 4：安装后 PATH 未生效

现象：安装成功后运行 opencode 提示 command not found。

解决：重新加载 shell 配置或打开新终端：

source ~/.bashrc   # 或 ~/.zshrc

如果安装脚本没有自动添加，手动添加：

export PATH="$HOME/.local/bin:$PATH"

坑 5：npm 全局安装权限错误

现象：npm install -g @opencode/cli 报 EACCES 错误。

解决：配置 npm 使用个人前缀目录：

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @opencode/cli

坑 6：升级时二进制冲突

现象：升级失败，提示文件被占用。

解决：先关闭所有 OpenCode 进程再升级：

pkill opencode
opencode upgrade

坑 7：文件权限错误

现象：OpenCode 无法读写需要的文件。

解决：在 ~/.config/opencode/opencode.json 中配置 permission 字段：

{
  "permission": {
    "read": {"~/projects/**": "allow"},
    "bash": "ask"
  }
}

尽量使用精确的文件模式以保持安全性。

坑 8：curl 安装报 404

现象：curl 安装脚本返回 404 错误。

解决：安装脚本可能暂时不可用。尝试手动安装（方式四）或稍后重试。

该你动手了

好了，该说的都说了。你现在知道的已经比 90% 的人多了。

不收藏了，现在就装：

curl -fsSL https://opencode.ai/install | bash
opencode providers login
cd your-project && opencode

下篇我会讲怎么用 OpenCode 的 Agent + MCP 搭一个自动代码审查流水线。关注别走丢。

参考资料

官方网站：https://opencode.ai
GitHub：https://github.com/sst/opencode
配置 Schema：https://opencode.ai/config.json
npm 包：@opencode/cli