把 AI 程序员
装进你的终端

02 · Install

安装

一条脚本搞定 macOS / Linux。装完在终端敲 opencode 验证。

§各平台方式

§升级与卸载

opencode upgrade        # 升级到最新版
opencode uninstall      # 彻底卸载（保留配置加 -c -d）

03 · Configure

配置模型

两条路：用官方网关 Zen（最省事），或自带任何一家 API Key。

opencode auth login     # 交互式配置任意 provider 的 Key
opencode auth list      # 查看已登录的 provider
opencode models         # 列出所有可用模型（格式：provider/model）
opencode models --refresh  # 刷新模型缓存，看到最新上架

04 · Quickstart

快速上手：七步走完第一轮

1. 进入项目，启动 OpenCode

   它会读取当前目录作为工作区。

   cd /path/to/project
   opencode

2. 初始化项目记忆

   输入 /init，它会分析代码库并在根目录生成 AGENTS.md——以后每次会话都会带上这份「项目说明书」。记得提交到 Git。

3. @ 引用文件提问

   输入 @ 可模糊搜索文件，文件内容自动进入对话。

   这个项目的鉴权是怎么做的？重点看 @packages/functions/src/api/index.ts

4. Tab 切换 Plan / Build

   Plan 模式只分析不动手，让它先出方案；觉得靠谱再切回 Build 模式让它实施。右下角有当前模式指示。

5. 给足上下文

   描述要具体，像跟初级同事交代任务；设计稿、截图直接拖进终端即可作为参考图。消息以 ! 开头可以直接跑 shell 命令，输出会进入对话。

   用户删除笔记时要软删除标记，再做一个回收站页面，可恢复或彻底删除。
   参考这张设计稿。[拖入图片] 方案确认后就动手改。

6. 后悔药：/undo 与 /redo

   不满意就 /undo——撤回上一条消息、回复以及所有文件改动，改改说法重来。底层靠 Git 实现，所以项目必须是 Git 仓库。

7. 分享会话

   /share 生成链接并复制到剪贴板，发给同事复现问题。默认不公开，/unshare 可随时撤下。

05 · TUI

TUI 界面与命令

所有内置命令都是斜杠开头；多数还有快捷键，前导键是 Ctrl+X，命令面板是 Ctrl+P。

§让外部编辑器接管长文本

/editor 和 /export 使用 EDITOR 环境变量指定的编辑器。GUI 编辑器记得加 --wait：

export EDITOR="code --wait"   # VS Code / Cursor / Windsurf 同理
export EDITOR=nvim            # 或终端编辑器

§tui.json：界面微调

TUI 的个性化放在独立的 tui.json 里（与 opencode.json 分工不同）：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "diff_style": "auto",
  "cursor": { "style": "block", "blinking": true },
  "mouse": true,
  "attention": { "enabled": true, "sound": true, "volume": 0.4 }
}

06 · Agents

Agent 模式：主控与子代理

OpenCode 的 agent 分两类：Primary 是你直接对话的主控（Tab 循环切换），Subagent 是被主控派活或你 @mention 的专职助手。

§自定义 Agent：一个 Markdown 文件的事

放到 .opencode/agents/（项目级）或 ~/.config/opencode/agents/（全局），文件名即名字：

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
You are in code review mode. Focus on quality, bugs,
performance and security. Provide feedback without editing.

懒得手写？终端跑 opencode agent create，问答式帮你生成。

07 · Permissions

权限控制

每个动作三种结局：allow 自动放行 · ask 弹窗询问（once / always / reject）· deny 直接禁止。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",            // 默认都问
    "read": "allow",
    "grep": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",    // 通配符匹配命令前缀
      "rm *": "deny"
    }
  }
}

§可以管住哪些动作

read edit glob grep bash task（派子代理） skill lsp question webfetch websearch external_directory（越出项目目录时） doom_loop（同一调用重复 3 次时触发）

• 默认策略很宽松：大多数 allow；但 .env 文件默认禁止读取，防泄密
• doom_loop 和 external_directory 默认 ask，是两道保险丝
• 想全自动？启动加 --auto：opencode --auto——deny 规则依然生效
• 权限可以在单个 agent 上覆盖，比如给 review 代理全面禁写

08 · Rules

规则：AGENTS.md

一份写给模型看的项目说明书，每次会话自动注入上下文。相当于团队的「新人手册」。

• /init 自动扫描仓库生成，已有则原地改进；务必提交进 Git
• 写什么：构建 / lint / 测试命令、目录结构、代码规范、坑与约定——约 100 行以内，像目录页而不是百科全书
• 两级生效：项目根 AGENTS.md（团队共享）＋ 全局 ~/.config/opencode/AGENTS.md（个人偏好，比如「回复用中文」）
• 从 Claude Code 迁来？项目里的 CLAUDE.md 会自动兜底读取，无缝过渡
• 已有规范文件不必搬运，instructions 数组直接引入（支持 glob 和远程 URL）：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    "packages/*/AGENTS.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

09 · Skills

Skills 技能

技能是按需加载的任务知识包：平时只在上下文里留一行简介，模型判断相关时才加载全文——比塞进 AGENTS.md 更省 token。

§结构：一个文件夹 + 一个 SKILL.md

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable gh release create command

## When to use me
Use this when preparing a tagged release.

• name 必填：小写字母数字加连字符，且必须与目录名一致
• description 必填（≤1024 字符）：写得越准，模型选得越对
• 放置位置：.opencode/skills/（项目）、~/.config/opencode/skills/（全局）；也兼容 .claude/skills/ 和 .agents/skills/，跨客户端通用
• 用 permission.skill 控制谁能加载哪些技能，支持通配符（如 "internal-*": "deny"）

10 · Commands

自定义命令

把重复的 prompt 固化成斜杠命令。一个 Markdown 文件就是一条命令，文件名即命令名。

---
description: Create a new React component
agent: build
---
Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

之后在 TUI 输入 /component Button 即可，$ARGUMENTS 自动替换；也可以用 $1 $2 取位置参数。

§两个杀手锏

• !`command`：把 shell 命令输出注入 prompt——比如先跑测试再让模型分析
• @file：把文件内容附进 prompt

---
description: Review recent changes
---
Recent git commits:
!`git log --oneline -10`

Review these changes and suggest improvements.

11 · MCP

MCP 外接工具

通过 Model Context Protocol 给 OpenCode 接上第三方能力：查 Sentry、搜文档、连数据库……配好后工具自动出现在模型面前。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry":   { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} },
    "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" },
    "everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

• 远程 OAuth 服务器首次使用会自动弹授权；手动管理用 opencode mcp auth / list / logout / debug
• 临时停用某服务器："enabled": false；批量禁用其工具："tools": { "my-mcp*": false }
• 想让模型主动用它：prompt 里加一句 use context7，或在 AGENTS.md 里写明触发条件

12 · Config

配置文件

两个文件分工明确：opencode.json 管行为（模型、权限、MCP……），tui.json 管界面。都支持 JSONC 写注释。

§配置从哪来（低 → 高优先级）

§高频配置项

13 · CLI

CLI 速查

不带参数就是 TUI；带命令就是脚本化入口。挑最常用的记。

§值得记住的环境变量

14 · Landscape

延伸：AI 编程工具横评

理解 OpenCode 的最好方式，是把它放进整个赛道看。2026 年的核心共识是一行公式：

§五个常见名字，其实分属三类

§Claude Code vs Codex：框架哲学之别

• 技术栈：TypeScript + Ink ↔ Rust 核心，单二进制
• 安全观：Claude Code 以「权限中心」著称（allow/ask/deny + Hooks 硬拦截）；Codex 以「沙箱中心」著称（macOS Seatbelt / Linux Landlock 系统级隔离 + 审批分级）
• 上下文工程：Claude Code 靠动态 Prompt 组装和 subagent 防火墙；Codex 发明了 AGENTS.md 规范，用 git worktree 物理隔离每个任务
• 商业绑定：前者随 Anthropic 订阅，后者随 ChatGPT 订阅；桌面端都已做出并行会话、可视化 diff、定时任务（Claude 还有实时预览、屏幕控制和手机 Dispatch）

§裸 API 直连 vs Agent 工具

像 Cherry Studio 那样不设系统提示词、直连模型 API，得到的是裸引擎：

「不设系统提示词」并不等于更纯净——那只是放弃了角色定义与工具协议。模型还是那个模型，缺的是让能力落地的整套运行时。

15 · FAQ

常见问题