AI 编程工具正在从“聊天窗口里的代码补全”走向可以读取项目、运行命令、调用工具、持续维护上下文并交付修改的 coding agent。OpenCode 就是这一方向中非常有代表性的开源项目：它提供终端界面、可选桌面应用、HTTP Server、客户端 SDK 和插件机制，让开发者能够在自己的机器或团队基础设施中运行、审计和扩展 Agent。
OpenCode 的官方定位是“开源的 AI coding agent”。与只绑定一家模型厂商的客户端不同，它把 Agent 运行时、模型 Provider、会话存储、工具调用、权限策略、MCP、插件和用户界面拆成相对清晰的层。你可以在终端直接启动，也可以启动服务后通过 Web、桌面端或 SDK 连接；可以使用 Anthropic、OpenAI、Google、xAI、Amazon Bedrock、OpenRouter、GitHub Copilot、OpenAI-compatible 等多种 Provider。
截至 2026 年 8 月 13 日，GitHub API 快照显示仓库约有 196,723 个 Star、25,285 个 Fork 和 5,107 个未关闭 Issue，默认分支为 dev，主要语言为 TypeScript，采用 MIT 许可证。最新正式 Release 为 v1.18.18，发布于 2026 年 8 月 13 日；仓库的 packages/opencode/package.json 同样标记为 1.18.18。项目迭代非常快，文中的版本、命令和配置应以实际 Release Notes 为准。
OpenCode 是什么？
OpenCode 可以理解为一个“本地优先、可服务化、面向开发者的 Agent 平台”。在最常见的终端模式中，它打开当前项目目录，读取项目说明和代码文件，根据用户请求生成计划，调用读取、搜索、编辑、Shell、LSP、Git、测试等工具，最后把修改和执行结果呈现出来。它的关键不在某个单独的模型，而在于如何把模型推理、工具执行、权限确认和会话持久化串成可恢复的工程流程。
项目同时提供图形化入口：官方 README 将桌面应用标为 Beta，可从 Release 页面或官网下载安装 macOS、Windows 和 Linux 版本。桌面端本质上是 Electron 应用，能够与 OpenCode 的服务和客户端能力协作；终端用户也可以运行 Web 模式或连接远程 Server。对于团队而言，这种“同一运行时、多种前端”的结构比把逻辑复制到多个客户端更容易维护。
核心设计：Agent Runtime
OpenCode 的 Agent Runtime 可以拆成几个相互配合的层：
- Session：持久化用户输入、模型消息、工具调用、结果、错误和上下文变化，支持恢复、重试、压缩和事件订阅。
- Provider：把不同厂商或兼容端点统一到 AI SDK 风格的模型接口，并处理认证、模型发现、请求选项和流式响应。
- Agent：决定系统提示、可使用的工具、权限策略、模型选择和每轮行为；内置
build与plan两种 Agent。 - Tool Registry：注册读取、搜索、编辑、写入、Shell、LSP、任务委派、问题询问、Web 获取、Web 搜索等工具。
- Context：组合项目指令、AGENTS.md、技能说明、工具结果和动态上下文，形成发送给模型的系统上下文。
- Server/Client：通过 HTTP API、SSE 和 WebSocket 对外提供会话、事件、工具和管理能力，同时支持进程内 Embedded OpenCode。
这种分层让 OpenCode 不必把所有逻辑塞进一个终端循环。模型可以更换，前端可以更换，某个工具或插件也可以独立演进；但层之间的协议、会话状态和权限边界必须稳定，否则一个小改动就可能影响 SDK、TUI 和桌面端。
CLI、TUI 与桌面应用
命令行入口
根目录的 CLI 使用 yargs 组织命令。当前入口包含运行 Agent、生成内容、账户与 Provider 管理、Agent 管理、升级与卸载、Server、Web、模型、统计、MCP、GitHub、PR、会话、数据库、插件、导入导出、Attach、TUI 和 ACP 等命令。运行 opencode --help 可以查看当前版本实际暴露的命令。
CLI 还支持全局日志开关、日志级别和 --pure 模式。--pure 用于不加载外部插件的运行场景，适合排查插件导致的问题或构建更可预测的执行环境。程序启动时会设置 OPENCODE、OPENCODE_PID 等环境变量，工具和子进程可以据此识别自己处于 Agent 执行上下文。
终端 UI
TUI 适合在 SSH、远程开发机和不希望打开浏览器的环境中工作。它将对话、工具执行、Diff、权限请求、问题确认和 Agent 切换放在终端内；README 提到可以使用 Tab 在 build 与 plan Agent 之间切换。终端模式的优势是启动快、依赖少、与 Shell 和 Git 工作流紧密，但复杂的多会话浏览、文件树和视觉 Diff 更适合桌面或 Web 前端。
桌面应用
桌面应用使用 Electron 构建，当前标注为 Beta。它把 OpenCode 的服务能力包装成更完整的桌面工作区，适合希望获得系统菜单、窗口管理、原生安装和升级体验的用户。Beta 版本意味着安装包、自动更新、系统权限和跨平台行为仍可能变化，企业部署应先在受控设备和固定版本上验证。
两个内置 Agent：build 与 plan
build 是默认的全权限 Agent，适合真正执行开发任务：读取代码、修改文件、运行测试、检查 Git 状态并完成多步实现。它的“全权限”并不意味着可以绕过所有确认；工具策略仍会根据项目配置和安全规则请求用户允许高风险操作。
plan 是只读分析 Agent，默认拒绝文件编辑，并在运行 Bash 命令前询问权限。它适合探索陌生代码库、拆解需求、评估实现方案和生成改动计划。先用 plan 建立上下文，再切换到 build 执行，通常能减少误改和无效试错。
项目还包含一个 general 子 Agent，用于复杂搜索和多步任务，可在对话中使用 @general 调用。子 Agent 的价值是把大任务拆成并行或分阶段的调查工作，但它们依然共享项目权限和敏感上下文，不能因为“由子 Agent 执行”就忽略审计。
模型 Provider 与统一适配
OpenCode 的 Provider 层建立在 Vercel AI SDK 生态之上，并内置大量动态加载的适配器。源码可以看到 Anthropic、OpenAI、Azure、Google Gemini、Google Vertex、Amazon Bedrock、xAI、Mistral、Groq、DeepInfra、Cerebras、Cohere、Together AI、Perplexity、OpenRouter、Vercel、Alibaba、GitLab、Venice 和 OpenAI-compatible 等 Provider。
动态加载很重要：只有实际选中的 Provider 才需要加载对应 SDK，减少 CLI 的初始成本，也让插件或自定义 Provider 有机会补充模型。Provider 层还负责模型发现、认证信息、环境变量、超时、流式响应超时和请求转换。例如 SSE 响应可以配置读取超时，长时间没有数据时主动中止，避免终端会话无限挂起。
多模型不是无限兼容
统一接口并不意味着所有模型行为完全一致。不同 Provider 对工具调用、思考预算、图片、缓存、结构化输出、Responses API、Chat Completions 和模型参数的支持不同。OpenCode 将生成控制、Provider 语义选项和兼容请求字段分开，再由具体协议适配器负责编码；使用时仍应针对目标模型验证工具调用和长上下文，而不是只看模型名称能否出现在列表里。
工具系统：让模型真正“做事”
OpenCode 内置的工具覆盖了一个开发闭环：
- 读取与搜索：读取文件、Glob 文件匹配、Grep 内容搜索，帮助模型以较小上下文定位代码。
- 编辑与写入：Apply Patch、编辑和写入工具用于生成可审阅的文件变更。
- Shell：执行构建、测试、格式化、Git 和项目脚本。
- LSP：利用语言服务器获取诊断、符号和代码导航信息。
- 任务与问题：委派子任务、向用户询问缺失信息，并维护 Todo。
- 网络能力：Web Fetch、Web Search 和 MCP Web Search 用于读取外部文档或检索资料。
- 技能与插件：通过 skill 工具加载受权限控制的技能，通过插件注册额外能力。
工具结果会进入会话上下文，并可能被模型继续使用。一个好的 Agent 不只是“工具越多越好”：工具需要清晰的参数 Schema、输出截断策略、错误分类、权限等级和可观察日志。OpenCode 还包含输出截断与截断目录等代码，说明它把“工具输出可能过大”当作运行时问题处理。
权限与安全边界
代码 Agent 的核心风险不是模型回答错误，而是模型拥有执行操作的能力。OpenCode 把工具权限、Agent 策略和用户确认放在运行时的重要位置。读取公共代码、修改本地文件、执行测试、访问网络、删除数据、运行安装脚本的风险等级不同，不应使用一套“全部允许”策略覆盖所有项目。
plan Agent 的只读默认值是一种安全提示：探索阶段可以不授予写入权限；进入 build 后再按工具逐项允许。对于 CI、远程服务器或无人值守流程，应使用专用工作区、最小文件权限、无生产密钥环境和可回滚分支，并在执行 Shell 前检查命令来源与参数。
网络工具、MCP Server 和插件会扩大信任边界。一个恶意网页、被污染的依赖、过度授权的 MCP 或插件，都可能诱导 Agent 泄露代码、读取密钥或执行危险命令。生产环境应固定插件版本，审查其源码和权限，关闭不需要的网络能力，并把凭据放在不会自动进入模型上下文的密钥存储中。
项目上下文与 AGENTS.md
OpenCode 不只读取当前对话。项目上下文还可以来自仓库根目录和上级目录的 AGENTS.md、项目说明、技能、工具结果和动态状态。系统上下文注册表会以稳定键组织多个 Context Source，在安全的 Provider-turn 边界重新组合；上下文变化不会随时打断正在运行的模型轮次，而是在合适边界生效。
这套机制解决了一个实际问题：团队规范、测试命令、目录约定和安全要求需要长期影响 Agent，但不能每次都靠用户重复粘贴。将重要规则写入版本控制的 AGENTS.md，并在 Pull Request 中审查变更，比把规范散落在个人提示词里更可靠。不过，规则文件本身也属于可执行上下文的一部分，外部仓库或依赖带来的指令必须谨慎对待，不能盲目执行其中的下载、上传和密钥操作。
会话持久化、恢复与上下文压缩
OpenCode 的 Session 不是一次性聊天记录，而是 Agent 运行的持久化边界。项目使用 Drizzle ORM 和 SQLite 相关实现保存会话、消息、事件、工具状态与数据库迁移。会话可以恢复、导入、导出、回滚和订阅事件；CLI 还暴露 Session、DB、Export 和 Import 等命令。
长会话会遇到上下文窗口限制。OpenCode 将 compaction 设计成一个明确的 Context Epoch 转换：把当前完整系统上下文重新渲染成新的基线，保留必要的审计历史，同时移除旧的中间系统消息。这样比简单截断最早消息更可控，也能避免模型在长时间工作后丢失项目规则。
V2 Session Runtime 还区分 durable prompt、projected history、provider attempt 和本地 Session drain。Steering prompt 可以在安全边界插入，queued prompt 则等待当前执行接近空闲时再提升。这个设计说明项目在解决多输入并发、崩溃恢复和重复提交问题，而不只是把内存里的消息数组写进数据库。
HTTP Server、SSE、WebSocket 与 SDK
OpenCode 可以作为本地或远程 Server 运行。Server 层使用 Effect、Node HTTP Server 和项目自己的 HttpApi 路由，支持 HTTP、SSE 和 WebSocket。监听器支持端口回退、优雅关闭、活动连接强制关闭以及可选 mDNS 发布。默认情况下，mDNS 只在非回环主机上发布，避免把本机服务误广播到局域网。
对外事件分为两类：sessions.events({ sessionID, after }) 是可按序号重放的持久会话事件流；events.subscribe() 是当前实例级实时流，没有断线重放保证。客户端断线后不能假设自动恢复，应刷新权威状态，再根据最后一个持久序号显式重新订阅 Session 事件。
SDK 也在持续演进。仓库区分网络 Client、Effect Client、SDK-next 和 Embedded OpenCode：网络客户端通过 HTTP 访问服务，Embedded OpenCode 则在进程内复用 Server 路由、数据库和中间件，不打开监听端口，也不产生网络 I/O。创建 Embedded 实例后，关闭所属 Scope 会释放服务、数据库、注册和 fiber 资源。
这种设计适合构建自定义 IDE、代码审查服务、内部自动化和测试工具。需要注意的是 SDK Contract、Promise/Effect 两套生成器和公共 HttpApi 都在快速变化；如果直接依赖生成代码，应固定版本，并在升级时重新生成和验证类型。
MCP、插件与扩展生态
MCP 让 OpenCode 能够连接外部工具和数据源，例如文档搜索、数据库、工单系统和部署平台。插件则可以扩展 Provider、工具、命令、事件、认证和上下文来源。项目的插件系统包含依赖加载、配置读取、生命周期和热重载相关能力，目标是让 OpenCode 从一个固定功能的客户端变成可组合的 Agent 平台。
扩展越多，升级和审计成本越高。建议把插件分成开发期、团队共享和生产关键三类；为每类建立来源、版本、权限、网络域名和数据处理清单。尤其要避免让一个不可信插件同时拥有文件系统、Shell、网络和模型凭据权限。
安装方式
官方 README 提供安装脚本和多种包管理器方式。对于个人开发机，可以先使用 Homebrew、npm、Bun、pnpm 或 yarn；对于 Linux 和 Windows，也提供 Pacman、AUR、Scoop、Chocolatey、mise 与 Nix 方案。
# 推荐先查看脚本内容，再在受控环境执行
curl -fsSL https://opencode.ai/install -o /tmp/opencode-install
less /tmp/opencode-install
bash /tmp/opencode-install
# 或使用 npm
npm install --global opencode-ai@1.18.18
opencode --version
opencode --help安装脚本会按 OPENCODE_INSTALL_DIR、XDG_BIN_DIR、$HOME/bin、$HOME/.opencode/bin 的优先级选择目录。生产或团队环境建议固定具体版本，不直接使用 latest；升级前保留旧二进制、配置、插件清单和会话数据。
从源码构建
仓库使用 Bun 作为包管理器，根目录 package.json 标记的版本为 Bun 1.3.14。项目是多包工作区，包含 OpenCode 核心、Core、Protocol、Server、TUI、SDK、桌面端、Web 应用和控制台等包。构建前需要安装 Bun，并按仓库要求初始化依赖。
git clone --branch dev https://github.com/anomalyco/opencode.git
cd opencode
bun install
# 类型检查与核心构建
bun run typecheck
bun run --cwd packages/opencode build
# 本地运行 CLI
bun run --cwd packages/opencode dev -- --help项目文档要求在包目录执行类型检查和测试，不能从仓库根目录直接运行测试。仓库还包含 patched dependencies、原生 PTY、Tree-sitter、Electron 等依赖，跨平台构建前应准备编译工具，并在目标系统上验证终端、文件监听、PTY 和桌面打包。
典型使用流程
- 准备隔离分支：把待修改代码放在 Git 分支或可恢复工作区，确认没有未提交的敏感文件。
- 配置 Provider：使用环境变量、OpenCode 账户或项目配置添加模型凭据，先调用模型列表验证认证。
- 先用 plan：让只读 Agent 阅读目录、指令和测试，输出实现步骤与风险。
- 切换 build：逐项允许读取、编辑和测试工具，要求 Agent 说明每次修改的目的。
- 运行验证：执行项目已有的 lint、typecheck、unit test 和构建命令，审阅 Diff。
- 保存会话：利用 Session、Export 或 Git 提交保留决策、修改和测试证据。
如果任务需要外部文档或服务，先确认网络请求不会带出源代码、密钥或客户数据。对于自动修复和批量迁移，要设置文件范围、命令白名单和人工审批点。
配置与团队协作建议
OpenCode 的配置体系涵盖模型、Agent、权限、Provider、MCP、插件、命令和项目上下文。团队可以把稳定规则提交到仓库，把个人模型密钥放在本地配置或密钥管理器中，把不适合共享的实验功能放到用户级配置。
建议将以下内容写入团队约定：
- 允许 Agent 修改的目录和禁止访问的目录；
- 构建、测试、格式化和发布的标准命令；
- 哪些 Shell、网络、MCP 和插件操作必须人工确认；
- 模型提供商、数据驻留、日志保留和敏感信息脱敏要求；
- 会话导出、代码 Diff 和 Agent 生成内容的审查流程。
安全与隐私
模型会看到什么？
模型可能接收到用户请求、项目指令、打开的文件片段、搜索结果、工具输出、错误日志和动态上下文。不要把 API Key、云端凭据、生产数据库连接串、客户个人信息或私有证书放在模型可读目录中。即使 Provider 承诺不训练，网络传输、代理、插件和日志仍然是额外的数据处理环节。
Shell 和文件操作
Agent 可以生成危险命令，尤其是递归删除、权限修改、依赖安装、数据库迁移和发布脚本。使用 plan 做分析，用受限用户运行 build，确保工作区有 Git 快照，设置 CI 沙箱，并对高风险工具启用确认。不要在包含 SSH 私钥、云凭据或生产挂载目录的主机上直接运行未经审查的 Agent。
HTTP Server 和远程访问
OpenCode Server 适合在本机或受控网络中使用。若监听在非回环地址，应增加 TLS、身份认证、网络 ACL、速率限制和审计日志；不要因为服务支持 mDNS 或远程 Client，就把开发端口暴露到公网。远程 Server 还会把项目代码和工具权限集中到一台机器，必须按服务器安全标准管理。
插件与供应链
插件依赖会执行代码、读取配置并可能访问网络。固定版本、审查发布来源、运行依赖扫描、限制权限并保留回滚路径。升级 OpenCode 时同时检查 Bun lockfile、patched dependencies、Provider SDK 和桌面 Electron 组件的变更。
OpenCode 的优势
- 真正开源：MIT 许可证，核心运行时、工具、Server、TUI 和 SDK 都可审计。
- 多入口：CLI、TUI、Web、桌面和 SDK 共享同一套会话与服务能力。
- Provider 灵活：既能接主流厂商，也能连接 OpenAI-compatible、Bedrock 和自定义适配器。
- 工具完整：文件、Shell、LSP、Git、Web、任务和 MCP 组成较完整的开发闭环。
- 会话工程化：持久化、事件重放、上下文压缩、重试、导入导出和嵌入式运行时适合构建上层产品。
- 扩展能力强：Agent、插件、命令、技能、Provider 和上下文来源都可以定制。
局限与适用边界
OpenCode 的复杂度也很高。它不是一个“安装后永远不需要维护”的代码补全插件，而是一套快速迭代的 Agent 平台。Provider SDK、模型能力、MCP 协议、桌面打包和会话 Runtime 都会持续变化；大量依赖和多包工作区会增加升级、构建和排障成本。
如果你只想获得轻量级的单文件补全，OpenCode 的工具、权限和会话系统可能过于庞大。如果你的组织无法接受代码发送到第三方模型，仍需要自托管模型、私有 Provider 或严格的数据脱敏。如果要在 CI 中无人值守运行，应先设计沙箱、凭据隔离和可回滚交付链，而不是直接复用个人开发机权限。
适合谁使用？
OpenCode 适合希望审计 Agent 行为、连接多家模型、在终端和桌面之间切换，或基于 Agent Runtime 构建内部工具的开发者。它也适合研究会话持久化、工具权限、MCP、HTTP API、SDK 生成和多 Provider 抽象的工程团队。
对个人用户，建议从固定 Release、单个项目和 plan Agent 开始；对团队，建议统一版本、配置 Agent 权限、提交 AGENTS.md、建立插件白名单和审查模型数据流；对平台团队，可以进一步使用 Server、SDK 和 Embedded OpenCode 构建代码审查、自动修复或内部开发门户。
总结
OpenCode 的核心价值不是“替你写几行代码”，而是把模型、上下文、工具、权限、会话和交付组织成一个可恢复、可扩展的开发运行时。CLI/TUI 适合直接工作，桌面端提供更完整的交互，Server 与 SDK 让它能够进入 IDE、自动化和团队平台，多 Provider 与插件机制则保留了较大的选择空间。
使用它时应同时关注两件事：一是模型能力和工具编排能否真正提升开发效率，二是代码、凭据和 Shell 权限是否处于可控边界。固定版本、最小权限、隔离工作区、审查插件、保留 Git 回滚点，再逐步扩大自动化范围，才能把 OpenCode 的 Agent 能力转化为可靠的工程生产力。
