OpenCode 常用使用指南

基于 OpenCode 官方文档整理，最后更新：2026-05-01。

概述

OpenCode 是一个开源 AI 编程助手，运行在终端、桌面或 IDE 中。使用自然语言即可理解代码库、回答问题、编写/修改代码、执行命令。

核心特点：开源（GitHub 153K+ stars）、支持 75+ LLM 提供商（Claude / GPT / Gemini / 本地模型）、内置 LSP 支持、多会话并行、会话分享链接、可接入 GitHub Copilot 或 ChatGPT Plus/Pro 账号。

安装

一键安装（推荐）：

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

其他安装方式：

npm npm install -g opencode-ai

Bun bun install -g opencode-ai

Homebrew brew install anomalyco/tap/opencode

Arch Linux sudo pacman -S opencode 或 paru -S opencode-bin

Windows (Scoop) scoop install opencode

Windows (Chocolatey) choco install opencode

💡 Windows 用户推荐使用 WSL 获得最佳体验。详见 OpenCode Windows/WSL 文档。

配置 API Key

/connect 命令

进入 TUI 后运行 /connect 选择提供商并输入 API Key。

环境变量

1
2
3
export ANTHROPIC_API_KEY=sk-ant-xxx   # Anthropic
export OPENAI_API_KEY=sk-xxx          # OpenAI
export OPENCODE_API_KEY=xxx           # OpenCode Zen（官方精选模型）

CLI 管理

1
2
3
opencode auth login     # 交互式添加提供商
opencode auth list      # 查看已配置的提供商
opencode auth logout    # 退出某个提供商

密钥存储在 ~/.local/share/opencode/auth.json。

💡 新手推荐使用 OpenCode Zen 精选模型，访问 opencode.ai/auth 获取 API Key。

TUI 界面核心操作

在项目目录下运行 opencode 进入交互式终端界面（TUI）。

基础操作

输入消息：直接打字，回车发送；Shift+Enter 换行。

引用文件 @ 后跟文件名（模糊搜索），例如 @packages/utils.ts——文件内容自动加入对话。

执行 Shell 命令：以 ! 开头，例如 !ls -la。

外部编辑器：/editor 或 Ctrl+X E，用外部编辑器编写复杂提示词。

拖入图片：直接把截图拖入终端，AI 会识别。

必知斜杠命令

命令 快捷键 说明
/help — 查看帮助
/init — 初始化项目 AGENTS.md
/connect — 添加 AI 提供商
/models Ctrl+X M 查看可用模型列表
/new Ctrl+X N 新建会话
/sessions Ctrl+X L 查看/切换历史会话
/undo Ctrl+X U 撤销上一次对话和文件修改
/redo Ctrl+X R 重做被撤销的操作
/compact Ctrl+X C 压缩上下文（长对话后释放 token）
/share — 生成会话分享链接
/unshare — 取消会话分享
/editor Ctrl+X E 用外部编辑器编写提示词
/export Ctrl+X X 导出当前对话为 Markdown
/thinking — 显示/隐藏模型思考过程
/exit Ctrl+X Q 退出 OpenCode
/details — 展开/折叠工具执行详情

Plan 模式 vs Build 模式

按 Tab 切换模式：

  • Plan 模式：只分析/计划，不修改文件。适合复杂功能讨论。
  • Build 模式：实际执行修改。

右下角有模式指示器。

命令面板

按 Ctrl+P 打开命令面板，可搜索所有操作。

编辑器配置

设置 EDITOR 环境变量以启用 /editor 和 /export：

1
2
3
export EDITOR="code --wait"   # VS Code
export EDITOR="nvim"          # Neovim
export EDITOR="nano"          # Nano

⚠️ 部分编辑器需要 --wait 参数以阻塞等待，否则文件操作会异常。

CLI 命令模式

OpenCode 也支持非交互式命令行操作。

run — 一键执行

1
2
3
4
5
6
opencode run "解释这个项目的认证流程"
opencode run -m anthropic/claude-sonnet-4-20250514 "重构 utils.ts"
opencode run -c "继续上次的工作"                        # 续接上次会话
opencode run -f src/utils.ts "修复这个文件的 bug"       # 附加文件
opencode run --attach http://localhost:4096 "问一个问题" # 连接远程服务
opencode run --format json "..."                        # 输出 JSON 格式

其他常用 CLI 命令

opencode session list：列出所有会话

opencode stats：查看 token 用量统计（--days 7 近 7 天，--models 5 模型排名）

opencode export <id>：导出会话为 JSON

opencode import session.json：导入会话或分享链接

opencode models：列出可用模型（--refresh 刷新缓存）

opencode upgrade：更新到最新版

opencode github install：安装 GitHub Agent 自动化

serve / web 服务模式

1
2
3
opencode serve --port 4096              # 启动无头 API 服务
opencode web --port 4096                # 启动 Web 界面
opencode attach http://localhost:4096   # 附加 TUI 到已有服务

设置 OPENCODE_SERVER_PASSWORD 环境变量可启用 HTTP Basic Auth。

Skills 技能系统

Skills 是给 AI 提供的可复用专业指令，按需加载，不占用上下文。

技能发现路径

项目级 .opencode/skills/<name>/SKILL.md

全局 ~/.config/opencode/skills/<name>/SKILL.md

Claude 兼容路径 .claude/skills/<name>/SKILL.md 或 ~/.claude/skills/<name>/SKILL.md

安装与管理

1
2
3
4
npx skills find [关键词]                           # 搜索技能
npx skills add <owner/repo@skill> -g -y            # 安装技能
npx skills check                                    # 检查更新
npx skills update                                   # 更新所有技能

推荐技能

前端 frontend-design（前端设计）、vercel-react-best-practices（React）

测试 test-driven-development（TDD）、webapp-testing

代码质量 systematic-debugging（调试）、polish（代码打磨）

文档处理 pdf、xlsx、docx

工作流 brainstorming（头脑风暴）、writing-plans（编写计划）

详见 常用技能列表 中的完整技能目录。

AGENTS.md 项目规则

AGENTS.md 是项目最高优先级工作约定文件，告诉 AI 项目架构、编码规范和行文约束。

初始化

在项目目录下运行 opencode 后执行 /init，OpenCode 会自动分析项目并生成 AGENTS.md。

💡 务必把 AGENTS.md 提交到 Git，保证团队协作中 AI 行为一致。

也可以参考 LLM Wiki 的 AGENTS.md 手写，定义架构、规范、测试策略和 AI 行为约束。

撤销与恢复

OpenCode 通过 Git 管理文件修改，支持无限次撤销。

操作 命令 说明
撤销上次 /undo (Ctrl+X U) 移除最后一条消息、回复及文件改动
重做 /redo (Ctrl+X R) 仅在 /undo 后可用
多次撤销 连续 /undo 可回退多步

⚠️ 撤销依赖 Git，项目必须为 Git 仓库。

会话分享

1
2
/share        # 生成分享链接（复制到剪贴板）
/unshare      # 取消分享

会话默认不分享。分享后他人可通过链接查看对话记录。

常用工作流

理解代码库

直接进入 TUI 提问：”帮我梳理项目架构”、”@packages/auth 认证模块怎么实现的？”

实现新功能（推荐 Plan 模式）

  1. 按 Tab 切到 Plan 模式
  2. 描述需求：”增加软删除功能，改动数据库和 UI”
  3. 审核计划，给反馈：”UI 请参考这张截图 [拖入图片]”
  4. 按 Tab 切回 Build 模式：”没问题，开始实现”

修 Bug

直接给上下文：”在 @src/api/auth.ts 里登录超时后会崩溃，定位根因并修复”

代码审查

“review @src/utils/http.ts，检查安全性和性能”

批量重构

/editor 打开外部编辑器，写好详细的重构要求（保持接口签名、统一错误处理、确保测试通过）。

自动化 CI

opencode github install 安装 GitHub Agent 后可自动处理 Issue/PR；也可 opencode run "根据 #42 issue 修复 bug" 命令行自动运行。

技巧与注意事项

  1. 多给上下文：用 @ 引用关键文件，AI 表现会大幅提升。
  2. 小步快跑：一次问一件事，不要一次要求太多。
  3. 先说目标再说细节：先让 AI 理解目标，再补充约束。
  4. 图片输入：直接拖入终端发送截图，AI 能识别。
  5. 善用撤销：改坏了就 /undo，不要手动回滚。
  6. 长对话及时 compact：会话太长会超出 token 上限，用 /compact 压缩。
  7. Plan 模式省 token：复杂任务先讨论再执行。
  8. 提交 AGENTS.md：纳入版本管理，保证 AI 行为一致。

TUI 配置

tui.json

1
2
3
4
5
6
7
8
9
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "keybinds": { "leader": "ctrl+x" },
  "scroll_speed": 3,
  "scroll_acceleration": { "enabled": false },
  "diff_style": "auto",
  "mouse": true
}

可用 /themes (Ctrl+X T) 预览主题，Ctrl+P 命令面板中搜索切换。

opencode.json 权限控制

1
2
3
4
5
6
7
8
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "permission": {
    "bash": { "*": "ask" },
    "skill": { "*": "allow" }
  }
}

常用环境变量

OPENCODE_CONFIG：自定义配置文件路径

OPENCODE_TUI_CONFIG：TUI 配置文件路径

OPENCODE_PERMISSION：内联权限 JSON

OPENCODE_DISABLE_AUTOUPDATE：禁用自动更新

OPENCODE_DISABLE_AUTOCOMPACT：禁用自动上下文压缩

OPENCODE_SERVER_PASSWORD：为 serve/web 设置密码