OpenCode 快速入门

一句话卖点:开源、MIT 协议、本地终端跑的多模型 AI 编程 Agent,被社区戏称「Claude Code 的开源替代」。

这是什么?适合谁?

OpenCode 是一款终端里的 AI 编程 Agent,由 SST(sst/opencode)社区主导开发,采用 MIT 协议开源。它不是 IDE 插件,而是一个独立的命令行工具:opencode 命令敲下去,直接进入一个 TUI(终端 UI)界面,你可以在里面描述需求,AI 会自己去读、改、跑命令。

它跟其他 CLI 编程 Agent(比如 Claude Code、Aider)相比,有几个特点:

• 模型无关:同一套 CLI 接 75+ 模型供应商,包括 Anthropic、OpenAI、Google、DeepSeek、Groq、OpenRouter、本地 Ollama 等,你想用哪个用哪个;
• 多 Agent 并行:可以同时跑多个 Agent 各自干各自的活,再合并结果;
• LSP 自动加载:项目里装了 TypeScript / Python / Go 的 LSP,OpenCode 会自动拉起来用,跳转会准;
• TUI 而非纯文本:用 Bubble Tea 写的终端界面,有语法高亮、有 diff 视图、有文件树;
• 可脚本化:支持 -p 一句话模式、--share 分享 session、<task> 工具定义文件。

适合谁?习惯终端的开发者、想低成本试不同模型的人、对数据敏感不愿把代码传到闭源 SaaS 的团队、需要把 AI 编程 Agent 跑进 CI / Docker 的人。

不适合纯小白——你至少要会用 git、能看懂报错。

准备工作

1. Node.js ≥ 18(官网推荐 ≥ 20);
2. 一个你常用的 AI 模型 API Key(OpenAI / Anthropic / DeepSeek 都行,本地模型可以零 Key);
3. 一个终端:macOS Terminal、iTerm2、Windows Terminal、WezTerm 都行;
4. (可选)Git,很多 OpenCode 工作流基于 git 改动。

3 步快速上手

第 1 步:安装

macOS / Linux 推荐用官方安装脚本:

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

或用 Homebrew:

brew install opencode

Windows 上推荐用 scoop 或直接下载 release:

scoop install opencode

安装完后在任意目录敲 opencode,能看到版本号就说明装好了。

第 2 步:配置模型

第一次启动会引导你选 provider,也可以手动编辑 ~/.config/opencode/config.json:

{
  "provider": {
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    },
    "deepseek": {
      "apiKey": "sk-xxx"
    }
  },
  "defaultModel": "anthropic/claude-sonnet-4"
}

OpenCode 用 <provider>/<model> 这种字符串写模型名,完整列表见 https://opencode.ai/docs/models。

第 3 步:跑第一个任务

切到你的项目目录:

cd ~/work/my-app
opencode

进入 TUI 后输入:

在这个 Next.js 项目里,把所有 <img> 替换成 next/image,并补全 width / height 属性。

按 Enter,OpenCode 会先列出要改的文件、给出 diff,在右侧 diff 视图里你可以 y 接受、n 拒绝。完成后用 git diff 复查改动即可。

如果想用一句命令模式(不进入 TUI):

opencode -p "给 src/utils/date.ts 加单测,使用 vitest"

常见踩坑

1. Node 版本太低:opencode: command not found 或运行报错,先 node -v,低于 18 请升级;
2. API Key 没生效:在 config 里写错了字段名(api_key 而不是 apiKey)会导致 silent 失败,用 opencode --debug 看日志;
3. TUI 乱码:Windows Terminal 默认 OK,但 cmd.exe / PowerShell ISE 不支持 TUI,先换 Windows Terminal;
4. LSP 没起来:项目里没装对应语言的 LSP,跳转不准是正常的,比如 Go 项目要先 go install gopls@latest;
5. diff 视图接受后没生效:有些大文件 OpenCode 会拆成多次写入,需要一直按 y 直到结束,中途按 n 会回滚本次修改;
6. 跑得太贵:默认会用 Sonnet 这种较贵的模型,本地开发可以在 config 里把默认改成 deepseek/deepseek-chat 或本地 Ollama,几乎免费。

初级用法

• 单文件解释:opencode -p "用中文解释 src/auth/login.ts 的逻辑";
• 生成 commit message:opencode -p "看一下 git diff 帮我写一个 commit message,使用 conventional commits";
• 代码搜索:opencode -p "找出所有调用 getUserById 的地方,只列文件路径和行号"。

高级玩法

• 多 Agent 并行:在 TUI 里按 Tab 新建 Agent,一个修前端 bug、一个写后端 API、一个写测试,互不干扰;
• 自定义工具:在 ~/.config/opencode/tools/ 下放 <name>.ts 文件定义工具,例如「部署到 Vercel」「查 Linear 工单」,AI 可以调用;
• CI 集成:在 GitHub Actions 里跑 opencode -p "review this PR diff and post comments" --share,自动评审 PR;
• 本地模型:装 Ollama 后跑 ollama pull qwen2.5-coder:32b,OpenCode 里选 ollama/qwen2.5-coder:32b 完全离线跑。

小技巧

1. prompt 里写明「先列计划再动手」:OpenCode 默认会直接改,如果你想先看计划再说,在 prompt 后加一句「先给我列计划,等我确认再动文件」;
2. 善用 <file> 引用:在 prompt 里写 <file>src/api/users.ts</file> 让 AI 精准读目标文件,不用整仓搜;
3. 常用 prompt 写成 .opencode/commands/:在项目根放 .opencode/commands/review.md,内容是固定 prompt 模板,在 TUI 里 /review 直接调用;
4. 保护敏感目录:在 config.json 加 "excludePaths": [".env", "secrets/", "node_modules/"],AI 不会去碰;
5. 会话可分享:opencode --share <session-id> 会生成一个只读链接,别人能看到你跟 AI 的对话全过程,适合贴 PR 解释决策。

常见问题 FAQ

Q1: OpenCode 适合哪些编程语言?

A: OpenCode 通常支持主流编程语言(Python、JavaScript/TypeScript、Java、Go、C++、Rust 等)。支持程度因语言而异:Python/JavaScript/TypeScript 最佳,小众语言(如 Haskell、Elixir)可能较弱。

Q2: OpenCode 生成的代码可以直接用吗?

A: 简单的 CRUD、工具函数、单元测试可以直接用;复杂的业务逻辑、算法实现需要人工 review。永远不要盲目复制 AI 生成的代码——先理解再使用。

Q3: OpenCode 怎么收费?

A: 通常分免费版(基础功能,有限次数)、付费版(高级模型、无限次数、团队协作)。个人开发者 Pro 版约 $10-20/月,企业版 $30-50/用户/月。具体以 https://opencode.ai/ 定价为准。

Q4: OpenCode 会上传我的代码到云端吗?有隐私问题吗?

A: 大部分 AI 编程工具会保存你的代码用于服务提供(模型推理)和模型改进(除非关闭)。敏感代码(企业核心、商业秘密)建议:1) 使用本地部署版本;2) 关闭”使用我的代码改进模型”选项;3) 考虑企业版(有更强隐私保护)。

Q5: 怎么让 OpenCode 生成更高质量的代码?

A: 关键技巧:1) 写清晰的 prompt,说明输入输出和约束;2) 提供代码示例(让 AI 学习你的风格);3) 拆分任务,不要一次生成太多;4) 用 TODO 注释让 AI 补充具体实现;5) review + 单元测试保证质量。

进阶学习建议

如果想进一步用好 OpenCode,建议按以下路径学习:

第 1 周:熟练基础

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些操作有效、哪些没用”——形成自己的笔记

第 2 周:探索功能

• 把界面上的按钮/菜单都点一遍
• 找到最常用的 3-5 个功能
• 配置个性化设置(主题、快捷键、默认参数)

第 3-4 周:融入工作流

• 找到 OpenCode 与你现有工具的结合点
• 用快捷键/模板/批处理提高效率
• 考虑付费升级(如果免费版够用就不必)

长期:进阶玩法

• 探索 OpenCode 的 API/SDK 集成
• 写自己的脚本/扩展/插件
• 关注官方博客/更新日志,第一时间用上新功能

推荐资源:

• 官方文档:https://opencode.ai/
• 官方 YouTube/B 站频道(看产品演示)
• 国内社区:CSDN/掘金/知乎搜 “OpenCode 教程”
• 国外社区:Reddit、Product Hunt 评论区

避免的坑:

• 不要追求”全能工具”——OpenCode 不可能满足所有需求
• 不要盲目订阅付费版——先用免费版验证价值
• 不要忽略数据备份——重要内容定期导出
• 不要被新功能冲昏头脑——核心功能用熟再拓展

参考链接

• OpenCode 官方主页:https://opencode.ai/
• 安装文档:https://opencode.ai/docs/install
• 模型支持矩阵:https://opencode.ai/docs/models
• GitHub 仓库:https://github.com/sst/opencode
• 配置参考:https://opencode.ai/docs/config

FAQ 速查

Q:OpenCode 跟 Claude Code 有什么区别? A:Claude Code 是 Anthropic 官方闭源产品,只能用 Anthropic 模型;OpenCode 是 MIT 协议开源,支持 75+ 模型商。两者在 TUI 体验上相似,但 OpenCode 更轻、更可定制,Claude Code 在「项目级长上下文理解」上略胜一筹。

Q:OpenCode 支持 Windows 原生吗? A:支持。推荐用 scoop / winget 安装,或直接下载 GitHub Release 的 .exe。如果遇到 TUI 显示问题,优先用 Windows Terminal,避免 cmd.exe。

Q:跑 OpenCode 会把代码上传到云吗? A:取决于你选的模型。接 Anthropic / OpenAI 会走它们的 API;接 Ollama / 自部署 vLLM 完全本地。对数据敏感的团队,选本地模型。

Q:OpenCode 的 License 能商用吗? A:MIT 协议,商用、修改、私有化都可以,只要保留版权声明。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。