入门

OpenCode 入门不是把所有安装命令背一遍，而是在一台真实开发机器上跑通第一条安全闭环：能启动、能连接模型、能读项目、能受控修改、能撤销、知道下一步该配置什么。

先跑通安全闭环

第一次使用 OpenCode，不要先研究 plugin、MCP、LSP 或团队治理。先按下面顺序确认基础能力。

flowchart LR
    Terminal["现代终端"] --> Install["安装 opencode"]
    Install --> Provider["连接 provider"]
    Provider --> Project["进入真实 Git 仓库"]
    Project --> Init["/init 生成 AGENTS.md 初稿"]
    Init --> ReadOnly["第一轮只读分析"]
    ReadOnly --> WriteSmall["第一轮限定写入"]
    WriteSmall --> Undo["确认 /undo 和 /redo"]
    Undo --> Next["进入个性化配置"]

    style Terminal fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style ReadOnly fill:#dcfce7,stroke:#22c55e
    style WriteSmall fill:#fef3c7,stroke:#f59e0b
    style Undo fill:#fee2e2,stroke:#ef4444

这条路径故意保守。Coding agent 会读取文件、修改文件、运行命令和调用外部模型。先证明它能被约束，再扩大任务范围。

1. 准备终端和模型密钥

要在终端里使用 OpenCode，你至少需要两样东西：

• 现代终端：TUI 显示、快捷键、拖放图片、交互输入都依赖终端能力。
• LLM provider API key：OpenCode 是 agent 运行时，推理仍由模型 provider 提供。

官方文档列出的现代终端包括 WezTerm、Alacritty、Ghostty 和 Kitty。macOS 或 Linux 用户如果已经在用 Ghostty、WezTerm 或 iTerm2，通常可以直接开始。

2. 安装 OpenCode

官方最直接的安装方式是安装脚本：

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

如果你偏好包管理器，可以选更符合当前机器的方式。

• macOS / Linux：brew install anomalyco/tap/opencode 或安装脚本。
• Node.js 环境：npm install -g opencode-ai。
• Windows：优先 WSL，再考虑 Chocolatey、Scoop、npm、Mise、Docker 或 release binary。
• Arch Linux：sudo pacman -S opencode 或 AUR 的 opencode-bin。

Homebrew 用户优先使用 OpenCode 官方 tap：

brew install anomalyco/tap/opencode

Node.js 用户最常用 npm：

npm install -g opencode-ai

Windows 可以直接装，但 coding agent 对 shell、Git、语言工具链和文件权限依赖很重。第一次学习建议用 WSL，这样更接近多数开源项目默认假设的 Linux 开发环境。

安装后先验证命令，不要马上进入项目改代码：

opencode --help

如果命令找不到，先查 PATH 和安装位置：

which opencode
echo $PATH

3. 连接模型 provider

启动 TUI 后输入：

/connect

第一次可以选择 OpenCode Zen，按照页面提示前往 opencode.ai/auth 登录、添加账单信息并复制 API key。OpenCode 也支持其他 provider，后续可以在 provider 目录里选择。

如果你更喜欢 CLI 管理凭据，也可以使用：

opencode auth login
opencode auth list

两种方式的区别很简单：

• /connect 适合第一次在 TUI 里跑通。
• opencode auth login 适合在终端里管理和复查 provider 凭据。
• .env 或环境变量适合已经有统一凭据管理的人。

4. 在真实项目里初始化

配置好 provider 后，进入你真正要处理的项目目录。

cd /path/to/project
opencode

然后运行：

/init

OpenCode 会分析项目并生成项目根目录的 AGENTS.md 初稿。这个文件应该提交到 Git，因为它是团队共享项目上下文的入口，适合写项目结构、包管理器、测试命令、编码约定、禁止修改范围和发布边界。

5. 第一轮只做只读任务

第一次任务不要让 OpenCode 改文件。先验证它能不能正确理解仓库。

先快速阅读这个仓库的目录结构，不要修改文件。
请按这四点输出：
1. 项目的技术栈和入口文件。
2. 主要模块分别做什么。
3. 你会优先阅读哪些文件来理解项目。
4. 你现在还不确定、需要我确认的问题。

这条提示词同时做三件事：

• 限制动作：明确“不要修改文件”。
• 验证上下文：看它是否真的读到了项目结构。
• 暴露不确定性：要求它说出不知道的地方。

需要引用具体文件时，按 @ 模糊搜索文件：

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

如果第一轮只读任务就开始改文件，先停下来检查模式、提示词和权限，不要继续扩大任务范围。

6. 第一轮写入只改单文件

只读任务稳定后，再做一个低风险写入。优先选择 README、文档或测试说明，不要上来重构核心模块。

只修改 README.md 中的安装说明，把命令整理成 macOS、Linux、Windows 三段。
不要修改其他文件。
改完后先解释 diff，再告诉我建议运行什么检查命令。

合格结果应该满足四点：

• 只改你指定的文件。
• 能解释具体 diff。
• 能给出合理的验证命令。
• 不会自作主张 commit、push 或部署。

如果任务稍复杂，先按 Tab 切到 Plan mode，让 OpenCode 只给计划；计划确认后再按 Tab 回到 Build mode 执行。这个动作比“事后回滚一堆无关文件”成本低得多。

7. 会撤销，才算能继续

OpenCode 支持撤销和重做当前会话产生的修改：

/undo

/redo

第一次低风险写入后，至少确认你知道这两个命令的用途。真正进入大范围修改前，还要配合 Git diff 查看文件边界。

8. 分享默认手动触发

OpenCode 会话可以通过 /share 生成分享链接：

/share

对话默认不会自动分享。分享前要确认当前会话里没有密钥、账号、客户数据、内部路径、未公开仓库信息或商业策略。敏感项目宁愿不分享，也不要事后补救。

9. 继续做个性化配置

跑通第一轮以后，再进入个性化配置：

• 主题和 keybinds：让 TUI 更顺手。
• rules 和 AGENTS.md：沉淀项目规则。
• commands：把重复提示词变成 slash command。
• formatters：把格式化交给确定性工具。
• agents、skills、plugins、MCP：把复杂能力拆到更清晰的边界里。

不要把这些配置一次性全开。每次只加一种能力，并用真实任务验证它是否减少了重复沟通或降低了出错概率。

接下来去哪

官方资料

• OpenCode 入门：https://opencode.ai/docs
• OpenCode CLI：https://opencode.ai/docs/cli
• Windows / WSL：https://opencode.ai/docs/windows-wsl
• OpenCode Zen：https://opencode.ai/docs/zen