OpenCode 上手指南3 条命令跑通开源编程代理双 Agent 权限机制一次讲清【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode改了四个调用层才发现接口根本不该动——这种AI 一边读代码一边动手改结果越改越乱的处境正是 OpenCode 把代理拆成 plan 和 build 两个角色的原因先让只读的 plan 读完代码给出方案再由 build 接手执行。这是一套跑在终端里的开源 AI 编程代理这篇文章带你从 clone 到跑通并拆解它的权限与会话机制最后给出插件扩展的入口。OpenCode 解决的三件事OpenCode 的 npm 包名是opencode定位是终端优先的开源编码代理核心价值有三点跑在终端里不绑定任何编辑器bun dev起一个实例就能在任意项目目录里对话、改文件、跑命令。权限分离是默认行为内置 build全权限和 plan只读两个代理plan 默认拒绝文件编辑、执行 bash 前要向你确认相当于给想改代码的模型上了一把闸。模型与扩展点全部可换Anthropic、OpenAI 等各家模型通过 provider 层切换工具能力可以经插件和 MCP 两条路扩展不被锁死在单一供应商。5 分钟跑通本地开发环境从源码跑起来只需要 4 条命令git clone https://gitcode.com/GitHub_Trending/openc/opencode cd opencode bun install bun dev前提只有一个本机装有 Bun 1.3。首次启动时按提示选择模型供应商并登录即可对话。这里有个高频坑bun dev默认打开的是仓库内的packages/opencode目录你以为在操作自己的项目实际在改 OpenCode 的源码。想指向自己的项目显式传目录bun dev /path/to/your-project如果你只是日常使用而不打算改源码没必要走源码编译——仓库根目录 README 列了 brew、scoop、pacman、mise 等安装方式装一次长期可用源码流程留给要跑最新版或做二次开发的人。核心机制精讲它怎么防止 agent 把仓库改坏一句话结论权限是 agent 的一级字段读和写被拆成了两个默认角色。为什么这么设计给一个能写文件的模型整仓阅读权限等于让它在探索时随时可以动手出错成本很高。只读的 plan 代理可以放心地翻陌生代码库、产出改动方案确认方向后切到 build 执行误伤面小、可回退。两个角色共用 Tab 键切换成本几乎为零但把想清楚再动手固化成了工作流。源码看 packages/opencode/src/agent/每个 agent 的定义就是一段结构化数据——名字、权限规则集、可选的专用模型和专用 prompt。你完全可以在配置里声明自己的角色比如一个只许读特定目录的 reviewer而不需要改任何代码。会话状态为什么分两层存放一句话结论交互逻辑归opencode包持久化归core包两层解耦。为什么这么设计一轮对话涉及的东西很多——prompt 拼装、上下文压缩、失败重试、消息回滚。如果这些都直接贴着数据库写换存储方案或重放历史时会非常痛苦。OpenCode 把这一轮对话怎么跑放在 packages/opencode/src/session/里面有 compaction 压缩、retry 重试、revert 回滚等独立文件把状态如何落盘与投影放在 packages/core/src/session/store、projector、run-coordinator 负责把内存态写回 SQLite。这里有个设计值得借鉴compaction 不是简单的消息截断而是独立的压缩流程长会话的 token 超限问题在它身上是定期摘要而不是直接丢历史。会话越长越能体会到这个机制的价值。模型切换为什么几乎无感一句话结论provider 层统一了各家差异会话逻辑对具体是哪家模型无感。为什么这么设计不同供应商在工具调用格式、流式协议、错误语义上差异不小如果这些差异泄漏到会话层每加一家供应商都要动核心代码。OpenCode 把协议适配收敛在 packages/opencode/src/provider/ 与独立的 llm 包里会话层只面对统一的模型接口。对使用者的直接收益是换模型不用换工作流对想加私有网关的人这是一条清晰的扩展缝。 进阶给 agent 加一个私有工具插件系统入口在 packages/plugin/src/其中example.ts和example-workspace.ts是可以直接照抄的样例。理解插件机制最快的方式是看工具拿到的上下文类型它是从 tool.ts 里摘出来的export type ToolContext { sessionID: string messageID: string agent: string directory: string // 当前会话的项目目录 worktree: string // worktree 根生成相对路径用 abort: AbortSignal metadata(...): void // 上报标题等进度信息 ask(...): Promisevoid // 触发权限确认 }写工具时的两个要点返回值可以是纯字符串也可以是带 title 的结构任何可能碰文件系统的操作都该走ask请求授权——这样你的私有工具自动获得和内置工具一致的权限体验。另一条扩展路线是 MCPpackages/opencode/src/mcp/ 里有 OAuth、浏览器登录等现成实现接外部 AI 服务时优先复用。OpenCode vs Claude Code vs Cursor怎么选维度OpenCodeClaude CodeCursor形态终端优先开源可自托管终端闭源IDE 内嵌闭源权限模型build/plan 双代理规则集粒度单代理 命令白名单单一模型全有或全无模型多供应商自由切换绑定 Anthropic供应商受限判断直接给要开源、要换模型、工作在终端选 OpenCode深度 Anthropic 生态用户留在 Claude Code全天泡在编辑器里的人Cursor 的体验更顺。新手高频问题plan 代理想改文件却改不动这是设计行为它默认 deny 编辑跑 bash 也要确认。确认方案没问题后按 Tab 切到 build 再执行别去给 plan 开写权限。bun dev起来后操作的不是我项目默认落在packages/opencode目录用bun dev 你的目录或bun dev .显式指定。会话很长后模型开始失忆会话会走 compaction 压缩而非截断历史仍在本地 SQLite 里可以回看如果效果不对回滚机制revert按消息粒度工作。必须用 Bun 吗源码开发流程要求 Bun 1.3只当工具用的话按仓库 README 的包管理器方式安装发布版即可不依赖本地 Bun。收尾OpenCode 的核心可取之处是把权限和会话做成了两个可独立演进的模块而不是揉在一段 agent 循环里。下一步建议想弄懂会话如何变成模型调用先读 packages/opencode/src/session/ 里的 processor 与 compaction想动手扩展直接抄 packages/plugin/src/ 的 example.ts 写第一个工具。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/8 23:56:49 · 阅读 1.2k OpenCode 上手指南：3 条命令跑通开源编程代理，双 Agent 权限机制一次讲清
OpenCode 上手指南3 条命令跑通开源编程代理双 Agent 权限机制一次讲清【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode改了四个调用层才发现接口根本不该动——这种AI 一边读代码一边动手改结果越改越乱的处境正是 OpenCode 把代理拆成 plan 和 build 两个角色的原因先让只读的 plan 读完代码给出方案再由 build 接手执行。这是一套跑在终端里的开源 AI 编程代理这篇文章带你从 clone 到跑通并拆解它的权限与会话机制最后给出插件扩展的入口。OpenCode 解决的三件事OpenCode 的 npm 包名是opencode定位是终端优先的开源编码代理核心价值有三点跑在终端里不绑定任何编辑器bun dev起一个实例就能在任意项目目录里对话、改文件、跑命令。权限分离是默认行为内置 build全权限和 plan只读两个代理plan 默认拒绝文件编辑、执行 bash 前要向你确认相当于给想改代码的模型上了一把闸。模型与扩展点全部可换Anthropic、OpenAI 等各家模型通过 provider 层切换工具能力可以经插件和 MCP 两条路扩展不被锁死在单一供应商。5 分钟跑通本地开发环境从源码跑起来只需要 4 条命令git clone https://gitcode.com/GitHub_Trending/openc/opencode cd opencode bun install bun dev前提只有一个本机装有 Bun 1.3。首次启动时按提示选择模型供应商并登录即可对话。这里有个高频坑bun dev默认打开的是仓库内的packages/opencode目录你以为在操作自己的项目实际在改 OpenCode 的源码。想指向自己的项目显式传目录bun dev /path/to/your-project如果你只是日常使用而不打算改源码没必要走源码编译——仓库根目录 README 列了 brew、scoop、pacman、mise 等安装方式装一次长期可用源码流程留给要跑最新版或做二次开发的人。核心机制精讲它怎么防止 agent 把仓库改坏一句话结论权限是 agent 的一级字段读和写被拆成了两个默认角色。为什么这么设计给一个能写文件的模型整仓阅读权限等于让它在探索时随时可以动手出错成本很高。只读的 plan 代理可以放心地翻陌生代码库、产出改动方案确认方向后切到 build 执行误伤面小、可回退。两个角色共用 Tab 键切换成本几乎为零但把想清楚再动手固化成了工作流。源码看 packages/opencode/src/agent/每个 agent 的定义就是一段结构化数据——名字、权限规则集、可选的专用模型和专用 prompt。你完全可以在配置里声明自己的角色比如一个只许读特定目录的 reviewer而不需要改任何代码。会话状态为什么分两层存放一句话结论交互逻辑归opencode包持久化归core包两层解耦。为什么这么设计一轮对话涉及的东西很多——prompt 拼装、上下文压缩、失败重试、消息回滚。如果这些都直接贴着数据库写换存储方案或重放历史时会非常痛苦。OpenCode 把这一轮对话怎么跑放在 packages/opencode/src/session/里面有 compaction 压缩、retry 重试、revert 回滚等独立文件把状态如何落盘与投影放在 packages/core/src/session/store、projector、run-coordinator 负责把内存态写回 SQLite。这里有个设计值得借鉴compaction 不是简单的消息截断而是独立的压缩流程长会话的 token 超限问题在它身上是定期摘要而不是直接丢历史。会话越长越能体会到这个机制的价值。模型切换为什么几乎无感一句话结论provider 层统一了各家差异会话逻辑对具体是哪家模型无感。为什么这么设计不同供应商在工具调用格式、流式协议、错误语义上差异不小如果这些差异泄漏到会话层每加一家供应商都要动核心代码。OpenCode 把协议适配收敛在 packages/opencode/src/provider/ 与独立的 llm 包里会话层只面对统一的模型接口。对使用者的直接收益是换模型不用换工作流对想加私有网关的人这是一条清晰的扩展缝。 进阶给 agent 加一个私有工具插件系统入口在 packages/plugin/src/其中example.ts和example-workspace.ts是可以直接照抄的样例。理解插件机制最快的方式是看工具拿到的上下文类型它是从 tool.ts 里摘出来的export type ToolContext { sessionID: string messageID: string agent: string directory: string // 当前会话的项目目录 worktree: string // worktree 根生成相对路径用 abort: AbortSignal metadata(...): void // 上报标题等进度信息 ask(...): Promisevoid // 触发权限确认 }写工具时的两个要点返回值可以是纯字符串也可以是带 title 的结构任何可能碰文件系统的操作都该走ask请求授权——这样你的私有工具自动获得和内置工具一致的权限体验。另一条扩展路线是 MCPpackages/opencode/src/mcp/ 里有 OAuth、浏览器登录等现成实现接外部 AI 服务时优先复用。OpenCode vs Claude Code vs Cursor怎么选维度OpenCodeClaude CodeCursor形态终端优先开源可自托管终端闭源IDE 内嵌闭源权限模型build/plan 双代理规则集粒度单代理 命令白名单单一模型全有或全无模型多供应商自由切换绑定 Anthropic供应商受限判断直接给要开源、要换模型、工作在终端选 OpenCode深度 Anthropic 生态用户留在 Claude Code全天泡在编辑器里的人Cursor 的体验更顺。新手高频问题plan 代理想改文件却改不动这是设计行为它默认 deny 编辑跑 bash 也要确认。确认方案没问题后按 Tab 切到 build 再执行别去给 plan 开写权限。bun dev起来后操作的不是我项目默认落在packages/opencode目录用bun dev 你的目录或bun dev .显式指定。会话很长后模型开始失忆会话会走 compaction 压缩而非截断历史仍在本地 SQLite 里可以回看如果效果不对回滚机制revert按消息粒度工作。必须用 Bun 吗源码开发流程要求 Bun 1.3只当工具用的话按仓库 README 的包管理器方式安装发布版即可不依赖本地 Bun。收尾OpenCode 的核心可取之处是把权限和会话做成了两个可独立演进的模块而不是揉在一段 agent 循环里。下一步建议想弄懂会话如何变成模型调用先读 packages/opencode/src/session/ 里的 processor 与 compaction想动手扩展直接抄 packages/plugin/src/ 的 example.ts 写第一个工具。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考