OpenCode：开源 Coding Agent 与可嵌入式 Agent Harness

1. OpenCode 到底是什么？

可以把 OpenCode 理解为三个层次：

OpenCode
├── Coding Agent 产品
│   ├── TUI / CLI
│   ├── Desktop
│   └── Web UI
│
├── Agent Harness
│   ├── Agent Loop
│   ├── Session
│   ├── Tool Calling
│   ├── Context 管理
│   ├── Subagent
│   ├── Skills
│   ├── Permissions
│   └── MCP
│
└── 可嵌入服务
    ├── opencode serve
    ├── HTTP API
    ├── OpenAPI
    ├── SSE 实时事件
    └── TypeScript SDK

因此，OpenCode 主要有两种使用方式：

作为 Coding Agent，供开发者直接使用。
作为 Agent Harness，嵌入其他产品。

2. 作为 Coding Agent 直接使用

进入项目目录运行 OpenCode，然后用自然语言描述任务：

分析这个项目
修复登录接口问题
运行测试
重构数据库访问层

OpenCode 通常会按照以下流程工作：

检查项目结构和相关文件。
搜索与任务有关的代码。
制定或维护任务计划。
修改代码和配置文件。
执行命令、测试或类型检查。
根据运行结果继续分析和修复。
汇总修改内容与最终结果。

这种体验与 Claude Code、Codex CLI 等终端 Coding Agent 类似。

3. 作为 Agent Harness 后端使用

OpenCode 也可以作为无头服务运行：

opencode serve

其他应用可以通过 HTTP API 或 SDK：

创建和管理 Session
发送 Prompt
订阅 SSE 实时事件
获取消息和流式文本
获取 Tool Call 与 Tool Result
响应权限审批请求
获取 Todo 或执行计划
读取 Agent 运行状态

例如，OpenWork 就采用了类似的架构：OpenWork 负责桌面端 UI 和产品体验，OpenCode 负责底层 Agent 执行。

OpenWork Desktop
       │
       ▼
OpenWork Server
       │
       ▼
OpenCode Server
       │
       ├── Agent Loop
       ├── Model Provider
       ├── Tools
       ├── Permissions
       ├── Skills
       └── MCP

4. OpenCode 的核心能力

4.1 Agent Loop

Agent Loop 是 OpenCode 作为 Agent Harness 的核心。

用户请求
   ↓
构造模型上下文
   ↓
调用模型
   ↓
模型返回文本或 Tool Call
   ↓
检查操作权限
   ↓
执行工具
   ↓
将 Tool Result 返回模型
   ↓
继续循环，直到任务完成

OpenCode 不只是调用一次模型，而是持续协调模型、工具、上下文和权限，直到任务完成或需要用户介入。

4.2 内置工具

OpenCode 提供了开发任务常用的工具，例如：

Read
Write
Edit
Apply Patch
Glob
Grep
List
Bash / Shell
LSP
Web Fetch
Web Search
Todo
Question
Skill
Task / Subagent

模型不会直接操作文件或系统，而是生成结构化的 Tool Call，再由 OpenCode 执行并返回结果。

4.3 权限控制

OpenCode 可以为不同操作配置三种权限策略：

allow：直接执行
ask：执行前请求用户批准
deny：禁止执行

例如：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git push *": "deny",
      "rm *": "deny"
    }
  }
}

权限可以按多个维度细分：

Tool
文件路径
Shell 命令
Agent
Skill
MCP Tool
外部目录

详情参见 OpenCode 权限文档。

OpenCode 的默认权限相对宽松，多数操作默认允许，外部目录访问、重复工具循环等操作才会默认询问。将其用于生产环境时，建议显式配置权限策略，不要完全依赖默认值。

4.4 Primary Agent 与 Subagent

OpenCode 支持两类 Agent。

Primary Agent

Primary Agent 是与用户直接交互的主 Agent，例如：

Build
Plan

Subagent

Subagent 是由主 Agent 调用的专用 Agent，例如：

Explore：搜索和分析代码
General：执行通用子任务
Reviewer：审查代码修改
Security Auditor：检查安全问题

典型协作流程如下：

Build Agent
├── 调用 Explore Agent 搜索相关代码
├── 调用 Reviewer 检查修改
└── 汇总结果并完成最终实现

每个 Agent 都可以独立配置：

System Prompt
Model
Temperature
最大执行步骤数
Tool 权限
Skill 权限
是否允许启动其他 Agent

详情参见 OpenCode Agent 文档。

4.5 Skills

OpenCode 支持标准的 SKILL.md，并可以从多个目录发现 Skill：

.opencode/skills/git-release/SKILL.md
.claude/skills/git-release/SKILL.md
.agents/skills/git-release/SKILL.md

OpenCode 不会一开始就把所有 Skill 的完整内容放入上下文。它会先向模型提供 Skill 的名称和描述，等模型判断需要使用时，再通过 skill 工具加载完整内容。

发现 Skill
   ↓
向模型提供名称和描述
   ↓
模型判断是否需要
   ↓
skill({ name: "git-release" })
   ↓
加载完整 SKILL.md

这种按需加载机制可以减少上下文占用，避免大量无关 Skill 内容干扰模型。

详情参见 OpenCode Skills 文档。

4.6 MCP

OpenCode 可以连接本地或远程 MCP Server，从而让 Agent 使用更多外部能力，例如：

GitHub
数据库
浏览器
文件服务
企业内部 API
SaaS Connector

本地 MCP Server 配置示例：

{
  "mcp": {
    "servers": {
      "my-server": {
        "type": "local",
        "command": ["npx", "-y", "example-mcp-server"]
      }
    }
  }
}

通过 MCP 接入的工具同样受 OpenCode 权限系统控制。

详情参见 OpenCode MCP 文档。

4.7 多模型 Provider

OpenCode 不绑定某一个模型或模型厂商。它可以接入不同 Provider，并统一处理：

流式响应
Tool Calling
模型名称与配置
Token 使用统计
Provider 鉴权
模型能力差异

这意味着上层 Agent、工具系统和产品 UI 不需要直接处理每个模型厂商的接口差异。

4.8 Server、OpenAPI 与 SDK

运行以下命令后，OpenCode 会启动无头 HTTP Server：

opencode serve

服务会暴露 OpenAPI 接口，客户端可以通过 HTTP API 或 TypeScript SDK 与其通信。

详情参见 OpenCode Server 文档。

实时执行过程通常通过 SSE 传递：

客户端 UI
   │
   ├── 创建 Session
   ├── 发送 Prompt
   └── 订阅 SSE
          │
          ├── 文本增量
          ├── Tool Call
          ├── Permission Request
          ├── Tool Result
          └── Session 状态变化

因此，OpenCode 可以作为以下产品的底层 Agent Engine：

桌面应用
Web Agent
IDE 插件
CI 自动化 Agent
远程 Worker
企业内部开发平台
其他 AI 产品的 Harness 后端

5. OpenCode 与 OpenWork 的区别

OpenCode 和 OpenWork 容易混淆，但它们的定位并不相同。

维度	OpenCode	OpenWork
产品定位	Coding Agent 与 Agent Harness	桌面 Cowork 产品
核心职责	执行模型循环	提供用户体验
Tool Call	调度和执行工具	展示工具调用时间线
Session	创建并管理 Session	提供 Session 管理界面
Permissions	生成并处理权限请求	提供用户审批窗口
Skills / MCP	发现、加载和调用	提供配置与管理界面
独立使用	可以独立运行	主要复用 OpenCode 能力

可以用一个简单的比喻来理解：

OpenCode ≈ 发动机
OpenWork ≈ 使用这台发动机制造的整车

不过，OpenCode 自身也提供 TUI、Desktop 和 Web UI，因此它既可以作为底层基础设施，也可以直接作为完整的 Coding Agent 产品使用。

6. 一句话总结

OpenCode 是一个完整的开源 Coding Agent 和可嵌入式 Agent Harness。它负责让模型理解代码仓库、调用文件与 Shell 工具、管理上下文和权限、使用 Skills 与 MCP、启动 Subagent，并通过 Session、Server、SDK 和事件流将这些能力提供给终端、桌面端、Web 应用和第三方产品。

OpenWork 则展示了另一种可能：如何基于 OpenCode 的底层能力，构建一个面向普通用户的 Cowork 桌面产品。