CangLu Knowledge Base

总览

8分钟阅读

opencode 上手总览

learn 索引 | 主题索引

1. 先记住一句话

opencode 是一个跑在终端里的 AI 编码代理。日常使用只有一条主线：进到一个 Git 仓库里 → 敲 opencode 打开 TUI → 用自然语言让它读代码、改代码、跑命令 → 你审核并确认。它不绑定某一家模型，配一次供应商凭证就能一直用。

2. 最短上手路径

第一步：安装

本机推荐用 npm 全局安装（版本最新、更新方便）：

npm install -g opencode-ai

其他方式（任选其一即可，别重复装）：

# Homebrew（版本更新较慢）
brew install opencode
 
# 官方安装脚本（最新，但属于执行远程脚本，注意安全）
curl -fsSL https://opencode.ai/install | bash

验证安装：

opencode --version   # 应输出版本号，如 1.17.18
which opencode       # 确认在 PATH 中

第二步：配置模型供应商（第一次必做）

没有配供应商凭证，进 TUI 也没法对话。用交互式登录：

opencode auth login
# 等价命令：opencode providers login

按提示选供应商（Anthropic / OpenAI / OpenRouter / 本地 Ollama 等），粘贴对应的 API Key 即可。查看已配置的供应商：

opencode auth list           # 或 opencode providers list
opencode models              # 列出当前可用的所有模型

第三步：进仓库启动

cd /path/to/your-project   # 一定先进到目标 Git 仓库
opencode                    # 打开 TUI，默认作用于当前目录

进入 TUI 后，直接在输入框里用中文/英文描述需求，比如「帮我看下 UserService 的登录逻辑有没有并发问题」。opencode 会读相关文件、给出分析或改动，涉及写文件、跑命令时会请求你确认。

第四步：只掌握这几个操作

  • 输入需求 → 回车发送。
  • 它要改文件或执行命令时，看清楚再批准/拒绝。
  • 想开新话题：新建会话（避免上下文越滚越长）。
  • 想换模型：在 TUI 里切换供应商/模型。
  • 卡住或跑偏：中断当前生成，重新描述。
  • 忘记快捷键：按 ? 打开帮助面板（这是最可靠的快捷键来源）。

opencode 的 TUI 用 leader 键触发大部分操作，默认 leader 是 ctrl+x。例如退出是 ctrl+c / ctrl+d / <leader>q，打开外部编辑器是 <leader>e。完整键位见 速查清单。

3. 80% 高频场景

场景一：读懂一段陌生代码

进到仓库启动 TUI，直接问：

解释 src/service/OrderService 的下单主流程，指出关键分支和外部依赖

opencode 会自动检索相关文件再回答，比自己 grep 快。追问时它保留上下文，可以继续「那退款流程呢」。

场景二：改一个 Bug 或加一个小功能

描述清楚「现象 + 期望」，让它先给方案再动手：

登录接口偶发 500，日志报空指针，先定位原因再给修复方案，别直接改

确认方案后再让它落地。养成习惯：先让它说思路，你认可了再让它写。 写完让它跑一遍相关测试。

场景三：脚本化 / 单次执行（不进 TUI）

适合接自动化、CI，或只想问一句就走：

opencode run "把 README 里的安装步骤翻译成英文"
opencode run -c "继续上一个会话的任务"          # -c 续上次会话
opencode run -m anthropic/claude-... "..."      # -m 指定模型
opencode run -f src/a.ts -f src/b.ts "对比这两个文件的差异"  # -f 附带文件

opencode run 支持 --format json 输出结构化事件，方便被程序解析。

场景四：多模型 / 本地模型切换

  • 想省钱或离线：配 Ollama 本地模型，opencode models 里就能看到。
  • 想按任务选模型：TUI 里随时切换，或用 opencode run -m provider/model。
  • 复杂任务想加大推理力度：run 支持 --variant high|max 控制推理强度（供应商相关）。

4. 配置文件在哪

opencode 的行为可以用配置文件调整，核心是项目根或用户级的 opencode.json（键位相关也可用 tui.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "editor_open": "<leader>e"
  }
}
  • 项目级配置放仓库根目录，可随仓库提交、团队共享。
  • 另有 AGENTS.md 约定：放在仓库里，用来给 agent 提供项目背景与规则（类似给它的「须知」）。
  • 不确定字段时，靠 $schema 在编辑器里获得补全，别凭记忆硬写。

5. 先别学什么

刚上手时，先不要纠结：

  • 自定义 agent、MCP 服务器接入（opencode mcp / opencode agent）。
  • ACP server、headless serve、web 界面、attach 远程会话。
  • GitHub agent 自动化（opencode github）。
  • 全部 60+ 键位的记忆。
  • 精细的权限引擎配置。

这些属于后 80% 的进阶能力，先把「进仓库 → 对话 → 审核改动」这条主线练熟。

6. 常见误区

误区正确理解
装了就能直接对话必须先 opencode auth login 配供应商凭证
在任意目录启动都行应先 cd 进目标 Git 仓库，它默认作用于当前目录
让它一次性改一大堆上下文越长越容易跑偏，拆小步、勤开新会话更稳
它改的代码可以直接信它会请求确认，务必自己审核 + 跑测试再合入
npm 和 brew 都装一份没关系会造成版本混乱，选一种安装方式即可
记不住快捷键要去翻文档TUI 内按 ? 就是最快、最准的键位来源

7. 推荐日常习惯

  • 每个仓库单独启动，别跨项目混用一个会话。
  • 先让它给方案，认可后再落地代码。
  • 改动后立刻让它跑相关测试或自己验证。
  • 任务切换就开新会话，保持上下文干净。
  • 用 opencode run 把重复性问答沉淀成脚本。
  • 键位、模型不确定时，用 ? 面板和 opencode models 现场确认，不猜。

关系图谱