OpenCode 是一款开源免费的 AI 编程助手，由 Anomaly 团队开发。它能直接在你的终端、桌面端或 IDE 里工作，帮你读代码、改代码、跑命令、执行测试，直接用自然语言完成各种开发任务。目前支持多达 75+ 家 LLM 提供商（Claude、GPT、Gemini、本地 Ollama 等），不绑定任何一家大模型，你可以设置任何一家大模型提供商即可使用。

相比其它 AI CLI，我用下来最看重它两点：

  1. 默认不存储你的代码和上下文数据，只有你主动使用 /share 分享会话时，对话数据才会同步到官方服务器；
  2. 时不时提供免费模型，例如 mimo，minmax，kimi，能够满足我日常小需求迭代开发。

如何安装

官方脚本一键安装

最省事的方式是官方安装脚本：

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

通过包管理器安装

如果你本地有安装 nodejs 环境，也可以通过 npm 管理器进行安装，pnpm、bun、yarn 同理：

npm install -g opencode-ai

Mac 和 Linux 推荐 brew 进行安装，官方 tap 的更新更及时：

brew install anomalyco/tap/opencode

Arch Linux 用户可以用 pacman 或 AUR：

sudo pacman -S opencode   # 稳定版
paru -S opencode-bin      # AUR 最新版

如果不想装到本机，也可以直接用 Docker 镜像跑：

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

Windows 用户

官方推荐在 WSL 里运行，性能和兼容性都更好。如果要用原生 Windows，可以用 Chocolatey 或 Scoop：

choco install opencode
scoop install opencode

安装完成后只需切换到项目路径下，在终端运行 opencode 就可以启动 TUI 界面，也可以直接指定工作目录：

opencode
opencode /path/to/project

OpenCode TUI界面

模型配置

OpenCode 已内置 OpenAI、Anthropic、DeepSeek、OpenRouter、Moonshot AI、MiniMax、Groq、Ollama 等主流供应商。接入流程非常简单：

  1. 在 TUI 中执行 /connect，选择对应提供商，填入 API Key
  2. 执行 /models，从列表中选择模型
配置Deepseek
配置Deepseek

官方文档推荐在 OpenCode 上表现较好的模型包括：GPT 5.2、GPT 5.1 Codex、Claude Opus 4.5、Claude Sonnet 4.5、Gemini 3 Pro 等。

自定义模型

对于 OpenCode 未内置、但提供 OpenAI 兼容接口的服务（如公司内部网关、自建推理服务、聚合平台），需要手动配置 opencode.json。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "my-local-model": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "我的本地模型",
      "options": {
        "baseURL": "http://localhost:1234/v1",
        "apiKey": "your-api-key-if-any"
      },
      "models": {
        "model-id-on-server": {
          "name": "显示在列表中的名字"
        }
      }
    }
  },
  "model": "my-local-model/model-id-on-server"
}

关键字段含义：

字段 说明
my-local-model 自定义提供商 ID，必须唯一
npm OpenCode 调用该接口使用的 AI SDK 包
baseURL 模型服务的 API 地址，注意不要填网站首页
models 模型 ID 到配置的映射，键名必须是服务端认可的真实模型 ID

这里重点介绍下 npm 这个字段，npm 字段决定 OpenCode 用哪个 AI SDK 包与提供商通信，选错会导致接口 404 或工具调用失败。

协议类型 npm值 适用场景
OpenAI 兼容（Chat Completions） @ai-sdk/openai-compatible 兼容 /v1/chat/completions 的服务，最通用
OpenAI 官方完整 API @ai-sdk/openai 连接 OpenAI 官方，或使用仅支持 /v1/responses 的服务
Anthropic @ai-sdk/anthropic Claude 系列模型
Google @ai-sdk/google Gemini 系列模型

选择原则：优先匹配提供商的 API 协议，具体支持的协议可以查阅提供商接入文档或者咨询对应的提供商的客服。其中要注意一下 openai 协议的不同：

  • @ai-sdk/openai-compatible 是一个通用兼容层，始终针对 /v1/chat/completions，适合绝大多数第三方代理、本地模型服务（Ollama、vLLM、LM Studio）和网关（LiteLLM）。
  • @ai-sdk/openai 是 OpenAI 官方完整 Provider，同时支持 Chat Completions 和 Responses API，但默认倾向于 /v1/responses。只有当你需要连接 OpenAI 官方，或使用仅提供 /v1/responses 的服务时才选它。

两者不能随意互换，选错就会导致接口 404 或工具调用失败。

项目规则

如果你的项目根目录下已经有 AGENTS.md，启动时会自动读进上下文。以前用 Codex 维护过的话，直接接着用就行。

项目里还没有的话，在 TUI 里跑 /init 就能生成。它会扫一遍仓库里的关键文件，遇到代码搞不清楚的地方会问你几个问题，然后写出一份精简说明。重点写这些：

  • 从文件名看不出来的架构信息
  • 项目特有的约定和容易踩的坑

已经有 AGENTS.md 的话，/init 会直接改原文件，不会覆盖。建议的是把这个文件跟着项目一起发布到仓库里，可以在团队共享。

全局规则

全局规则默认放在 ~/.config/opencode/AGENTS.md，对所有会话都生效。它和项目级是叠加关系，项目级管当前目录和子目录的具体规矩，全局级管你的个人偏好（比如指定回复的语言）。

拆分规则文件

通常建议 AGENTS.md 不要写太多内容，控制在 250-300 行即可。

如果需要给项目补充更多的规则，可以在 opencode.json 里用 instructions 字段引用其他文件，配置支持 glob 和远程 URL 两种方式，引用的内容会和 AGENTS.md 进行合并。

monorepo 或者团队有共享规范的场景，可以用 glob 一把引入所有的 packages/*/AGENTS.md。

Agent

OpenCode 的能力边界由 Agent 和权限共同决定，内置 2 个主 Agent 和 3 个子 Agent。

主 Agent

OpenCode 内置的 Build 与 Plan 两个主 Agent，区别如下：

  • Build：默认 Agent，所有工具全部开放，适合真正动手写代码的场景。
  • Plan：偏分析和规划的模式，文件编辑和 bash 命令默认都是 ask，需要你确认才会执行，适合让模型先看代码、出方案而不直接动仓库。

在 TUI 里按 Tab 快捷键就能在两个模式之间切换，界面左下角会显示当前模式。我自己的习惯是先在 Plan 里把方案聊清楚，确认之后再按 Tab 切回 Build 让它动手。

Build
Build
Plan
Plan

子 Agent

除了主 Agent，OpenCode 还内置了三个子 Agent。主 Agent 会根据描述自动调用，你也可以用 @ 手动指定：

  • general：通用型，拥有完整的工具权限（todo 除外），适合复杂调研和多步任务，也能并行跑多个工作单元。
  • explore：只读，专注快速探索代码库，用来按模式找文件、搜索关键字、回答代码结构问题。
  • scout：只读，用来查外部文档和依赖资料，必要时会把依赖仓库克隆到 OpenCode 的托管缓存里，不会污染你的工作区。

另外还有几个隐藏的系统 Agent（compaction、title、summary），分别负责压缩上下文、生成会话标题和摘要，它们自动运行，不会出现在可选列表里。

自定义 Agent

通常内置的模型肯定不够用，这时候就需要定义个性化 agent。如果你想临时定义一个简单的 agent，最方便的方式就是直接写进 opencode.json，但是我不建议这样做。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": { "edit": "deny" }
    }
  }
}

我更推荐的是使用 markdown 文件来创建 agent，方便编辑和管理，直接在 markdown 内容加 frontmatter 定义，文件名就是 Agent 名，可以放在 ~/.config/opencode/agents/（全局）或 .opencode/agents/（项目级）目录，例如一个简单的 code review agent。

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
 
You are in code review mode. Focus on code quality, edge cases, performance and security.

其中 frontmatter 的配置项

  • description 是必填项
  • temperature 越低输出越稳定（0.0-0.2 适合代码分析和规划）
  • permission 用来限制这个 Agent 能用哪些工具。

权限控制

OpenCode 的每个工具都可以单独设置权限，取值有三种：

  • allow：直接执行，不询问
  • ask：每次都询问你
  • deny：直接拒绝

全局配置的写法如下，* 表示所有工具的兜底规则：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

bash、edit 这类工具还支持按参数做细粒度规则，通配符 * 匹配任意字符，最后一条匹配的规则生效，所以兜底规则要写在前面：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    }
  }
}

例如前面提到的 code review agent，我们设置了 edit 和 bash 都是 deny，防止 review 时修改，执行我们的代码。

想让 OpenCode 一路跑到底，可以加 --auto 自动批准所有询问类请求，但显式 deny 的规则依然会被拦住：

opencode --auto

扩展能力

MCP servers

MCP 是 AI 与外部系统交互的开放标准，OpenCode 通过 mcp-go 库实现 MCP 客户端功能，支持本地（Stdio） 和远程（SSE） 两种传输方式。

我们只需要在配置文件的 mcp 字段下添加 MCP server：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true
    },
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": { "Authorization": "Bearer MY_API_KEY" }
    }
  }
}

要注意 MCP 工具会占用上下文，像 GitHub MCP 这种工具数量多的 server 很容易把上下文吃满，建议按需开启。

Agent Skills

Skill 本质是一份包含特定指令的 SKILL.md 文件，遵循开放的 Agent Skills 规范，它不默认激活，Agent 只会加载技能的名称和描述，只有在任务匹配时才通过内置的 skill 工具按需加载完整内容，避免占用过多上下文。

Skill的加载顺序

OpenCode 会从这些位置查找并加载：

项目级别：

  • opencode/skills/<name>/SKILL.md
  • ~/.claude/skills/<name>/SKILL.md
  • ~/.agents/skills/<name>/SKILL.md

全局级

  • ~/.config/opencode/skills/<name>/SKILL.md
  • ~/.claude/skills/<name>/SKILL.md
  • ~/.agents/skills/<name>/SKILL.md

发现顺序为：全局外部技能 → 项目外部技能 → OpenCode 原生技能 → 额外配置路径 → 远程技能

SKILL.md 的结构

SKILL.md 必须以 frontmatter 开头，其中 name 和 description 是必填项。

name 要求 1-64 位小写字母数字加单个连字符，且必须和所在目录名一致。

一个简单的 SKILL.md 长这样：

---
name: hello-skill
description: 一个最简单的问候技能。当用户说“跟世界打个招呼”时使用。
---
 
# Hello Skill
 
当用户要求你“跟世界打个招呼”时，请执行以下操作：
 
1. 用中文输出一句问候语。
2. 在问候语后面加上一个笑脸表情 😊。

如何想了解如何编写 skill，可以查看这篇文章：Claude Skill 完全入门教程：从零开始打造你的第一个Skill

小结

整体体验下来，OpenCode 值得推荐的地方有三点：不绑定模型、终端体验打磨得比较完整、开源且数据默认不上传。如果你之前用的是 Claude Code 或 Codex，迁移成本很低，AGENTS.md 和 skills 目录基本可以直接复用。

如果你厌倦了 Claude，想尝试新的 AI CLI，OpenCode 也是一个不错的选择。

OpenCode