opencode 新手入门指南

Q: opencode 免费吗？要不要自己的 API Key

opencode 本体完全免费且开源（MIT 协议），下载与使用工具本身不收费。但它不自带模型，你需要连接一个模型 provider。如果用 Anthropic、OpenAI、OpenRouter 等付费 API，会按所选模型的用量计费，需要自备 API Key；如果用 OpenRouter 免费模型、本地 Ollama，或官方的 OpenCode Zen 免费额度，则可以零成本上手。换句话说，工具免费，成本只取决于你接的模型。

Q: opencode 和 Claude Code 有什么区别

两者都是终端里的 AI 编程智能体，最大区别是 opencode 不绑定单一厂商。Claude Code 默认走 Anthropic 的 Claude 模型，而 opencode 采用「自带 Key」模式，可在 Anthropic、OpenAI、Google、OpenRouter 以及本地 Ollama 等 75+ provider 之间自由切换，并支持免费模型。opencode 完全开源（MIT），项目上下文使用通用约定的 AGENTS.md。

约 2214 字大约 7 分钟...

opencode 是 Anomaly（原 SST 团队，2026 年更名）开源的终端 AI 编程智能体，采用 MIT 协议，本体完全免费。它最大的特点是不绑定任何模型厂商：通过「自带 API Key（bring-your-own-key）」的方式，你可以在 Anthropic、OpenAI、Google、OpenRouter 以及本地 Ollama 等 75+ 个 provider 之间自由切换，也能直接用免费模型上手。本指南将带你从安装、认证，到第一次会话、项目上下文与多模型切换，逐步掌握这款工具。

定位说明：opencode 提供终端 TUI 界面，也有桌面应用与 IDE 扩展。本文聚焦最常用的终端用法。

第一步：快速安装

opencode 提供一键安装脚本，会自动下载对应平台的二进制文件，也支持各大包管理器。

macOS / Linux

一键安装脚本：

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

或使用 Homebrew（官方推荐 tap，更新及时）：

brew install anomalyco/tap/opencode

Windows

使用 Scoop 或 Chocolatey：

scoop install opencode

choco install opencode

跨平台：npm

如果你已有 Node.js 环境，可以全局安装 npm 包（包名为 opencode-ai）：

npm install -g opencode-ai@latest

提示：旧版本（早于 0.1.x）请先卸载再安装，以免冲突。其他渠道如 Arch Linux（sudo pacman -S opencode）、mise、Nix 等也都支持（以官方为准）。

验证安装

安装完成后运行以下命令确认：

opencode --help

看到完整的帮助信息即说明安装成功。

第二步：配置模型与认证

opencode 本身不带模型，第一次使用需要连接一个 provider 并完成认证。

在终端运行：

opencode auth login

它会列出 75+ 个可选 provider（Anthropic、OpenAI、Google、OpenRouter 等），按提示选择后填入对应的 API Key，或对支持的 provider 走浏览器授权登录。凭据会保存在本地的 ~/.local/share/opencode/auth.json 中。

查看已认证的 provider：

opencode auth list

各家 provider 速览

Anthropic（Claude）：选择 Anthropic，可填入 API Key，或选择 Claude Pro/Max 走浏览器授权。
OpenAI：选择 OpenAI，填入 API Key，或用 ChatGPT Plus/Pro 浏览器登录。
OpenRouter：在 OpenRouter 控制台创建 API Key，登录时选 OpenRouter 并粘贴 Key，即可访问海量模型（含免费档）。

免费模型方案（零成本上手）

如果你暂时不想付费，有几种常见选择：

OpenCode Zen：官方推荐新手从这里开始。访问 opencode.ai/auth 创建 API Key，再在 opencode auth login 中选择 OpenCode Zen 即可。
OpenRouter 免费档：OpenRouter 上有一批标注 :free 的免费模型，连接 OpenRouter 后即可在 /models 里选用。

本地模型（Ollama）：在本机跑 Ollama，无需联网、无 token 费用。可在 opencode.json 里配置一个 OpenAI 兼容的 provider：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama3": { "name": "Llama 3" } }
    }
  }
}

具体字段以官方文档为准。

第三步：开始你的第一次会话

启动 TUI 交互模式

在项目目录下直接运行：

opencode

进入交互式界面后，就可以用自然语言对话了：

请解释这个项目的整体结构

帮我写一个 Go 函数，从 CSV 文件读取数据并去重

引用文件使用 @ 符号，输入 @ 后会弹出文件补全：

分析 @src/main.ts 的代码质量并指出潜在问题

一次性命令模式（opencode run）

只想执行单个任务、或在脚本 / CI 中调用时，用 opencode run，直接把提示词作为参数传入：

opencode run "为 src/utils.ts 编写单元测试"

配合 --model（短写 -m）可临时指定模型，格式为 provider/model：

opencode run --model anthropic/claude-sonnet-4-5 "重构这个函数使其更易读"

这种模式不启动完整 TUI，适合自动化和快速取答案。

第四步：配置项目上下文（AGENTS.md）

opencode 使用项目根目录下的 AGENTS.md 作为「项目记忆」，其中的内容会被加入每次对话的上下文，用来约束模型行为——作用类似 Cursor 的 rules，也与 Claude Code 的 CLAUDE.md 一致。AGENTS.md 正逐渐成为各家工具通用的约定。

你可以在 TUI 中运行 /init，让 opencode 扫描仓库并自动生成一份 AGENTS.md；也可以手动创建：

# MyWebApp 项目指南

## 技术栈

- 前端：React + TypeScript + Vite
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 编码规范

- 所有函数必须有 TypeScript 类型注解
- 组件名使用 PascalCase，文件名使用 kebab-case
- 每次改动后运行 `pnpm test` 确保测试通过

## 项目结构

- `/src/components/` - React 组件
- `/src/api/` - API 调用

opencode 读取规则的优先级大致为：从当前目录逐级向上查找的本地 AGENTS.md → 全局 ~/.config/opencode/AGENTS.md → ~/.claude/CLAUDE.md（作为 Claude Code 兼容回退）。把团队通用约定放在项目根目录，把个人偏好放进全局文件即可。

第五步：多模型切换与进阶

opencode 的核心优势就是不绑定单一模型。模型目录由 models.dev 维护，覆盖各家上千个模型。

查看与切换模型

命令行下查看可用模型：

opencode models

在 TUI 中用 /models 切换：

/models

它会列出已认证 provider 的全部模型（以 provider/model 格式展示），用方向键选择即可。建议简单任务用便宜 / 免费模型省成本，复杂重构或架构设计再切换到更强的推理模型。

全局配置与会话管理

全局配置目录：~/.config/opencode/，可放全局 opencode.json 和全局 AGENTS.md。
凭据文件：~/.local/share/opencode/auth.json。
会话（sessions）：opencode 会保存历史会话，可用 opencode --continue 继续上一次，或 opencode --session <id> 恢复指定会话。
自定义 agent：通过 --agent 指定不同的智能体配置，针对不同任务使用不同的模型与权限组合（以官方为准）。

了解使用成本

工具本体：opencode 采用 MIT 协议，完全免费、开源，下载与使用工具本身不花一分钱。
模型费用：成本只取决于你连接的 provider。
- 走 Anthropic / OpenAI / Google 等付费 API，按所选模型的 token 用量计费，需自备 API Key；
- 用 OpenRouter 上的 :free 免费模型、本地 Ollama，或官方 OpenCode Zen 免费额度，可零成本使用。
省钱建议：把日常小任务交给免费 / 廉价模型，只在关键场景切换到旗舰模型；本地敏感代码可优先考虑 Ollama，数据不出本机。

各家模型的免费额度与价格会随时调整，最终以对应 provider 的官方说明为准。

常见问题解答

Q: opencode 免费吗？要不要自己的 API Key？ A: 工具本体免费且开源（MIT）。它不自带模型，需要连接一个 provider：用付费 API 需自备 Key 并按用量计费；用 OpenRouter 免费模型、本地 Ollama 或 OpenCode Zen 免费额度则可零成本上手。

Q: 我的代码会被发送到云端吗？ A: 取决于你选的模型。连接云端 provider 时，相关代码会发送到对方 API 处理；如果用本地 Ollama 模型，则数据不出本机，更适合敏感代码。

Q: opencode 和 Claude Code 有什么区别？ A: 都是终端 AI 编程智能体。Claude Code 默认走 Anthropic 的 Claude，而 opencode 不绑定厂商，可在 75+ provider 间切换并支持免费模型，且完全开源。项目上下文用通用约定的 AGENTS.md。

Q: 怎样在多个模型之间切换？ A: 命令行用 opencode models 查看，TUI 里用 /models 切换；一次性命令可用 opencode run --model provider/model "..." 临时指定。建议按任务难度和成本灵活选择。