1. 为什么值得花时间整理 OpenCode 的命令体系刚接触 OpenCode 的人十有八九会经历这么一个阶段装好了界面也打开了然后对着屏幕发呆——这玩意儿到底怎么用菜单栏翻一遍没找到几个能点的按钮想跑个任务不知道从哪下手看别人演示时噼里啪啦敲几个键就完成了一堆操作自己却连 Leader 键是什么都没搞明白。这不是你的问题。OpenCode 这类终端优先的 AI 编程工具设计哲学就是键盘驱动——它把绝大多数能力藏在命令和快捷键里而不是摆在界面上。你看到的极简界面其实是把复杂度转移到了命令层。这意味着命令和快捷键的熟练度直接决定了你用 OpenCode 的效率上限。我用了大半年 OpenCode从最开始每次操作都要翻文档到现在基本可以盲操中间踩了不少坑。这篇文章就是把我积累的常用命令、快捷键、Agent 调度技巧、配置要点全部整理出来按使用场景分类配上我自己的实操心得。不管你是刚装好 OpenCode 的新手还是已经用了一段时间但总觉得效率上不去的老用户应该都能从里面找到有用的东西。文章会覆盖这几个方面基础命令与启动参数、Leader 键与核心快捷键体系、Agent 的调用与管理、Skill 机制的使用、常见报错排查、以及一些我摸索出来的效率技巧。每个部分都会说清楚为什么这么设计和实际怎么用而不是干巴巴地列一张表。2. OpenCode 基础命令与启动参数详解2.1 安装后的第一组命令确认环境与版本装完 OpenCode 之后别急着跑任务先花两分钟确认环境状态。这一步很多人会跳过结果后面遇到问题排查半天最后发现是版本不对或者依赖缺失。# 查看当前版本 opencode --version # 查看完整帮助信息 opencode --help # 查看特定子命令的帮助 opencode subcommand --help--version看起来简单但它能帮你快速判断当前装的是哪个版本。OpenCode 迭代很快不同版本之间命令行为可能有差异遇到问题时第一件事就是确认版本。--help输出的内容比较长建议配合less或者重定向到文件慢慢看opencode --help | less opencode --help opencode-help.txt我个人的习惯是把帮助信息存一份到本地遇到不确定的命令时直接搜文件比每次敲--help快得多。2.2 启动参数不同场景用不同姿势OpenCode 的启动参数决定了它进入什么模式、加载什么配置、连接什么模型。常用的启动方式有这么几种# 默认启动进入交互式界面 opencode # 指定工作目录启动 opencode --cwd /path/to/project # 以非交互模式执行单次任务 opencode run 帮我重构这个函数 # 指定配置文件 opencode --config /path/to/config.json # 查看当前生效的配置 opencode config list--cwd这个参数值得单独说一下。OpenCode 默认以当前目录作为工作区但很多时候你是在一个父目录下操作想让它聚焦到某个子项目。这时候用--cwd比先cd过去再启动更清晰尤其是你在脚本里调用的时候。run子命令是自动化场景的关键。它让 OpenCode 执行一次任务然后退出不进入交互界面。你可以把它嵌到 shell 脚本或者 CI 流程里# 在脚本中调用把结果输出到文件 opencode run 检查这个目录下所有 Python 文件的语法错误 result.txt 21注意run模式下 OpenCode 不会等待你确认它会直接执行。所以任务描述要尽量明确避免它做出你意料之外的操作。我一般会先在交互模式里试一遍确认行为符合预期后再写成run命令。2.3 配置管理命令让 OpenCode 记住你的偏好OpenCode 的配置分几个层级全局配置、项目级配置、会话级配置。理解这个层级关系很重要因为它决定了你的设置什么时候生效、什么时候被覆盖。# 查看所有配置项 opencode config list # 获取某个配置项的值 opencode config get model # 设置配置项 opencode config set model claude-sonnet-4-20250514 # 删除配置项 opencode config unset model # 查看配置文件位置 opencode config path配置的优先级从高到低是命令行参数 项目级配置 全局配置。也就是说如果你在项目根目录放了一个.opencode/config.json它会覆盖全局设置。这个机制在团队协作时特别有用——你可以把项目相关的模型选择、Skill 配置提交到仓库让所有成员用同一套设置。我踩过的一个坑早期我把 API 相关的配置写在了项目级配置文件里结果提交代码时差点把密钥一起提交上去。后来学乖了敏感信息一律走环境变量项目级配置只放非敏感的项目相关设置。# 推荐做法敏感信息用环境变量 export OPENCODE_API_KEYyour-key-here # 项目级配置只放这类内容 { model: claude-sonnet-4-20250514, skills: [./skills/project-specific] }2.4 会话管理别让上下文丢了OpenCode 的会话机制是它区别于普通命令行工具的一个重要特性。每次交互都会产生上下文这些上下文可以保存、恢复、归档。# 列出所有会话 opencode session list # 恢复指定会话 opencode session resume session-id # 归档当前会话 opencode session archive # 查看归档的会话 opencode session list --archived会话归档后去哪了这是热词里出现频率很高的问题。归档的会话默认存在~/.opencode/sessions/archive/目录下以 JSON 格式保存。你可以直接查看这些文件也可以用session resume恢复。如果磁盘空间紧张可以定期清理旧的归档会话# 查看归档会话占用的空间 du -sh ~/.opencode/sessions/archive/ # 清理 30 天前的归档 find ~/.opencode/sessions/archive/ -mtime 30 -delete实操心得我习惯在完成一个阶段性任务后手动归档会话而不是让它一直挂着。这样下次session list的时候列表干净找起来快。归档不等于删除需要的时候随时能恢复。3. Leader 键与核心快捷键体系拆解3.1 Leader 键是什么为什么需要它如果你用过 Vim、Tmux 或者 Emacs对 Leader 键的概念应该不陌生。简单说Leader 键就是一个前缀键——你先按它再按其他键组合成一个命令。这样做的好处是避免快捷键冲突同时让快捷键体系可以无限扩展。OpenCode 默认的 Leader 键是Ctrlx。你可以把它理解成进入命令模式的开关。按下Ctrlx之后OpenCode 会等待你输入下一个键根据这个键来决定执行什么操作。为什么不用单个键或者Ctrl字母的组合因为终端环境下很多组合键已经被系统或者终端模拟器占用了。用 Leader 键做前缀相当于开辟了一个独立的命名空间不会跟其他软件打架。你可以自定义 Leader 键{ keybinds: { leader: ctrlspace } }我试过改成Ctrlspace但发现跟输入法切换冲突最后还是用回了默认的Ctrlx。如果你用的是 macOSCtrlx跟系统快捷键冲突的概率很低建议保持默认。3.2 最常用的 Leader 组合键下面这些是我日常使用频率最高的 Leader 组合按使用场景分组会话与上下文管理快捷键功能使用场景Ctrlx n新建会话开始一个独立任务时Ctrlx l列出会话需要切换回之前的任务Ctrlx a归档当前会话任务完成后清理Ctrlx r重命名会话给会话起个有意义的名字Agent 与模型切换快捷键功能使用场景Ctrlx m切换模型不同任务用不同模型Ctrlx g切换 Agent在通用 Agent 和专用 Agent 之间切换Ctrlx s查看当前状态确认当前用的是哪个模型和 Agent编辑与操作快捷键功能使用场景Ctrlx e打开外部编辑器需要写长文本时Ctrlx c复制最后一条回复快速取用输出内容Ctrlx u撤销上一步操作误操作后回退视图控制快捷键功能使用场景Ctrlx v切换详细/简洁视图根据屏幕空间调整Ctrlx t切换主题光线环境变化时Ctrlx ?显示快捷键帮助忘记某个组合时这张表建议截图存手机里前两周对着用慢慢就形成肌肉记忆了。我刚开始的时候把最常用的五六个写在便签上贴在显示器边框一周之后就基本不用看了。3.3 非 Leader 快捷键日常操作的高频键除了 Leader 组合还有一些不需要前缀的直接快捷键这些是日常操作中使用频率最高的Enter 发送消息 ShiftEnter 换行不发送 CtrlC 中断当前操作 CtrlD 退出 OpenCode CtrlL 清屏 CtrlR 搜索历史消息 Tab 自动补全 上/下箭头 浏览历史输入CtrlC和CtrlD这两个要特别说一下。CtrlC是中断当前正在执行的操作比如 Agent 正在跑一个长任务你发现方向不对按CtrlC可以停下来。CtrlD是退出但退出前会提示你是否保存会话。如果你直接关终端窗口会话可能丢失所以养成用CtrlD退出的习惯。Tab自动补全在输入命令时特别有用。比如你输入opencode ses然后按Tab它会自动补全成opencode session。如果多个命令有相同前缀按两次Tab会列出所有匹配项。3.4 自定义快捷键打造顺手的操作流OpenCode 允许你完全自定义快捷键。配置文件里有一个keybinds字段你可以覆盖任何默认绑定{ keybinds: { leader: ctrlx, new_session: ctrlx n, list_sessions: ctrlx l, switch_model: ctrlx m, toggle_view: ctrlx v, custom_command_1: ctrlx 1 } }自定义的时候有两条原则一是不要覆盖你已经在用的其他软件的快捷键二是尽量保持逻辑一致性。比如你把新建会话改成了Ctrlx n那新建 Agent最好也用Ctrlx开头加一个相关的字母这样记忆负担小。我自己的配置里加了一个Ctrlx d用来快速查看当前目录的 git diff因为我在 OpenCode 里最常做的操作之一就是让它帮我 review 代码改动。这个绑定不在默认配置里需要自己加{ keybinds: { custom_git_diff: ctrlx d }, custom_commands: { custom_git_diff: { command: git diff --stat, description: 查看当前改动概览 } } }注意自定义命令的配置格式可能随版本变化建议先用opencode config list确认当前版本支持的字段名。我遇到过升级后旧配置不生效的情况后来发现是字段名从custom_commands改成了commands。4. Agent 机制从调用到自定义的完整路径4.1 Agent 到底是什么跟普通对话有什么区别热词里agent和harness和agent区别出现频率很高说明很多人对这个概念还比较模糊。我用一个类比来解释普通对话模式下的 AI就像一个坐在你旁边的人你问什么它答什么它不会主动去翻你的文件、跑你的命令。而 Agent 模式下的 AI更像一个坐在你工位上的人——它有权限打开你的文件、执行命令、查看目录结构然后根据看到的信息来决定下一步做什么。OpenCode 里的 Agent 就是这个有权限操作你环境的角色。它内置了几个不同类型的 Agent通用 Agent什么都能干适合大多数日常任务代码审查 Agent专注于读代码、找问题不会主动改文件重构 Agent专门用来做代码重构会主动修改文件调试 Agent帮你定位 bug会跑测试、看日志切换 Agent 用Ctrlx g或者在启动时指定opencode --agent code-review4.2 Agent 的调用方式与参数传递在交互模式里你可以直接用自然语言让 Agent 干活 帮我看看 src/utils/ 目录下有没有重复的代码 把这个函数拆成三个小函数每个不超过 20 行 跑一下测试看看哪些失败了Agent 会根据你的描述自动决定用什么工具、按什么顺序执行。但有时候你需要更精确的控制这时候可以用命令模式# 直接调用特定 Agent 执行任务 opencode agent run code-review --path src/ # 查看可用 Agent 列表 opencode agent list # 查看某个 Agent 的详细配置 opencode agent info code-reviewagent run这个命令在自动化场景里很有用。比如你可以在 pre-commit hook 里加一条#!/bin/bash # .git/hooks/pre-commit opencode agent run code-review --path . --output review.md if grep -q CRITICAL review.md; then echo 代码审查发现严重问题提交被阻止 exit 1 fi这样每次提交前都会自动跑一遍代码审查有问题直接拦下来。我团队里用这个机制拦下了不少低级错误。4.3 自定义 Agent让 OpenCode 懂你的项目内置 Agent 虽然好用但每个项目的技术栈和规范都不一样。OpenCode 支持自定义 Agent你可以给它设定特定的系统提示词、工具权限、甚至专属的 Skill。自定义 Agent 的配置文件长这样{ agents: { my-project-reviewer: { description: 专门审查本项目的代码规范, model: claude-sonnet-4-20250514, system_prompt: 你是一个严格的代码审查者。本项目使用 TypeScript遵循 Airbnb 规范。重点关注1. 类型安全 2. 错误处理 3. 命名规范。不要修改代码只输出审查意见。, tools: [read_file, list_directory, search], skills: [./skills/typescript-review] } } }几个关键字段的解释system_prompt这是 Agent 的人设决定了它的行为方式。写得越具体Agent 的表现越符合预期。tools限制 Agent 能用的工具。比如代码审查 Agent 不需要write_file权限就把它排除掉避免误改文件。skills挂载专属 Skill后面会详细讲。我给自己项目配了一个db-migration-reviewerAgent专门审查数据库迁移脚本。它的 system prompt 里写死了项目的迁移规范比如所有迁移必须包含回滚脚本索引命名必须遵循 idx_表名_字段名 格式。这样每次审查迁移脚本时Agent 会自动按这些规则检查比人工看靠谱得多。4.4 Agent 执行出错时的排查思路热词里有一条 agent execution terminated due to error这是很多人遇到过的报错。Agent 执行中断的原因通常有这么几类权限问题Agent 想执行某个命令但没有权限。比如它想跑npm test但当前用户没有执行权限。排查方法是看错误信息里提到的具体命令手动跑一遍确认。上下文超限任务太复杂Agent 读了太多文件超出了模型的上下文窗口。这时候需要把任务拆小或者用--max-context参数限制读取范围。工具调用失败Agent 调用的某个工具返回了错误。比如它想读一个不存在的文件。这种情况通常 Agent 会自己重试或者换一种方式但如果连续失败就会终止。模型侧错误热词里 error from provider (console): opencodes free tier can only be used from within opencode 这个报错意思是免费额度只能在 OpenCode 内部使用不能通过 API 直接调用。如果你在脚本里用opencode run遇到了这个报错说明当前用的是免费模型需要换成付费模型或者调整调用方式。排查 Agent 问题的通用步骤# 1. 查看详细日志 opencode --log-level debug # 2. 查看当前 Agent 配置 opencode agent info agent-name # 3. 用最小任务测试 Agent 是否正常 opencode agent run agent-name --task 列出当前目录的文件 # 4. 检查模型连接状态 opencode model test实操心得Agent 报错时第一件事是看日志里的最后几行通常那里有最具体的错误信息。如果日志太长用opencode --log-level debug 21 | tail -50只看最后 50 行。5. Skill 机制与扩展能力实战5.1 Skill 是什么跟 Agent 什么关系Skill 是 OpenCode 里一个容易被忽略但极其强大的功能。简单说Agent 决定谁来干活Skill 决定怎么干活。一个 Skill 就是一组预定义的操作流程或者知识库。比如你可以写一个部署到测试环境的 Skill里面包含了完整的部署步骤跑测试、构建、上传、重启服务、验证。然后你只需要跟 Agent 说部署到测试环境它就会自动按这个 Skill 里的步骤执行。Skill 和 Agent 的关系是Agent 可以挂载多个 Skill根据任务类型自动选择合适的 Skill。你也可以手动指定用哪个 Skill。5.2 内置 Skill 的使用OpenCode 自带了一些常用 Skill可以通过命令查看# 列出所有可用 Skill opencode skill list # 查看某个 Skill 的详情 opencode skill info skill-name # 手动执行某个 Skill opencode skill run skill-name内置 Skill 通常包括代码格式化、依赖更新检查、测试运行、文档生成等。这些 Skill 开箱即用不需要额外配置。5.3 自定义 Skill把重复操作固化下来自定义 Skill 是提升效率的关键。任何你重复做了三次以上的操作都值得写成一个 Skill。Skill 文件是一个 Markdown 文件放在项目的skills/目录下。格式如下--- name: deploy-to-staging description: 部署当前分支到测试环境 --- # 部署到测试环境 ## 前置检查 1. 确认当前分支不是 main 2. 确认工作区没有未提交的改动 3. 确认测试全部通过 ## 部署步骤 1. 运行 npm run build 2. 运行 npm run deploy:staging 3. 等待部署完成检查健康检查接口 4. 如果健康检查失败自动回滚 ## 验证 - 访问 staging 环境的首页确认返回 200 - 检查关键接口的响应时间写好之后在 Agent 配置里挂载这个 Skill{ agents: { deployer: { skills: [./skills/deploy-to-staging] } } }然后你就可以直接说部署到测试环境Agent 会自动按 Skill 里的步骤执行。我自己的项目里有一个release-checklistSkill把发版前的所有检查项都固化进去了。以前每次发版都要对着 checklist 手动过一遍现在一句话搞定而且不会漏项。5.4 Skill 的调试与版本管理Skill 写多了之后管理就成了问题。我的做法是把 Skill 目录纳入 git 管理每个 Skill 的修改都有记录。同时给 Skill 加版本号--- name: deploy-to-staging version: 1.2.0 description: 部署当前分支到测试环境 changelog: - 1.2.0: 增加回滚步骤 - 1.1.0: 增加健康检查 - 1.0.0: 初始版本 ---调试 Skill 的时候可以用--dry-run参数让 Agent 只输出将要执行的步骤不实际执行opencode skill run deploy-to-staging --dry-run这样可以在真正执行前确认步骤是否正确避免误操作。注意Skill 里的命令会以当前用户权限执行所以不要在 Skill 里放危险命令比如rm -rf。如果确实需要删除操作加上确认步骤让 Agent 在执行前询问你。6. 常见报错与排查速查6.1 安装与启动阶段的典型问题问题一opencode: command not found安装后命令找不到通常是 PATH 没配好。检查安装路径是否在 PATH 里# 查看 opencode 安装位置 which opencode # 如果找不到手动找一下 find / -name opencode -type f 2/dev/null # 把安装目录加到 PATH export PATH$PATH:/path/to/opencode/bin问题二启动后卡在加载界面通常是网络问题或者模型连接超时。检查网络连接确认能访问模型服务。如果是公司网络可能需要配置代理注意这里指的是正常的 HTTP 代理用于访问外部服务。# 测试模型连接 opencode model test # 查看详细日志 opencode --log-level debug问题三配置文件不生效检查配置文件的优先级。命令行参数 项目级配置 全局配置。用opencode config list查看当前生效的配置确认你的设置有没有被覆盖。6.2 运行阶段的常见报错报错信息可能原因解决方法error from provider: free tier can only be used from within opencode免费模型被外部调用改用付费模型或在 OpenCode 内部使用agent execution terminated due to errorAgent 执行中断查看 debug 日志确认具体错误context length exceeded上下文超限拆分任务或限制读取范围tool call failed工具调用失败检查工具依赖是否安装model not available模型不可用检查模型名称和 API 配置permission denied权限不足检查文件/命令权限6.3 性能问题的排查思路OpenCode 用久了可能会变慢原因通常有几个会话文件太大长时间不归档会话文件会积累到几百 MB。定期归档和清理# 查看会话目录大小 du -sh ~/.opencode/sessions/ # 归档旧会话 opencode session archive --older-than 7d缓存过多OpenCode 会缓存模型响应和文件索引。清理缓存opencode cache clear模型响应慢如果用的是远程模型网络延迟会影响体验。可以切换到本地模型或者选择响应更快的模型。6.4 我踩过的三个坑坑一在项目根目录放了配置文件但忘了加 .gitignore结果 API 密钥差点被提交。后来我把敏感配置全部改成环境变量项目级配置只放非敏感内容。坑二Agent 权限给太大误改了文件早期我给 Agent 开了所有工具权限结果它在我没注意的时候重构了一个不该动的文件。后来我给每个 Agent 精确配置tools列表只开必要的权限。坑三Skill 里的命令没有做错误处理写了一个部署 Skill里面直接跑npm run deploy没有检查前置条件。结果有一次在错误的分支上执行了部署。后来我在 Skill 开头加了前置检查步骤不满足条件直接终止。7. 效率提升的进阶技巧7.1 把 OpenCode 嵌入日常工作流OpenCode 最大的价值不是单独使用而是嵌入到你已有的工作流里。我目前的做法是Git hookpre-commit 跑代码审查 Agentcommit-msg 跑提交信息规范检查Makefile把常用任务封装成 make 目标内部调用opencode runShell 别名把高频命令做成别名减少输入# ~/.bashrc 或 ~/.zshrc alias ocopencode alias ocropencode run alias ocsopencode session list alias ocgopencode agent run code-review --path .7.2 多模型切换策略不同任务适合不同模型。我的策略是日常对话和简单任务用快速模型响应快成本低代码审查和重构用能力强的模型准确率高长文档处理用上下文窗口大的模型在 OpenCode 里可以快速切换# 查看可用模型 opencode model list # 切换模型 opencode model use claude-sonnet-4-20250514 # 或者在会话中切换 Ctrlx m7.3 会话命名与检索会话多了之后找到之前那个会话就成了问题。我的做法是给每个会话起一个有意义的名字包含日期和任务类型opencode session rename 2025-01-15-重构用户模块然后用session list配合 grep 快速定位opencode session list | grep 用户模块7.4 定期维护清单最后分享一个我每周执行的维护清单保持 OpenCode 处于最佳状态# 1. 归档超过 7 天的会话 opencode session archive --older-than 7d # 2. 清理缓存 opencode cache clear # 3. 检查更新 opencode update check # 4. 验证配置 opencode config validate # 5. 测试模型连接 opencode model test这套流程跑下来不到两分钟但能避免很多莫名其妙的问题。我坚持了几个月OpenCode 的稳定性明显提升很少再遇到卡顿或者报错。关于 OpenCode 的命令和快捷键其实核心就那么多关键是形成肌肉记忆。我的建议是先把最常用的十个快捷键练熟然后再逐步扩展。不要试图一次记住所有东西那样反而容易混淆。用着用着你会发现这些命令已经变成你操作电脑的本能反应了。
OpenCode 命令与快捷键完全指南：从入门到高效 Agent 调度
1. 为什么值得花时间整理 OpenCode 的命令体系刚接触 OpenCode 的人十有八九会经历这么一个阶段装好了界面也打开了然后对着屏幕发呆——这玩意儿到底怎么用菜单栏翻一遍没找到几个能点的按钮想跑个任务不知道从哪下手看别人演示时噼里啪啦敲几个键就完成了一堆操作自己却连 Leader 键是什么都没搞明白。这不是你的问题。OpenCode 这类终端优先的 AI 编程工具设计哲学就是键盘驱动——它把绝大多数能力藏在命令和快捷键里而不是摆在界面上。你看到的极简界面其实是把复杂度转移到了命令层。这意味着命令和快捷键的熟练度直接决定了你用 OpenCode 的效率上限。我用了大半年 OpenCode从最开始每次操作都要翻文档到现在基本可以盲操中间踩了不少坑。这篇文章就是把我积累的常用命令、快捷键、Agent 调度技巧、配置要点全部整理出来按使用场景分类配上我自己的实操心得。不管你是刚装好 OpenCode 的新手还是已经用了一段时间但总觉得效率上不去的老用户应该都能从里面找到有用的东西。文章会覆盖这几个方面基础命令与启动参数、Leader 键与核心快捷键体系、Agent 的调用与管理、Skill 机制的使用、常见报错排查、以及一些我摸索出来的效率技巧。每个部分都会说清楚为什么这么设计和实际怎么用而不是干巴巴地列一张表。2. OpenCode 基础命令与启动参数详解2.1 安装后的第一组命令确认环境与版本装完 OpenCode 之后别急着跑任务先花两分钟确认环境状态。这一步很多人会跳过结果后面遇到问题排查半天最后发现是版本不对或者依赖缺失。# 查看当前版本 opencode --version # 查看完整帮助信息 opencode --help # 查看特定子命令的帮助 opencode subcommand --help--version看起来简单但它能帮你快速判断当前装的是哪个版本。OpenCode 迭代很快不同版本之间命令行为可能有差异遇到问题时第一件事就是确认版本。--help输出的内容比较长建议配合less或者重定向到文件慢慢看opencode --help | less opencode --help opencode-help.txt我个人的习惯是把帮助信息存一份到本地遇到不确定的命令时直接搜文件比每次敲--help快得多。2.2 启动参数不同场景用不同姿势OpenCode 的启动参数决定了它进入什么模式、加载什么配置、连接什么模型。常用的启动方式有这么几种# 默认启动进入交互式界面 opencode # 指定工作目录启动 opencode --cwd /path/to/project # 以非交互模式执行单次任务 opencode run 帮我重构这个函数 # 指定配置文件 opencode --config /path/to/config.json # 查看当前生效的配置 opencode config list--cwd这个参数值得单独说一下。OpenCode 默认以当前目录作为工作区但很多时候你是在一个父目录下操作想让它聚焦到某个子项目。这时候用--cwd比先cd过去再启动更清晰尤其是你在脚本里调用的时候。run子命令是自动化场景的关键。它让 OpenCode 执行一次任务然后退出不进入交互界面。你可以把它嵌到 shell 脚本或者 CI 流程里# 在脚本中调用把结果输出到文件 opencode run 检查这个目录下所有 Python 文件的语法错误 result.txt 21注意run模式下 OpenCode 不会等待你确认它会直接执行。所以任务描述要尽量明确避免它做出你意料之外的操作。我一般会先在交互模式里试一遍确认行为符合预期后再写成run命令。2.3 配置管理命令让 OpenCode 记住你的偏好OpenCode 的配置分几个层级全局配置、项目级配置、会话级配置。理解这个层级关系很重要因为它决定了你的设置什么时候生效、什么时候被覆盖。# 查看所有配置项 opencode config list # 获取某个配置项的值 opencode config get model # 设置配置项 opencode config set model claude-sonnet-4-20250514 # 删除配置项 opencode config unset model # 查看配置文件位置 opencode config path配置的优先级从高到低是命令行参数 项目级配置 全局配置。也就是说如果你在项目根目录放了一个.opencode/config.json它会覆盖全局设置。这个机制在团队协作时特别有用——你可以把项目相关的模型选择、Skill 配置提交到仓库让所有成员用同一套设置。我踩过的一个坑早期我把 API 相关的配置写在了项目级配置文件里结果提交代码时差点把密钥一起提交上去。后来学乖了敏感信息一律走环境变量项目级配置只放非敏感的项目相关设置。# 推荐做法敏感信息用环境变量 export OPENCODE_API_KEYyour-key-here # 项目级配置只放这类内容 { model: claude-sonnet-4-20250514, skills: [./skills/project-specific] }2.4 会话管理别让上下文丢了OpenCode 的会话机制是它区别于普通命令行工具的一个重要特性。每次交互都会产生上下文这些上下文可以保存、恢复、归档。# 列出所有会话 opencode session list # 恢复指定会话 opencode session resume session-id # 归档当前会话 opencode session archive # 查看归档的会话 opencode session list --archived会话归档后去哪了这是热词里出现频率很高的问题。归档的会话默认存在~/.opencode/sessions/archive/目录下以 JSON 格式保存。你可以直接查看这些文件也可以用session resume恢复。如果磁盘空间紧张可以定期清理旧的归档会话# 查看归档会话占用的空间 du -sh ~/.opencode/sessions/archive/ # 清理 30 天前的归档 find ~/.opencode/sessions/archive/ -mtime 30 -delete实操心得我习惯在完成一个阶段性任务后手动归档会话而不是让它一直挂着。这样下次session list的时候列表干净找起来快。归档不等于删除需要的时候随时能恢复。3. Leader 键与核心快捷键体系拆解3.1 Leader 键是什么为什么需要它如果你用过 Vim、Tmux 或者 Emacs对 Leader 键的概念应该不陌生。简单说Leader 键就是一个前缀键——你先按它再按其他键组合成一个命令。这样做的好处是避免快捷键冲突同时让快捷键体系可以无限扩展。OpenCode 默认的 Leader 键是Ctrlx。你可以把它理解成进入命令模式的开关。按下Ctrlx之后OpenCode 会等待你输入下一个键根据这个键来决定执行什么操作。为什么不用单个键或者Ctrl字母的组合因为终端环境下很多组合键已经被系统或者终端模拟器占用了。用 Leader 键做前缀相当于开辟了一个独立的命名空间不会跟其他软件打架。你可以自定义 Leader 键{ keybinds: { leader: ctrlspace } }我试过改成Ctrlspace但发现跟输入法切换冲突最后还是用回了默认的Ctrlx。如果你用的是 macOSCtrlx跟系统快捷键冲突的概率很低建议保持默认。3.2 最常用的 Leader 组合键下面这些是我日常使用频率最高的 Leader 组合按使用场景分组会话与上下文管理快捷键功能使用场景Ctrlx n新建会话开始一个独立任务时Ctrlx l列出会话需要切换回之前的任务Ctrlx a归档当前会话任务完成后清理Ctrlx r重命名会话给会话起个有意义的名字Agent 与模型切换快捷键功能使用场景Ctrlx m切换模型不同任务用不同模型Ctrlx g切换 Agent在通用 Agent 和专用 Agent 之间切换Ctrlx s查看当前状态确认当前用的是哪个模型和 Agent编辑与操作快捷键功能使用场景Ctrlx e打开外部编辑器需要写长文本时Ctrlx c复制最后一条回复快速取用输出内容Ctrlx u撤销上一步操作误操作后回退视图控制快捷键功能使用场景Ctrlx v切换详细/简洁视图根据屏幕空间调整Ctrlx t切换主题光线环境变化时Ctrlx ?显示快捷键帮助忘记某个组合时这张表建议截图存手机里前两周对着用慢慢就形成肌肉记忆了。我刚开始的时候把最常用的五六个写在便签上贴在显示器边框一周之后就基本不用看了。3.3 非 Leader 快捷键日常操作的高频键除了 Leader 组合还有一些不需要前缀的直接快捷键这些是日常操作中使用频率最高的Enter 发送消息 ShiftEnter 换行不发送 CtrlC 中断当前操作 CtrlD 退出 OpenCode CtrlL 清屏 CtrlR 搜索历史消息 Tab 自动补全 上/下箭头 浏览历史输入CtrlC和CtrlD这两个要特别说一下。CtrlC是中断当前正在执行的操作比如 Agent 正在跑一个长任务你发现方向不对按CtrlC可以停下来。CtrlD是退出但退出前会提示你是否保存会话。如果你直接关终端窗口会话可能丢失所以养成用CtrlD退出的习惯。Tab自动补全在输入命令时特别有用。比如你输入opencode ses然后按Tab它会自动补全成opencode session。如果多个命令有相同前缀按两次Tab会列出所有匹配项。3.4 自定义快捷键打造顺手的操作流OpenCode 允许你完全自定义快捷键。配置文件里有一个keybinds字段你可以覆盖任何默认绑定{ keybinds: { leader: ctrlx, new_session: ctrlx n, list_sessions: ctrlx l, switch_model: ctrlx m, toggle_view: ctrlx v, custom_command_1: ctrlx 1 } }自定义的时候有两条原则一是不要覆盖你已经在用的其他软件的快捷键二是尽量保持逻辑一致性。比如你把新建会话改成了Ctrlx n那新建 Agent最好也用Ctrlx开头加一个相关的字母这样记忆负担小。我自己的配置里加了一个Ctrlx d用来快速查看当前目录的 git diff因为我在 OpenCode 里最常做的操作之一就是让它帮我 review 代码改动。这个绑定不在默认配置里需要自己加{ keybinds: { custom_git_diff: ctrlx d }, custom_commands: { custom_git_diff: { command: git diff --stat, description: 查看当前改动概览 } } }注意自定义命令的配置格式可能随版本变化建议先用opencode config list确认当前版本支持的字段名。我遇到过升级后旧配置不生效的情况后来发现是字段名从custom_commands改成了commands。4. Agent 机制从调用到自定义的完整路径4.1 Agent 到底是什么跟普通对话有什么区别热词里agent和harness和agent区别出现频率很高说明很多人对这个概念还比较模糊。我用一个类比来解释普通对话模式下的 AI就像一个坐在你旁边的人你问什么它答什么它不会主动去翻你的文件、跑你的命令。而 Agent 模式下的 AI更像一个坐在你工位上的人——它有权限打开你的文件、执行命令、查看目录结构然后根据看到的信息来决定下一步做什么。OpenCode 里的 Agent 就是这个有权限操作你环境的角色。它内置了几个不同类型的 Agent通用 Agent什么都能干适合大多数日常任务代码审查 Agent专注于读代码、找问题不会主动改文件重构 Agent专门用来做代码重构会主动修改文件调试 Agent帮你定位 bug会跑测试、看日志切换 Agent 用Ctrlx g或者在启动时指定opencode --agent code-review4.2 Agent 的调用方式与参数传递在交互模式里你可以直接用自然语言让 Agent 干活 帮我看看 src/utils/ 目录下有没有重复的代码 把这个函数拆成三个小函数每个不超过 20 行 跑一下测试看看哪些失败了Agent 会根据你的描述自动决定用什么工具、按什么顺序执行。但有时候你需要更精确的控制这时候可以用命令模式# 直接调用特定 Agent 执行任务 opencode agent run code-review --path src/ # 查看可用 Agent 列表 opencode agent list # 查看某个 Agent 的详细配置 opencode agent info code-reviewagent run这个命令在自动化场景里很有用。比如你可以在 pre-commit hook 里加一条#!/bin/bash # .git/hooks/pre-commit opencode agent run code-review --path . --output review.md if grep -q CRITICAL review.md; then echo 代码审查发现严重问题提交被阻止 exit 1 fi这样每次提交前都会自动跑一遍代码审查有问题直接拦下来。我团队里用这个机制拦下了不少低级错误。4.3 自定义 Agent让 OpenCode 懂你的项目内置 Agent 虽然好用但每个项目的技术栈和规范都不一样。OpenCode 支持自定义 Agent你可以给它设定特定的系统提示词、工具权限、甚至专属的 Skill。自定义 Agent 的配置文件长这样{ agents: { my-project-reviewer: { description: 专门审查本项目的代码规范, model: claude-sonnet-4-20250514, system_prompt: 你是一个严格的代码审查者。本项目使用 TypeScript遵循 Airbnb 规范。重点关注1. 类型安全 2. 错误处理 3. 命名规范。不要修改代码只输出审查意见。, tools: [read_file, list_directory, search], skills: [./skills/typescript-review] } } }几个关键字段的解释system_prompt这是 Agent 的人设决定了它的行为方式。写得越具体Agent 的表现越符合预期。tools限制 Agent 能用的工具。比如代码审查 Agent 不需要write_file权限就把它排除掉避免误改文件。skills挂载专属 Skill后面会详细讲。我给自己项目配了一个db-migration-reviewerAgent专门审查数据库迁移脚本。它的 system prompt 里写死了项目的迁移规范比如所有迁移必须包含回滚脚本索引命名必须遵循 idx_表名_字段名 格式。这样每次审查迁移脚本时Agent 会自动按这些规则检查比人工看靠谱得多。4.4 Agent 执行出错时的排查思路热词里有一条 agent execution terminated due to error这是很多人遇到过的报错。Agent 执行中断的原因通常有这么几类权限问题Agent 想执行某个命令但没有权限。比如它想跑npm test但当前用户没有执行权限。排查方法是看错误信息里提到的具体命令手动跑一遍确认。上下文超限任务太复杂Agent 读了太多文件超出了模型的上下文窗口。这时候需要把任务拆小或者用--max-context参数限制读取范围。工具调用失败Agent 调用的某个工具返回了错误。比如它想读一个不存在的文件。这种情况通常 Agent 会自己重试或者换一种方式但如果连续失败就会终止。模型侧错误热词里 error from provider (console): opencodes free tier can only be used from within opencode 这个报错意思是免费额度只能在 OpenCode 内部使用不能通过 API 直接调用。如果你在脚本里用opencode run遇到了这个报错说明当前用的是免费模型需要换成付费模型或者调整调用方式。排查 Agent 问题的通用步骤# 1. 查看详细日志 opencode --log-level debug # 2. 查看当前 Agent 配置 opencode agent info agent-name # 3. 用最小任务测试 Agent 是否正常 opencode agent run agent-name --task 列出当前目录的文件 # 4. 检查模型连接状态 opencode model test实操心得Agent 报错时第一件事是看日志里的最后几行通常那里有最具体的错误信息。如果日志太长用opencode --log-level debug 21 | tail -50只看最后 50 行。5. Skill 机制与扩展能力实战5.1 Skill 是什么跟 Agent 什么关系Skill 是 OpenCode 里一个容易被忽略但极其强大的功能。简单说Agent 决定谁来干活Skill 决定怎么干活。一个 Skill 就是一组预定义的操作流程或者知识库。比如你可以写一个部署到测试环境的 Skill里面包含了完整的部署步骤跑测试、构建、上传、重启服务、验证。然后你只需要跟 Agent 说部署到测试环境它就会自动按这个 Skill 里的步骤执行。Skill 和 Agent 的关系是Agent 可以挂载多个 Skill根据任务类型自动选择合适的 Skill。你也可以手动指定用哪个 Skill。5.2 内置 Skill 的使用OpenCode 自带了一些常用 Skill可以通过命令查看# 列出所有可用 Skill opencode skill list # 查看某个 Skill 的详情 opencode skill info skill-name # 手动执行某个 Skill opencode skill run skill-name内置 Skill 通常包括代码格式化、依赖更新检查、测试运行、文档生成等。这些 Skill 开箱即用不需要额外配置。5.3 自定义 Skill把重复操作固化下来自定义 Skill 是提升效率的关键。任何你重复做了三次以上的操作都值得写成一个 Skill。Skill 文件是一个 Markdown 文件放在项目的skills/目录下。格式如下--- name: deploy-to-staging description: 部署当前分支到测试环境 --- # 部署到测试环境 ## 前置检查 1. 确认当前分支不是 main 2. 确认工作区没有未提交的改动 3. 确认测试全部通过 ## 部署步骤 1. 运行 npm run build 2. 运行 npm run deploy:staging 3. 等待部署完成检查健康检查接口 4. 如果健康检查失败自动回滚 ## 验证 - 访问 staging 环境的首页确认返回 200 - 检查关键接口的响应时间写好之后在 Agent 配置里挂载这个 Skill{ agents: { deployer: { skills: [./skills/deploy-to-staging] } } }然后你就可以直接说部署到测试环境Agent 会自动按 Skill 里的步骤执行。我自己的项目里有一个release-checklistSkill把发版前的所有检查项都固化进去了。以前每次发版都要对着 checklist 手动过一遍现在一句话搞定而且不会漏项。5.4 Skill 的调试与版本管理Skill 写多了之后管理就成了问题。我的做法是把 Skill 目录纳入 git 管理每个 Skill 的修改都有记录。同时给 Skill 加版本号--- name: deploy-to-staging version: 1.2.0 description: 部署当前分支到测试环境 changelog: - 1.2.0: 增加回滚步骤 - 1.1.0: 增加健康检查 - 1.0.0: 初始版本 ---调试 Skill 的时候可以用--dry-run参数让 Agent 只输出将要执行的步骤不实际执行opencode skill run deploy-to-staging --dry-run这样可以在真正执行前确认步骤是否正确避免误操作。注意Skill 里的命令会以当前用户权限执行所以不要在 Skill 里放危险命令比如rm -rf。如果确实需要删除操作加上确认步骤让 Agent 在执行前询问你。6. 常见报错与排查速查6.1 安装与启动阶段的典型问题问题一opencode: command not found安装后命令找不到通常是 PATH 没配好。检查安装路径是否在 PATH 里# 查看 opencode 安装位置 which opencode # 如果找不到手动找一下 find / -name opencode -type f 2/dev/null # 把安装目录加到 PATH export PATH$PATH:/path/to/opencode/bin问题二启动后卡在加载界面通常是网络问题或者模型连接超时。检查网络连接确认能访问模型服务。如果是公司网络可能需要配置代理注意这里指的是正常的 HTTP 代理用于访问外部服务。# 测试模型连接 opencode model test # 查看详细日志 opencode --log-level debug问题三配置文件不生效检查配置文件的优先级。命令行参数 项目级配置 全局配置。用opencode config list查看当前生效的配置确认你的设置有没有被覆盖。6.2 运行阶段的常见报错报错信息可能原因解决方法error from provider: free tier can only be used from within opencode免费模型被外部调用改用付费模型或在 OpenCode 内部使用agent execution terminated due to errorAgent 执行中断查看 debug 日志确认具体错误context length exceeded上下文超限拆分任务或限制读取范围tool call failed工具调用失败检查工具依赖是否安装model not available模型不可用检查模型名称和 API 配置permission denied权限不足检查文件/命令权限6.3 性能问题的排查思路OpenCode 用久了可能会变慢原因通常有几个会话文件太大长时间不归档会话文件会积累到几百 MB。定期归档和清理# 查看会话目录大小 du -sh ~/.opencode/sessions/ # 归档旧会话 opencode session archive --older-than 7d缓存过多OpenCode 会缓存模型响应和文件索引。清理缓存opencode cache clear模型响应慢如果用的是远程模型网络延迟会影响体验。可以切换到本地模型或者选择响应更快的模型。6.4 我踩过的三个坑坑一在项目根目录放了配置文件但忘了加 .gitignore结果 API 密钥差点被提交。后来我把敏感配置全部改成环境变量项目级配置只放非敏感内容。坑二Agent 权限给太大误改了文件早期我给 Agent 开了所有工具权限结果它在我没注意的时候重构了一个不该动的文件。后来我给每个 Agent 精确配置tools列表只开必要的权限。坑三Skill 里的命令没有做错误处理写了一个部署 Skill里面直接跑npm run deploy没有检查前置条件。结果有一次在错误的分支上执行了部署。后来我在 Skill 开头加了前置检查步骤不满足条件直接终止。7. 效率提升的进阶技巧7.1 把 OpenCode 嵌入日常工作流OpenCode 最大的价值不是单独使用而是嵌入到你已有的工作流里。我目前的做法是Git hookpre-commit 跑代码审查 Agentcommit-msg 跑提交信息规范检查Makefile把常用任务封装成 make 目标内部调用opencode runShell 别名把高频命令做成别名减少输入# ~/.bashrc 或 ~/.zshrc alias ocopencode alias ocropencode run alias ocsopencode session list alias ocgopencode agent run code-review --path .7.2 多模型切换策略不同任务适合不同模型。我的策略是日常对话和简单任务用快速模型响应快成本低代码审查和重构用能力强的模型准确率高长文档处理用上下文窗口大的模型在 OpenCode 里可以快速切换# 查看可用模型 opencode model list # 切换模型 opencode model use claude-sonnet-4-20250514 # 或者在会话中切换 Ctrlx m7.3 会话命名与检索会话多了之后找到之前那个会话就成了问题。我的做法是给每个会话起一个有意义的名字包含日期和任务类型opencode session rename 2025-01-15-重构用户模块然后用session list配合 grep 快速定位opencode session list | grep 用户模块7.4 定期维护清单最后分享一个我每周执行的维护清单保持 OpenCode 处于最佳状态# 1. 归档超过 7 天的会话 opencode session archive --older-than 7d # 2. 清理缓存 opencode cache clear # 3. 检查更新 opencode update check # 4. 验证配置 opencode config validate # 5. 测试模型连接 opencode model test这套流程跑下来不到两分钟但能避免很多莫名其妙的问题。我坚持了几个月OpenCode 的稳定性明显提升很少再遇到卡顿或者报错。关于 OpenCode 的命令和快捷键其实核心就那么多关键是形成肌肉记忆。我的建议是先把最常用的十个快捷键练熟然后再逐步扩展。不要试图一次记住所有东西那样反而容易混淆。用着用着你会发现这些命令已经变成你操作电脑的本能反应了。
