★ FEATURED ARTICLE 1. 为什么要在本地跑一个 OpenCode Agent如果你最近在折腾 AI 编码工具大概率会遇到一个尴尬网页版聊得挺热闹真让它改你项目里的文件它就开始装傻。原因很简单网页端拿不到你的本地文件系统也执行不了 shell 命令只能靠你复制粘贴。而 OpenCode 这类终端原生 Agent 解决的就是这个问题——它直接跑在你的终端里能读文件、写文件、执行命令、操作 Git把「聊天」变成「干活」。OpenCode 是一个开源MIT 协议的终端优先编码 Agent定位是模型无关你可以接云端大模型也可以接本地 Ollama。它的核心设计是 Plan / Build 双模式Plan 阶段先出方案让你确认Build 阶段才真正动文件这个设计对新手特别友好能有效防止它一上来就把你的代码改乱。适合谁适合想快速跑通本地 Agent 工作流的开发者、习惯 Vim/终端的同学以及在意代码隐私、希望数据不出本机的人。这篇不聊虚的直接给你一条可复现的路径装好 OpenCode、配好模型、跑一个真实任务、再用日志验证 Agent 的行为到底符不符合预期。全程命令可复制踩坑点我也会标出来。2. 前置准备TaoToken 接入与 OpenCode 安装先说模型接入这块。OpenCode 本身不带模型它需要一个兼容 OpenAI 接口的 API 端点。我这边用的是 TaoToken 提供的统一接入好处是一个 Key 能切多个模型省得为每个模型单独配环境变量。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意这个不加 UTM 参数配置里填这个就行。你需要先去控制台建一个 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 建完复制出来后面配置要用。Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建议单独建一个给 OpenCode 用方便随时吊销。然后是 OpenCode 本体。官方给了安装脚本Linux/macOS/WSL 都能用curl -fsSL https://get.opencode.dev | bash装完验证一下版本opencode --version如果提示 command not found多半是~/.local/bin或~/.opencode/bin没进 PATH手动加一下export PATH$HOME/.local/bin:$HOME/.opencode/bin:$PATH想持久化就写进~/.bashrc或~/.zshrc。这一步看着简单但 90% 的新手卡在「装完找不到命令」先解决它再往下走。3. 可复制配置settings.json 与模型参数OpenCode 的配置分两层全局配置和项目级配置。全局配置一般放在~/.config/opencode/config.json项目级放在项目根目录的opencode.json。我建议先配全局把模型端点定下来。下面是一份可直接复制的~/.config/opencode/config.json注意把sk-xxxx换成你自己的 Key{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-xxxx }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5 }这里三个关键字段必须对齐Base URL 填https://taotoken.net/apiKey 填你刚建的Model ID 填taotoken/claude-sonnet-4-5这种「provider/model」格式。这三件套Base URL Key Model ID是任何 OpenAI 兼容接入的通用套路配错任何一个都会报错。如果你更习惯用环境变量而不是写死在 JSON 里可以这样export TAOTOKEN_API_KEYsk-xxxx然后把 JSON 里的apiKey改成{env:TAOTOKEN_API_KEY}。这样 Key 不进版本库团队协作时更安全。配完跑一下opencode进交互界面输入/models看看能不能列出你配的模型。列不出来就是 JSON 格式错了用jq . ~/.config/opencode/config.json校验一下。4. 验证请求跑一个真实任务看结果配置对不对跑个任务就知道。我拿一个真实场景演示让 OpenCode 分析当前目录的代码结构并生成一份 README 草稿。先建个测试目录mkdir -p ~/opencode-demo cd ~/opencode-demo git init echo def add(a, b): return a b calc.py然后启动 OpenCodeopencode进去之后先按 Tab 切到 Plan 模式界面底部会显示当前模式输入分析当前目录的代码说明每个文件的作用然后给出一个 README.md 的草稿先不要写文件。Plan 模式下它只会输出方案不会动文件。你会看到它调用file_reader读了calc.py然后给出分析。确认方案没问题后按 Tab 切到 Build 模式输入按刚才的方案生成 README.md这时候它会调用file_writer真正写文件。跑完ls一下应该能看到README.md出现了。验证 Agent 行为是否符合预期关键看两个地方一是它调用了哪些工具二是工具调用的参数对不对。OpenCode 在交互界面会实时打印工具调用比如→ file_reader(pathcalc.py)。如果它没读文件就直接编内容说明模型没走工具调用多半是模型不支持 function calling换个模型试试。想看更详细的日志启动时加--log-level debugopencode --log-level debug日志会打到 stderr你可以重定向到文件慢慢看opencode --log-level debug 2 opencode.log日志里搜tool_call和tool_result能看到每次工具调用的完整入参和返回。这是排查「Agent 为什么没按我想的做」最直接的手段。5. 常见报错排查401、local proxy failed 与 OAuth配 Agent 最烦的就是报错我把几个高频错误和对应动作列一下。401 UnauthorizedKey 错了或者没带上。先确认config.json里apiKey字段没写错再确认 Base URL 是https://taotoken.net/api而不是带路径的完整地址。如果用的是环境变量echo $TAOTOKEN_API_KEY看看是不是空的。还有一种情况是 Key 被吊销了去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新建一个。local proxy failed / connection refusedOpenCode 连不上端点。先curl -I https://taotoken.net/api看网络通不通。如果通检查是不是本地配了什么代理环境变量HTTP_PROXY/HTTPS_PROXY把请求劫持了临时unset掉再试。reading choices 报错 / 返回结构不对这类错误通常是模型返回的 JSON 不符合 OpenAI 格式或者你用的模型 ID 在 TaoToken 那边不存在。去 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 核对一下模型 ID 拼写别自己造名字。OAuth 相关报错如果你之前配过 Claude Code 或 Codex 的 OAuth 登录OpenCode 可能会去读那些凭证文件导致冲突。检查~/.config/opencode/下有没有残留的 auth 文件有就备份后删掉让它走纯 API Key 模式。工具调用不触发模型不支持 function calling或者你在 Plan 模式下让它写文件。前者换模型后者按 Tab 切 Build。排查顺序建议先看 HTTP 状态码401/403/404 是配置问题5xx 是服务端问题再看日志里的tool_call有没有出现最后看模型返回内容是不是符合预期。三步走下来基本能定位到具体环节。6. 长期编码与 Agent 工作流的下一步跑通单次任务只是起点。真正让 OpenCode 发挥价值的是把它嵌进日常编码流比如让它在你 commit 前自动跑一遍 lint、分析 diff、生成 commit message或者配一个自定义 Skill让它定期扫项目里的 TODO 并汇总成 issue 草稿。如果你打算长期用 Agent 做编码建议上 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频编码场景做了额度优化比按量付费划算。想先试试模型对话效果可以去 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 直接聊两句确认模型能力再决定接哪个。最后给个实用技巧把 OpenCode 的项目级配置opencode.json提交进仓库团队里每个人 clone 下来就能用同一套模型和 Skill 配置省得每人配一遍。配置里别写 Key用环境变量引用这样既统一又安全。
阅读完成 · 觉得有帮助？
