企业官网建设流程全解析

OpenCode 上手指南：3 步跑通你的第一个 AI 编程代理

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

OpenCode 是一个开源的 AI 编程代理，跑在终端里：接入你常用的大模型，让代理读代码库、改文件、执行命令，把多步骤的编码任务自动做完。这篇指南面向刚接触 AI 代码生成工具的开发者，从安装到调优，几分钟讲完。

项目速览

简单说：OpenCode 把"大模型 + 终端 + 文件系统"拼成了一个能干活的编程代理。它不只是问答，而是能真正在你的仓库里执行 edit、bash 等工具操作，并保留完整会话记录。

快速上手

方式一：装现成的（推荐普通用户）

npm i -g opencode-ai@latest 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_DIR>XDG_BIN_DIR>~/bin>~/.opencode/bin。团队机器统一用OPENCODE_INSTALL_DIR=/usr/local/bin安装即可。
• 需要无界面调用时，用opencode serve起 HTTP 服务，配合仓库里 packages/sdk/js/ 的 JS SDK 做二次开发。
• 部署形态见 packages/containers/ 下的多阶段 Dockerfile（base、bun-node、rust、tauri-linux），生产环境按平台选基础镜像构建即可。

避坑与常见问题

1. 现象：装完提示opencode: command not found。→原因：默认安装目录~/.opencode/bin不在 PATH。→怎么办：把该目录加进 PATH，或用OPENCODE_INSTALL_DIR装到已有 PATH 的目录。
2. 现象：在仓库根目录跑bun test直接退出。→原因：根 package.json 故意把 test 脚本设为拒绝执行（多包 monorepo，测试要分包跑）。→怎么办：进到具体包目录（如packages/core）再跑bun test。
3. 现象：让模型改文件却只收到"需要权限"的提示。→原因：当前在plan只读代理下。→怎么办：按 Tab 切回build，或在配置里调整权限策略。
4. 现象：长会话后模型明显变慢、开始"忘事"。→原因：上下文接近模型窗口上限。→怎么办：让会话触发自动压缩，或另开新会话只带关键结论。
5. 现象：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