OpenCode 终端 AI 编程工具使用指南

OpenCode 终端 AI 编程工具使用指南

OpenCode 是一款 MIT 协议、模型无关（BYO Model）的开源终端 AI 编程 Agent，形态上对标 Anthropic 的 Claude Code，但可接入 75+ LLM 供应商（Claude、GPT、Gemini、xAI、DeepSeek、Qwen、Ollama 等）。它提供终端 TUI、桌面应用、IDE 扩展多种使用形态，并通过 MCP 协议扩展工具能力。

OpenCode 本身就是「终端工具」，用 opencode 命令启动；本教程聚焦于如何安装它，并接入合适的 AI 模型供应商（默认推荐 OpenCode Zen，也支持 GitHub Copilot 订阅、Anthropic、OpenAI 等任意供应商）。

前置准备

1. 获取 LLM 凭据

OpenCode 支持多种认证方式，任选一种：

2. 系统要求

支持的系统： macOS、Linux、Windows（推荐 WSL2 获得最佳终端体验）。

分步安装指南

方式一：官方安装脚本（推荐，macOS / Linux / WSL）

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

脚本自动下载最新版并把 opencode 加入 PATH。

方式二：npm 安装（已有 Node 环境）

1# 注意：npm 包名是 opencode-ai，不是 opencode
2npm install -g opencode-ai
3
4# 升级到最新版
5npm install -g opencode-ai@latest
6
7# 验证安装
8opencode --version

中国大陆用户（使用 npm 镜像加速）：

1npm config set registry https://registry.npmmirror.com
2npm install -g opencode-ai

方式三：Homebrew（macOS / Linux）

1# 推荐：OpenCode tap，更新最快
2brew install anomalyco/tap/opencode
3
4# 或用官方 formula（由 Homebrew 团队维护，更新较慢）
5brew install opencode

方式四：Arch Linux

1# 官方仓库稳定版
2sudo pacman -S opencode
3
4# AUR 最新版
5paru -S opencode-bin

方式五：Windows 包管理器

1# Chocolatey
2choco install opencode
3
4# Scoop
5scoop install opencode
6
7# Mise
8mise use -g github:anomalyco/opencode

方式六：Docker 运行

1docker run -it --rm ghcr.io/anomalyco/opencode

方式七：二进制直接下载

从 GitHub Releases 下载对应平台的二进制文件，重命名为 opencode 并放入 PATH 即可。

配置认证与 API Key

方法一：TUI 内 /connect 命令（推荐）

最简单的方式：进入 TUI 后用 /connect 命令交互式添加任意供应商凭据。

1# 启动 TUI
2opencode
3
4# 在 TUI 内执行：
5/connect

接入 OpenCode Zen（新手首选）：

1. 执行 /connect，选择 opencode
2. 浏览器自动打开 opencode.ai/auth，登录并添加账单信息
3. 复制 API Key，粘回到 TUI
4. 执行 /models 浏览官方精选模型列表

接入其他供应商（如 302.AI、Anthropic、OpenAI）：

1. 执行 /connect，搜索供应商名称
2. 输入对应 API Key
3. 执行 /models 选择模型

凭据保存在 ~/.local/share/opencode/auth.json。

方法二：CLI 登录

1# 交互式登录
2opencode auth login
3
4# 查看已配置的凭证
5opencode auth ls

也可在 VS Code 命令面板执行 OpenCode: Auth Login。

方法三：环境变量（适合自动化 / 云厂商）

针对特定供应商可用环境变量。例如接入 Amazon Bedrock：

1# 方式 1：AWS 访问密钥
2AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode
3
4# 方式 2：命名 profile
5AWS_PROFILE=my-profile opencode
6
7# 方式 3：Bedrock bearer token
8AWS_BEARER_TOKEN_BEDROCK=XXX opencode

配置文件：opencode.json

OpenCode 支持 JSON 与 JSONC（带注释）格式，配置文件分层加载、合并而非覆盖：

opencode.json 示例：

1{
2  "$schema": "https://opencode.ai/config.json",
3  // 主题
4  "theme": "opencode",
5  // 默认模型
6  "model": "anthropic/claude-sonnet-4-5",
7  // 自动更新
8  "autoupdate": true
9}

自定义供应商 Base URL

通过 provider.<name>.options.baseURL 接入任意 OpenAI 兼容端点（代理、私有镜像、自建网关）：

1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {
4    "anthropic": {
5      "options": {
6        "baseURL": "https://api.anthropic.com/v1"
7      }
8    },
9    "amazon-bedrock": {
10      "options": {
11        "region": "us-east-1",
12        "profile": "my-aws-profile"
13      }
14    }
15  }
16}

快速开始

1. 进入项目目录

1cd /path/to/your/project

2. 启动 TUI

1opencode

3. 初始化项目上下文

OpenCode 会分析项目结构并在项目根目录生成 AGENTS.md，把项目规范、技术栈、关键文件说明写入其中。建议提交到 Git，让团队成员共享。

4. 切换 Plan / Build 模式

按 Tab 键在右下角模式指示器处切换：

• Plan 模式：只读分析，给出实施计划，不动任何文件
• Build 模式：开放全部工具，可读写文件、执行命令

5. 模糊搜索文件

用 @ 键触发文件模糊搜索，把文件加入对话上下文：

6. 撤销与重做

1/undo    # 撤销上一次改动（可多次）
2/redo    # 重做
3/share   # 生成对话分享链接并复制到剪贴板

核心功能与使用模式

Plan / Build 双模式

内置工具

多供应商与多模型

• 基于 models.dev 注册表，支持 75+ 供应商
• 可在会话中用 /models 切换模型
• 不同任务用不同模型，按需优化成本

自定义子代理（Subagents）

可在 ~/.config/opencode/agents/ 下定义自定义子代理，组合 MCP 工具完成专项任务（如代码审查、文档生成、前端实现等）。

配置文件与项目上下文

AGENTS.md（项目级规则）

在项目根目录放置 AGENTS.md，OpenCode 会读取作为每次对话的上下文，写入技术栈、编码规范、关键路径说明等。若从 Claude Code 迁移，OpenCode 会回退读取 CLAUDE.md。

.opencode 目录

项目根或 ~/.config/opencode/ 下可放置子目录：

• agents/：自定义子代理
• commands/：自定义斜杠命令
• modes/：自定义模式
• plugins/：插件
• skills/：技能
• themes/：主题

场景应用示例

场景一：代码库理解

1你：How is authentication handled in @packages/functions/src/api/index.ts
2
3OpenCode 会：
41. 用 @ 模糊搜索定位文件
52. 读取并分析认证逻辑
63. 解释关键函数与数据流

场景二：分步实现新功能

1你（Plan 模式）：When a user deletes a note, flag it as deleted in the database.
2                Then create a screen showing recently deleted notes.
3
4OpenCode 会：
51. Plan 模式下给出实施步骤，不动代码
62. 你迭代细节，可粘参考图：
7   [Image #1] Take a look at this image and use it as a reference.
83. 切 Build 模式：Sounds good! Go ahead and make the changes.
94. OpenCode 直接修改多个文件

场景三：直接修改 / 撤销回滚

1你：Can you refactor the function in @packages/functions/src/api/index.ts?
2
3# 不满意？直接撤销
4/undo
5
6# 调整 prompt 后重试

最佳实践

安全建议

1. Plan 模式优先评估：陌生代码库先用 Plan 模式了解结构
2. auth.json 加入 .gitignore：避免凭据泄露
3. CI/CD 用环境变量：通过 AWS_PROFILE 等环境变量注入最小权限
4. 提交 AGENTS.md 到 Git：让团队共享项目规则

性能优化

1. @ 精准引用文件：只加必要文件，减少 Token 消耗
2. 用 Plan 模式迭代方案：避免 Build 模式跑偏后浪费 Token
3. 多供应商分流：本地模型走 Ollama，复杂推理走 Claude
4. 用 OpenCode Zen 入门：官方精选模型开箱即用

故障排查

1# 检查已配置的凭证
2opencode auth ls
3
4# 查看当前生效的配置
5opencode debug config

扩展与进阶

官方资源

• 🌐 官网：opencode.ai
• 📖 官方文档：opencode.ai/docs
• 💻 GitHub 仓库：github.com/anomalyco/opencode（原 sst/opencode）
• 📦 npm 包：opencode-ai
• 🔐 认证入口：opencode.ai/auth
• 💬 Discord 社区：opencode.ai/discord

进阶玩法

• MCP 服务器：在 opencode.json 的 mcp 字段配置远程或本地 MCP 服务器
• 自定义子代理：在 ~/.config/opencode/agents/ 下定义专项 Agent
• 自定义命令：在 ~/.config/opencode/commands/ 下定义斜杠命令
• GitHub Copilot 集成：用现有 Copilot 订阅直接驱动终端 Agent
• LSP 与 ast-grep：开启语言服务器与结构化代码搜索，提升代码理解精度
• 主题与键位：在 tui.json 中自定义 TUI 外观与快捷键

总结

OpenCode 把 Claude Code 形态的终端 AI 编程 Agent 完全开源、模型无关化：一套工具壳，接入 75+ LLM 供应商，支持 Plan / Build 双模式，原生 MCP 扩展，并能用 GitHub Copilot 订阅直接认证。

无论是代码理解、分步实现新功能，还是直接修改与回滚，OpenCode 都能成为你终端里的得力开源 AI 编程 Agent。立即安装，把任意模型接入你的命令行工作流吧！