OpenCode: AI 开发工具介绍

发布时间： 更新时间： 总字数：2816 阅读时间：6m 作者：IP：上海 网址

OpenCode 是一款近期备受开发者关注的 100% 开源且免费的 AI 编程智能体（AI Coding Agent）。它由 anomalyco 团队开发，在定位上类似于开源版的 Claude Code，但其优势在于不绑定单一模型供应商，并且为终端（Terminal）用户提供了极致的交互体验（TUI）。本文基于官方文档和社区实践的 OpenCode 使用总结与核心指南。

核心特性

  1. 多环境支持：主要作为一个强大的终端 CLI/TUI 工具运行，但也提供桌面版应用（Beta）以及 VS Code、Cursor 等 IDE 扩展。
  2. 双 Agent 模式（核心亮点）：
    • Plan（规划模式）：按 Tab 键切换。此模式为只读模式，主要用于代码分析、探索未知代码库或设计实现方案。它不会修改你的文件，执行 bash 命令前也会主动询问。
    • Build（构建模式）：默认模式。具备完整的文件读写和命令执行权限，负责将 Plan 模式制定的计划落地为实际代码。
  3. 模型自由（Provider-Agnostic）：不强制绑定单一 AI 厂商。你可以配置使用 OpenAI、Anthropic (Claude)、Google (Gemini)，或者通过 Ollama、LM Studio 接入本地化开源模型。官方还提供了经过验证的 OpenCode Zen 模型组合供新手快速上手。
  4. 原生协议支持：内置原生 LSP（语言服务器协议）支持，能精准理解项目上下文和文件结构，拒绝幻觉猜代码；并支持 MCP（模型上下文协议）以接入各类外部工具。

安装与配置

1. 安装 OpenCode 你可以通过一键脚本或各类包管理器安装：

  • Linux / macOS（一键脚本）:
    bash 
    curl -fsSL https://opencode.ai/install | bash
  • Node.js 环境 (跨平台):
    bash 
    npm install -g opencode-ai  # 或使用 bun / pnpm / yarn
  • macOS (Homebrew):
    bash 
    brew install anomalyco/tap/opencode
  • Windows: 推荐在 WSL 下运行以获得最佳体验，或者通过包管理器安装 choco install opencode / scoop install opencode。

2. 启动与鉴权 在终端输入 opencode 即可进入 TUI 界面。 首次使用需要配置 API 密钥：在界面中输入 /connect，然后选择你拥有的供应商（如 OpenAI 或直接使用 OpenCode Zen），随后粘贴 API Key。

3. 项目初始化 进入你的项目根目录，输入：

bash 
/init

OpenCode 会分析你的项目结构，并在根目录生成一个 AGENTS.md 文件。建议将此文件提交到 Git 中，这有助于 AI 长期记忆和理解该项目的编码规范和上下文。

核心工作流（Workflow）

OpenCode 提倡 “思考与执行分离” 的工作流，最大程度避免 AI 瞎改代码毁坏项目：

  1. 提出需求：在终端输入你想完成的功能，例如：“给设置页面添加和笔记页面一样的身份验证逻辑”。
  2. Plan（规划阶段）：按 Tab 切换到 Plan 模式，或者使用 /plan 命令。让 AI 先阅读相关文件，并输出一份修改步骤与可能遇到的风险提示。
  3. 审查与细化：人工审查 AI 给出的路线图，提出修改意见。
  4. Build（构建阶段）：确认无误后，切回 Build 模式。AI 将自动分析依赖、写入确切的代码、更新导入路径并注释变更。
  5. 版本控制回退：如果对修改不满意，可以直接使用 /undo 命令撤销 AI 的修改，或用 /redo 重新应用。

核心 CLI 命令 (Core Commands)

OpenCode 提供了丰富的命令行（CLI）功能，主要分为 核心 CLI 命令 和 常用全局参数。

命令 (Command) 功能总结 (Description) 可直接运行的示例命令 (Runnable Example)
tui 启动 OpenCode 终端用户界面（TUI）。注意：如果在终端中只输入 opencode 而不加任何参数，默认也是执行此操作。 opencode
run 以非交互模式（Headless）运行。直接将 Prompt 传给大模型并输出结果后退出，非常适合脚本、CI/CD 或自动化工作流。 opencode run "用 Python 写一个快速排序"
serve 启动无头 (Headless) 后台服务器以提供 HTTP API 访问接口。可配合密码认证使用。 opencode serve --port 8080
web 启动后台 HTTP 服务器，并自动打开 Web 浏览器访问 OpenCode 的可视化 Web 界面。 opencode web
attach 将当前的终端窗口连接（附加）到已经通过 serve 或 web 命令在后台启动的 OpenCode 服务器。 opencode attach
auth 管理各大 AI 模型提供商（如 OpenAI, Anthropic 等）的 API Key 凭证登录和验证。 opencode auth login
models 获取并列出当前所有支持及配置可用的 AI 模型列表。 opencode models
agent 管理 OpenCode 的智能体（Agents）配置，允许你查看和切换不同的智能体设定。 opencode agent
mcp 管理模型上下文协议 (MCP - Model Context Protocol) 服务器，用于让 AI 连接外部工具和数据源。 opencode mcp
session 管理聊天会话历史，方便你查看之前的会话列表、恢复或清理对话记录。 opencode session
github 管理与 GitHub 的鉴权和集成设置，以便于拉取代码或提交 PR。 opencode github login
stats 查看你对模型的使用统计数据以及 Token 的消耗情况。 opencode stats
export 导出当前的对话记录或会话数据（如导出为 Markdown 或 JSON 格式以便分享或存档）。 opencode export > session.md
import 导入之前保存的对话数据或配置记录。 opencode import session.json
acp 管理和配置 ACP (Agent Context Protocol) 相关的支持和扩展。 opencode acp
upgrade 一键将你本地的 OpenCode CLI 升级至最新版本。 opencode upgrade
uninstall 彻底卸载 OpenCode CLI 及其相关配置。 opencode uninstall

使用技巧

  1. 上下文引用：在聊天窗口可以通过快捷键直接引入特定文件（如 @File#L37-42）给大模型提供精准参考。
  2. 结合 Git 工作流：可以在提交代码前，让 OpenCode 运行 pre-commit 审查；或者在 GitHub/GitLab 的 issue 中直接指派 OpenCode，它会拉取分支、修复问题并自动提交 PR。
  3. 客户端-服务端架构：OpenCode 实际上分为 Server 和 Client。这意味着你可以将其运行在性能强大的远程服务器或容器（甚至是 GitHub 运行器）中，然后在本地通过终端或移动设备与之交互。

常用全局选项与标志 (Global Flags)

在运行上述命令时，你还可以组合使用全局标志来控制 OpenCode 的具体行为：

标志 (Flags) 功能总结 可直接运行的示例命令
-m, --model 指定要使用的特定模型（格式为 提供商/模型名）。 opencode run -m google/gemini-2.5-pro "你好"
--prompt 快速发起一次非交互式 Prompt 提问（类似于 run），适合单次查询。 opencode --prompt "解释 Go 语言的并发"
-c, --continue 继续最后一次会话。 opencode --continue
--log-level 开启调试模式，打印详细的底层日志（用于排查配置或网络故障）。 opencode --log-level=DEBUG
-v, --version 打印当前安装的 OpenCode 版本号并退出。 opencode --version

opencode acp 命令

  • acp 命令代表 Agent Client Protocol（智能体客户端协议），它不是一个交互式的聊天命令，而是用于将 OpenCode 作为一个“后台服务”启动，让 IDE（如 Zed、VS Code、Neovim）通过 JSON-RPC 协议与其通信。

  • opencode acp 的作用是：启动一个基于 ACP 协议的服务器进程。

  • 核心功能与工作原理 当你执行 opencode acp 时，它会启动一个后台进程，该进程：

  • 通信机制：使用 JSON-RPC 协议通过标准输入/输出（stdin/stdout）进行通信。
  • 集成作用：它将 OpenCode 作为一个“后端代理”运行，允许支持 ACP 协议的编辑器（如 Zed, VS Code, Neovim 的插件等）直接与其交互。
  • 无缝对接：通过这种方式，你可以在 IDE 的 GUI 界面中直接调用 OpenCode 的能力，而不需要离开编辑器去手动操作终端。
  • 常见使用场景 通常你不会在终端里手动去运行这个命令并直接输入，而是由你的 IDE/编辑器插件 在后台自动调用它。例如：
  • 在 Neovim 中：使用 CodeCompanion.nvim 等插件时，配置文件可能会指定运行 opencode acp 来启动 AI 服务。
  • 在 Zed 编辑器中：Zed 支持 ACP 协议，可以将 OpenCode 配置为其中的一个辅助智能体。
  • 自动化脚本：用于构建需要与 AI 编程代理进行程序化交互的 CI/CD 流水线。
  • 常用参数 (Flags) 虽然该命令主要用于后台集成，但它支持一些常见的配置参数：
  • --cwd <path>：指定 OpenCode 运行的工作目录。
  • --port <number>：如果不是通过 stdio 而是通过网络运行，可以指定端口（较少见）。
  • --session <id>：恢复特定的对话会话。

初始化握手

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":1,"capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}},"id":1}' | opencode acp
# 启动 acp 模式
opencode acp

# 创建并获取 sessionId
{"jsonrpc": "2.0", "id": 1, "method": "session/new", "params": {"cwd": "/path/to/your/project", "mcpServers":[]}}

# 通过 session 写代码
{"jsonrpc": "2.0", "id": 2, "method": "session/prompt", "params": {"sessionId": "ses_2d1463a5dffeBIUI7sq4nis56C", "prompt":[{"type": "text", "text": "帮我写个 Python 脚本"}]}}

其他

  • oh-my-openagent 后台代理、预构建的 LSP/AST/MCP 工具、精选代理，兼容 Claude Code

参考

  1. https://github.com/anomalyco/opencode
最新评论