OpenCode 上手指南3 步跑通你的第一个 AI 编程代理【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencodeOpenCode 是一个开源的 AI 编程代理跑在终端里接入你常用的大模型让代理读代码库、改文件、执行命令把多步骤的编码任务自动做完。这篇指南面向刚接触 AI 代码生成工具的开发者从安装到调优几分钟讲完。项目速览简单说OpenCode 把大模型 终端 文件系统拼成了一个能干活的编程代理。它不只是问答而是能真正在你的仓库里执行 edit、bash 等工具操作并保留完整会话记录。维度OpenCode典型聊天式代码补全运行形态终端 TUI Web 桌面端编辑器内嵌模型任意提供商随时切换通常绑定单一模型会话本地持久化可回看可续写多为临时上下文快速上手方式一装现成的推荐普通用户npm i -g opencode-ailatest opencode auth login # 登录并配置模型提供商凭据 opencode # 在项目目录里启动方式二从源码跑想读代码或改行为时用git clone https://gitcode.com/GitHub_Trending/openc/opencode cd opencode bun install bun run dev常见报错点bun run dev之前没执行bun install或者 Bun 版本过旧仓库锁定了 bun 1.3.14见根目录 package.json 的packageManager字段都会让postinstall阶段的 node-pty 修复脚本报错。先升级 Bun 再装。核心能力拆解build 与 plan按 Tab 切换的两种代理OpenCode 内置两个代理Tab 键随时切换build是默认的全权限开发代理plan是只读代理——默认拒绝改文件、跑命令前要先征求同意。场景接手一个陌生仓库先切到plan让它把架构摸一遍确认思路后切回build动手改。此外还有内部的general子代理消息里写general可触发复杂多步检索。代理的提示词与权限逻辑在 packages/opencode/src/agent/。会话管理历史不是聊天记录是可续写的工作状态会话的存储、消息更新、上下文压缩都集中在 packages/core/src/session/store.ts管持久化projector.ts做状态投影compaction.ts负责长会话压缩。场景一个调试任务聊了几十轮上下文越滚越长、响应变慢——压缩机制会主动收拢历史而不是让你从头再来。插件与 MCP给代理加新的手插件接口在 packages/plugin/src/核心是tool.ts——你可以注册自己的工具函数让模型像调用内置工具一样调用它。同时 packages/opencode/src/mcp/ 实现了 MCP 集成能挂上外部工具服务器含 OAuth 流程。场景写一个deploy插件工具对话里直接说部署到 staging模型就会按你定义的执行路径去调用。进阶与调优配置文件放在~/.config/opencode/下如opencode.json项目根目录的配置文件优先级更高可针对单个仓库覆盖模型和权限。安装目录由环境变量控制优先级为OPENCODE_INSTALL_DIRXDG_BIN_DIR~/bin~/.opencode/bin。团队机器统一用OPENCODE_INSTALL_DIR/usr/local/bin安装即可。需要无界面调用时用opencode serve起 HTTP 服务配合仓库里 packages/sdk/js/ 的 JS SDK 做二次开发。部署形态见 packages/containers/ 下的多阶段 Dockerfilebase、bun-node、rust、tauri-linux生产环境按平台选基础镜像构建即可。避坑与常见问题现象装完提示opencode: command not found。→原因默认安装目录~/.opencode/bin不在 PATH。→怎么办把该目录加进 PATH或用OPENCODE_INSTALL_DIR装到已有 PATH 的目录。现象在仓库根目录跑bun test直接退出。→原因根 package.json 故意把 test 脚本设为拒绝执行多包 monorepo测试要分包跑。→怎么办进到具体包目录如packages/core再跑bun test。现象让模型改文件却只收到需要权限的提示。→原因当前在plan只读代理下。→怎么办按 Tab 切回build或在配置里调整权限策略。现象长会话后模型明显变慢、开始忘事。→原因上下文接近模型窗口上限。→怎么办让会话触发自动压缩或另开新会话只带关键结论。现象bun install在 postinstall 卡住或失败。→原因node-pty 需要原生编译系统缺工具链或 Bun 过旧。→怎么办升级到与仓库一致的 Bun 版本1.3.x补齐编译依赖后重装。写在最后更完整的配置项和文档在 packages/docs/想深入某个子系统直接看对应的包目录就行——这个仓库本身就是一个多包 monorepo 的好样本。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考