OpenCode 终端编程助手从入门到上手

2026-10-07 重写：原文有不少命令、配置项和下载地址在 OpenCode 官方文档里并不存在（例如 .deb / .rpm 安装包地址、opencode init、.opencodeignore），这次按官方中文文档（opencode.ai/docs/zh-cn）整篇重写，只保留文档里有的内容。OpenCode 更新很快，使用时以官方文档为准。

一、OpenCode 是什么

OpenCode 是一个开源的 AI 编程代理，可以在终端界面（TUI）、桌面应用或 IDE 扩展里使用。它读你的项目、回答关于代码的问题、规划改动并直接修改文件和执行命令。

几个基本特点：

• 模型随你选：基于 AI SDK 和 Models.dev，支持 75+ 家模型提供商，也能接本地模型；DeepSeek、Moonshot（Kimi）、Z.AI（GLM）等国内服务也在内置列表里。
• 开源：源码在 GitHub 的 anomalyco/opencode。
• 两种工作方式：Build 代理直接动手改代码，Plan 代理先分析、给方案，改文件和执行命令前都要你点头。

二、安装

终端里使用需要一个现代终端（官方列举了 WezTerm、Alacritty、Ghostty、Kitty），以及你要用的模型提供商的 API 密钥。

1. 一键脚本（macOS / Linux，推荐）

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

2. 包管理器

# Node.js 生态（任选其一）
npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai
yarn global add opencode-ai

# Homebrew（macOS / Linux）：官方 tap 更新最快
brew install anomalyco/tap/opencode

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

Homebrew 官方仓库里的 brew install opencode 由 Homebrew 团队维护，更新会慢一些。

3. Windows

官方推荐在 WSL（Windows Subsystem for Linux）里使用，性能和功能兼容性最好。也可以直接安装：

choco install opencode               # Chocolatey
scoop install opencode               # Scoop
npm install -g opencode-ai           # npm
mise use -g github:anomalyco/opencode

或者用 Docker：docker run -it --rm ghcr.io/anomalyco/opencode。

4. 手动下载

到 GitHub Releases 下载对应平台的版本。桌面应用在 opencode.ai/download。

三、连接模型

1. 添加提供商

启动 OpenCode 后，在输入框里执行：

/connect

从列表里选提供商，粘贴 API 密钥即可。密钥保存在 ~/.local/share/opencode/auth.json。然后用 /models 选择要用的模型。

官方推荐新手先试 OpenCode Zen：这是官方挑选、测试过的一组模型，/connect 里选 opencode，到 opencode.ai/auth 登录拿密钥。

2. 国内模型

DeepSeek、Moonshot AI、Z.AI 都在 /connect 的列表里，流程一样：

1. 到对应控制台创建 API 密钥；
2. /connect 搜索 DeepSeek / Moonshot AI / Z.AI，输入密钥（订阅了 GLM Coding Plan 的选 Z.AI Coding Plan）；
3. /models 选择模型。

3. 其他 OpenAI 兼容的服务

不在列表里的服务（比如各种中转站），只要提供 OpenAI 兼容接口就能用：

1. /connect 滚到最下面选 Other，输入一个自己起的提供商 ID（如 myprovider），再输入 API 密钥；
2. 在项目目录创建或修改 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "我的模型服务",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model-name": {
          "name": "My Model"
        }
      }
    }
  }
}

1. /models 里就能看到这个提供商和模型。

npm 填 @ai-sdk/openai-compatible 对应 /v1/chat/completions 接口；如果服务走 /v1/responses，改用 @ai-sdk/openai。不想走 /connect 存密钥的话，也可以在 options.apiKey 里写，例如 "{env:MY_API_KEY}" 从环境变量读。

4. 默认模型

在配置里写 model，格式是 provider_id/model_id：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "myprovider/my-model-name"
}

官方提醒：模型很多，但真正擅长写代码和调用工具的只有少数几个，工具调用不稳定时先换个模型试试。

四、上手：一个完整的工作流

1. 启动并初始化项目

cd /path/to/project
opencode

也可以直接 opencode /path/to/project。第一次在项目里用，先执行：

/init

OpenCode 会分析项目，在根目录生成 AGENTS.md，记下项目结构和代码约定。这个文件建议提交到 Git。

2. 提问：用 @ 引用文件

How is authentication handled in @packages/functions/src/api/index.ts

输入 @ 会在项目里模糊搜索文件，选中的文件内容会自动加进对话。图片可以直接拖进终端，作为参考一起发过去。

3. 复杂功能：先 Plan，再 Build

按 Tab 在 Build 和 Plan 之间切换，右下角有当前代理的标识。

• Plan：用来分析和出方案。默认情况下，改文件和执行 bash 命令都要先问你（ask）。
• Build：默认代理，所有工具都能用，直接改代码、跑命令。

比较大的改动，建议先切到 Plan 描述需求——像给团队新人布置任务那样，把背景和细节讲清楚；拿到方案后继续补充、修改；觉得可以了再按 Tab 切回 Build，让它开始改。

简单的改动可以直接在 Build 下说明要改什么、参照哪个文件。

4. 撤销与重做

/undo
/redo

/undo 撤销最近一条消息和它带来的所有文件改动，可以连续执行多次；/redo 恢复。这两个命令内部用 Git 管理文件变化，所以项目要是一个 Git 仓库。

5. 执行 shell 命令

以 ! 开头的消息会直接作为 shell 命令执行，输出会加进对话：

!ls -la

五、常用斜杠命令

输入 / 加命令名执行：

大多数命令有快捷键，前导键默认是 ctrl+x，例如 /models 是 ctrl+x m、/undo 是 ctrl+x u、/compact 是 ctrl+x c。不少命令还有别名：/new 也可以写 /clear，/sessions 也可以写 /resume，/exit 也可以写 /quit。

/editor 和 /export 用的是 EDITOR 环境变量里的编辑器，VS Code 这类图形编辑器要带 --wait，例如 export EDITOR="code --wait"。

六、代理

OpenCode 有两类代理：

• 主代理：直接和你对话，用 Tab 切换。内置 Build 和 Plan。
• 子代理：主代理会根据描述自动调用，也可以在消息里 @ 手动调用。内置三个：
  • General：通用研究、多步骤任务，可以改文件；
  • Explore：只读，快速找文件、搜代码、回答关于代码库的问题；
  • Scout：只读，查外部文档和依赖源码。

@general help me search for this function

也可以自己定义代理。用 Markdown 定义时，放在 ~/.config/opencode/agents/（全局）或 .opencode/agents/（项目），文件名就是代理名：

---
description: Reviews code for quality and best practices
mode: subagent
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on code quality, potential bugs,
performance and security. Provide feedback without making direct changes.

保存为 review.md，就多了一个叫 review 的只读子代理。也可以在 opencode.json 的 agent 字段里用 JSON 定义。

七、规则、配置与权限

1. AGENTS.md

AGENTS.md 里的内容会放进模型的上下文，用来交代项目约定：

• 项目级：项目根目录的 AGENTS.md，在该目录及子目录里生效；
• 全局：~/.config/opencode/AGENTS.md，适合放个人习惯，不进 Git。

从 Claude Code 迁移过来的话，没有 AGENTS.md 时会退而读取 CLAUDE.md。已有的规范文档不想复制，可以在配置里引用：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

2. 配置文件

配置支持 JSON 和 JSONC，主要有两处：

• 全局：~/.config/opencode/opencode.json，放主题、提供商、快捷键等个人偏好；
• 项目：项目根目录的 opencode.json，优先级更高，可以提交到 Git 和团队共享。

多份配置是合并而不是替换：后加载的只在同名键上覆盖前面的。还可以用 OPENCODE_CONFIG 环境变量指定一份自定义配置。

3. 权限

permission 决定每类操作是直接执行（allow）、先问你（ask）还是禁止（deny），可以按命令细分，后面的规则优先：

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

不配置时默认比较宽松：大多数操作直接执行（allow），访问工作目录之外的路径会先问你（ask），.env 文件默认不能读。常用的外部目录可以用 external_directory 规则放行。

八、自定义命令

重复的提示词可以做成命令。在 .opencode/commands/（项目）或 ~/.config/opencode/commands/（全局）放一个 Markdown 文件，文件名就是命令名：

---
description: Run tests with coverage
agent: build
---
Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

保存为 test.md，输入 /test 就会发出这段提示词。命令里可以用 $ARGUMENTS 接收整串参数，用 $1、$2 接收第几个参数；写 !`git log --oneline -10` 会把命令输出嵌进提示词。

九、MCP 服务器

通过 MCP（Model Context Protocol）可以给 OpenCode 接外部工具，本地和远程服务器都支持，在配置的 mcp 字段里定义：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true
    }
  }
}

也可以用 opencode mcp add 按引导添加，opencode mcp list 查看连接状态。官方提醒：MCP 工具会占用上下文，有的服务器（如 GitHub MCP）很耗 Token，只开真正要用的。

十、在脚本里用：opencode run

不打开界面、直接传入提示词：

opencode run "Explain the use of context in Go"

常用参数：-m provider/model 指定模型，-c 继续上一个会话，--agent 指定代理，-f 附加文件，--format json 输出原始 JSON 事件，方便脚本处理。

频繁调用时，可以先在一个终端里 opencode serve 起一个常驻服务，再用 opencode run --attach http://localhost:4096 "..." 连上去，省掉每次启动 MCP 服务器的时间。

十一、分享与隐私

/share 会为当前会话生成公开链接（opncd.ai/s/<share-id>）并复制到剪贴板，拿到链接的人都能看到完整对话，在你 /unshare 之前一直有效。分享模式在配置的 share 里设：manual（默认，手动分享）、auto（新会话自动分享）、disabled（完全禁用）。涉及公司代码或敏感信息的项目，建议在项目的 opencode.json 里设成 disabled 并提交到 Git。

十二、排查问题

• 日志：macOS / Linux 在 ~/.local/share/opencode/log/，保留最近 10 个；用 opencode --log-level DEBUG 获取更详细的日志。
• 本地数据：~/.local/share/opencode/ 下有 auth.json（密钥）、log/ 和各项目的会话数据。
• 桌面应用异常：先完全退出重开；启动就崩或卡住时，把全局配置里的 plugin 临时设成空数组，排除插件问题。
• 工具调用不稳定：换一个工具调用能力更好的模型。

参考资料

• 官方文档（中文）：https://opencode.ai/docs/zh-cn/
• 源码与发布：https://github.com/anomalyco/opencode
• 社区（Discord）：https://opencode.ai/discord