OpenCode 教程

OpenCode 接入 DeepSeek

DeepSeek 是国内高性价比的 AI 模型,OpenCode 可轻松接入。

1. 获取 API Key

1. 注册 platform.deepseek.com
2. 创建 API Key(充值)
3. 复制 key

2. 配置方式一: 环境变量

export OPENAI_API_KEY="sk-deepseek-key"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"

# 启动
opencode

3. 配置方式二: 配置文件

# ~/.config/opencode/opencode.json
{
  "provider": "openai",
  "model": "deepseek-chat",
  "apiKey": "sk-deepseek-key",
  "baseUrl": "https://api.deepseek.com/v1"
}

4. 推荐模型

deepseek-chat:      通用对话,日常编程首选(便宜)
deepseek-coder:     代码专项,编程任务效果好
deepseek-reasoner:  深度推理,复杂问题

# 切换
/model deepseek-coder

5. 验证连接

opencode "用 Python 实现二分查找,并给出测试"

# 成功输出代码;失败检查 Key/网络

6. 常见问题

1. 401: Key 错误或未生效
2. 402: 余额不足,充值
3. 429: 限流,稍后重试
4. 慢: deepseek-reasoner 推理耗时属正常
5. 网络: 确认 baseUrl 与代理配置

OpenCode 配置文件

OpenCode 通过 JSON 配置文件定制全局行为与项目设置。

1. 配置文件位置

全局: ~/.config/opencode/opencode.json
项目: .opencode/opencode.json(项目级覆盖)
环境: OPENCODE_CONFIG 环境变量指定路径

优先级: 项目配置 > 全局配置 > 默认

2. 核心配置项

{
  "provider": "openai",          // 提供商
  "model": "gpt-4o",             // 默认模型
  "apiKey": "sk-xxx",            // API Key
  "baseUrl": "https://...",      // API 地址
  "temperature": 0.7,            // 随机性
  "maxTokens": 8192,             // 最大输出
  "autocomplete": true           // 补全
}

3. 行为配置

{
  "permissions": {
    "allow": ["bash", "edit"],   // 允许的工具
    "deny": ["webfetch"]         // 禁止的工具
  },
  "notify": true,                // 桌面通知
  "small_model": "gpt-4o-mini",  // 简单任务模型
  "theme": "opencode",           // 主题
  "agent": "code"                // 默认 agent
}

4. 项目配置示例

// .opencode/opencode.json
{
  "instructions": "项目专用提示词...",
  "permissions": {
    "allow": ["bash"],
    "deny": ["npm publish"]
  },
  "model": "deepseek-coder"
}

5. 查看当前配置

opencode config
# 或 TUI 中 /config

6. 配置最佳实践

1. 全局配置: 模型与 Key
2. 项目配置: 权限、指令、专属模型
3. 团队: 项目配置文件入 Git 共享
4. Key 不写配置文件,用环境变量
5. 改配置后重启生效

OpenCode 第一次使用

完成配置后,体验 OpenCode 的首次对话与任务执行。

1. 启动 TUI

cd my-project
opencode

2. 基本对话

> 你好,你能做什么?

OpenCode: 我是 AI 编程助手,可以:
- 生成和修改代码
- 解释代码与文档
- 执行命令与 Git 操作
- 排查与修复 bug

3. 写代码任务

> 创建一个 Python 文件,实现冒泡排序

[工具] 创建文件 bubble_sort.py
✓ 已创建 bubble_sort.py
[工具] 运行 python bubble_sort.py
✓ 输出: [1, 2, 3, 5, 8]

4. 修改与反馈

> 改成降序排序

[工具] 编辑 bubble_sort.py
✓ 已修改
> 加注释并解释一下

...完成

5. 查看操作历史

> /undo       撤销上次操作
> /redo       重做
> /session    查看会话信息

6. 常用技巧

1. 任务描述具体: "把 src/utils.py 中的函数改成异步"
2. 要求验证: "改完运行测试"
3. 限定范围: "只修改 api 目录下的文件"
4. 多轮追问: 不满意继续提要求
5. Ctrl+C 中断, /undo 回滚

OpenCode VS Code 扩展

在 VS Code 中使用 OpenCode,享受 IDE 内的 AI 编程体验。

1. 安装扩展

1. 打开 VS Code 扩展市场
2. 搜索 "OpenCode"
3. 安装(官方扩展)

# 或命令行
code --install-extension opencode.opencode

2. 使用方式

1. 打开项目
2. Ctrl+Shift+P → "OpenCode: Open"
3. 在打开的终端面板中对话

或直接:
- 选中代码 → 右键 → Ask OpenCode
- 编辑器内 AI 对话面板

3. 代码上下文

扩展自动把当前文件/选中代码作为上下文:

# 选中函数后提问
"解释这个函数"

# 选中报错区域
"修复这个错误"

# 全文件
"重构这个文件"

4. 快捷键

Ctrl+Shift+P  OpenCode 命令
Alt+C         打开对话面板(可自定义)
Ctrl+Enter    发送

5. 与 Git 集成

# 查看 diff
"解释当前未提交的改动"

# 生成提交信息
"根据改动生成 commit message"

6. 注意事项

1. 需要先配置 API Key(命令行配置即可)
2. 扩展共享 opencode 配置
3. 团队可以统一安装与配置
4. 支持多根工作区

OpenCode TUI(终端界面)

TUI 是 OpenCode 的主界面,提供沉浸式的终端 AI 编程体验。

1. 启动与布局

# 在项目目录启动
opencode

界面布局:
- 主区域: 对话与工具输出
- 底部: 输入框
- 右侧/顶部: 会话信息与模型
- 状态栏: 模型、上下文占用、快捷键提示

2. 常用快捷键

Enter        发送消息
Shift+Enter  换行
Ctrl+C       中断生成
Ctrl+N       新建会话
Ctrl+L       清屏
Ctrl+R       重新生成
Ctrl+U       撤销输入
Esc          关闭弹窗/退出菜单
Tab          补全/切换焦点
/help        查看全部快捷键

3. 斜杠命令

/model      切换模型
/agent      切换 agent(如 code/debug)
/session    查看会话
/compact    压缩上下文
/undo       撤销工具操作
/redo       重做
/permissions 管理权限
/theme      切换主题
/config     查看配置
/quit       退出

4. 工具调用展示

TUI 中实时显示工具执行:
[▸] 读取文件 src/main.py
[✓] 写入文件 src/main.py
[✕] 命令失败: npm test

可以 Ctrl+C 取消正在执行的操作

5. 多会话

Ctrl+N 新建会话
Ctrl+W 关闭会话
会话列表切换(类似编辑器标签)
每个会话独立上下文,可并行多个任务

6. 效率技巧

1. 用 /model 快速切换便宜/强大模型
2. 长对话及时 /compact 压缩
3. 项目专属指令写在配置里
4. 善用 Tab 补全命令与文件路径
5. Ctrl+C 中断错误方向,重新描述

OpenCode CLI 使用

CLI 模式适合脚本化、CI/CD 与一次性任务。

1. 基本用法

# 一次性任务
opencode "总结这个项目的架构"

# 指定文件上下文
opencode -f src/main.py "优化性能"

# 多个文件
opencode -f src/a.py -f src/b.py "对比两个文件"

# 指定模型
opencode --model deepseek-coder "重构这段代码"

2. 常用参数

-m, --model       指定模型
-p, --provider    指定提供商
-f, --file        附加文件(可多次)
-c, --continue    继续上次会话
-o, --output      输出格式(text/json/stream)
--agent           指定 agent
--permission-mode 权限模式
--session         会话 ID
-v, --version     版本
-h, --help        帮助

3. 管道与输出控制

# 代码进管道
cat error.log | opencode "分析这个日志"

# 输出到文件
opencode "生成 README" > README.md

# JSON 输出
opencode --output json "检查代码问题"

4. 脚本中使用

#!/bin/bash
# 批量检查代码
for f in src/*.py; do
  opencode -f "$f" "检查代码质量" 
done

# 带超时
timeout 60 opencode "执行任务" || echo "超时"

5. CI/CD 集成

# GitHub Actions
- name: AI Review
  run: |
    opencode --output json "审查改动" > review.json

6. 非交互注意事项

1. 非交互默认不允许工具确认,用 --permission-mode 控制
2. 长任务注意超时
3. 敏感操作建议保持确认模式
4. 输出 JSON 便于程序解析

OpenCode Web 使用

OpenCode 提供 Web 界面,可远程访问与团队共享。

1. 启动 Web 服务

# 启动 Web 服务器
opencode serve

# 指定端口与地址
opencode serve --port 3000 --hostname 0.0.0.0

# 默认 http://localhost:3000

2. Web 界面功能

- 与 TUI 相同的能力(对话、工具、会话)
- 浏览器访问,无安装需求
- 支持多用户(需配置认证)
- 远程开发服务器上使用方便

3. 认证配置

# 需要认证(生产环境必须)
opencode serve --auth

# 或环境变量
export OPENCODE_AUTH="username:password"
opencode serve

4. 反向代理(HTTPS)

# nginx 配置示例
server {
    server_name opencode.example.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

5. 团队使用场景

1. 开发服务器上部署,团队浏览器访问
2. 与 CI/CD 结合做 AI 代码审查
3. 共享会话给同事
4. 移动端浏览器简单查看

6. 安全建议

1. 生产环境必须开启认证
2. 用 HTTPS 反代
3. 限制绑定地址(内网用 127.0.0.1)
4. 控制可访问目录范围
5. 记录访问日志

OpenCode 与 GitHub 集成

OpenCode 提供 GitHub 工具,可在对话中直接操作仓库。

1. 配置 GitHub Token

# 生成 token(GitHub Settings → Developer settings → Personal access tokens)
# 权限: repo, read:org

export GITHUB_TOKEN="ghp_xxx"

2. 常用 GitHub 操作

# 在对话中直接要求:
"列出当前仓库的 open issues"
"创建 issue: 修复登录 bug"
"查看 PR #42 的改动"
"给 PR #42 添加评论"
"合并 PR #42"

3. 代码审查(PR Review)

# 审查 PR
opencode "审查 PR #42,关注潜在 bug 与安全问题"

# OpenCode 会:
# 1. 读取 PR 的 diff
# 2. 分析代码
# 3. 输出审查意见
# 4. 可一键发布评论

4. Issues 管理

# 自动创建 issue(如 CI 失败)
opencode "CI 日志显示测试失败,创建 issue 记录"

5. 安全注意

1. Token 用环境变量,勿提交
2. 最小权限原则(repo 即可)
3. 敏感仓库勿用公共模型
4. 合并 PR 前人工确认

6. 与 Actions 结合

# CI 中自动生成发布说明
opencode "根据 v1.0 到 v1.1 的 commits 生成 release notes"

OpenCode 与 GitLab 集成

OpenCode 同样支持 GitLab 仓库操作。

1. 配置 GitLab Token

# GitLab → Settings → Access Tokens
# 权限: api, read_repository

export GITLAB_TOKEN="glpat-xxx"
export GITLAB_URL="https://gitlab.example.com"  # 自托管

2. 常用操作

# 对话中:
"列出未合并的 MR"
"查看 MR !56 的改动"
"给 MR !56 添加评论"
"创建 issue"

3. MR 审查

opencode "审查 MR !56 的代码改动"

# 支持:
# - 读取 diff
# - 代码分析
# - 发布审查评论
# - 讨论区回复

4. 自托管 GitLab

# 自托管配置
export GITLAB_URL="https://gitlab.company.com"
export GITLAB_TOKEN="glpat-xxx"

# OpenCode 自动识别 API 地址

5. 注意事项

1. Token 权限最小化(api 够用)
2. 公司实例注意数据合规
3. 审查意见人工确认后再合并
4. 评论用词保持专业

OpenCode 工具系统

工具(Tools)是 OpenCode 执行任务的能力集合,理解工具便于更好地指挥它。

1. 内置工具

bash          执行 shell 命令
edit          精确编辑文件
write         写入新文件
read          读取文件
grep          代码搜索
glob          文件查找
list          列出目录
patch         应用补丁
web           网页抓取
webfetch      网络请求
toggl         工具开关

Git 相关:
git_status / git_diff / git_log
git_commit / git_branch / git_push

2. 查看工具状态

# TUI 中
/tools          列出所有工具及启用状态
/tool on bash   启用某工具
/tool off bash  禁用某工具

3. 权限控制

# 配置文件
{
  "permissions": {
    "allow": ["bash", "edit", "read"],
    "deny": ["webfetch"]
  }
}

# 或会话内
/permissions allow bash
/permissions deny rm

4. 工具失败处理

工具执行失败时:
1. 查看错误输出
2. 让 AI 分析原因并重试
3. 必要时手工干预

> 刚才命令失败了,分析原因并修复

5. 自定义工具

# OpenCode 支持自定义工具(详见自定义工具章节)
# 如: 调用公司内部 API 的专用工具
# 配置在 .opencode/ 目录

6. 工具安全

1. 危险命令(rm -rf、sudo)保持确认
2. 白名单限制可执行命令
3. 敏感文件访问限制
4. 审计日志记录工具调用
5. 不信任的项目禁止 bash

OpenCode 规则(Rules)

规则为 AI 提供项目级行为约束,让代码风格与规范保持一致。

1. 什么是规则

规则 = 注入给 AI 的指令
- 项目级: .opencode/rules
- 全局: ~/.config/opencode/rules
- 每次会话自动加载
- 用于约束代码风格、流程、禁忌

2. 创建项目规则

# .opencode/rules 文件
# 每个文件一个主题,支持 markdown

# .opencode/rules/000-structure
本项目的代码规范:
- 遵循现有目录结构,新代码放对应模块
- 公共函数写在 utils 目录
- 数据库操作统一走 repository 层

# .opencode/rules/001-style
代码风格:
- 使用 TypeScript 严格模式
- 缩进 2 空格
- 组件使用函数式写法
- 错误处理用统一 Error 类

# .opencode/rules/002-workflow
工作流程:
- 修改前先阅读相关文件
- 改完必须运行 npm test
- 禁止直接修改 lock 文件
- 提交信息遵循 conventional commits

3. 全局规则

# ~/.config/opencode/rules/global
回答要求:
- 用中文回答
- 代码给出完整可运行示例
- 解释时先结论后细节

4. 规则生效机制

规则在会话开始时自动注入
规则是纯文本指令,给模型的参考
不保证 100% 遵守,但显著提升一致性
优先级: 项目规则 > 全局规则

5. 规则最佳实践

1. 编号前缀控制顺序(000-, 001-)
2. 用肯定句式("应该...")而非否定
3. 简洁具体,别写长篇大论
4. 团队规范入 Git 共享
5. 定期审查更新规则

OpenCode 代理(Agent)

Agent 是 OpenCode 的"角色",不同的 agent 专注于不同类型的任务。

1. 内置 Agent

code    通用编程(默认)
debug   调试排错(自动加日志、测试)
plan    规划模式(只规划不执行)
review  代码审查

# 切换
/agent debug
/agent plan

2. Agent 的作用

每个 agent 有专属的系统提示词与默认工具:
- code: 写代码、重构、解释
- debug: 分析错误、加调试、跑测试
- plan: 输出执行计划,不改文件
- review: 审查代码质量与安全

3. 创建自定义 Agent

# .opencode/agent/ 目录
# 每个 agent 一个 markdown 文件

# .opencode/agent/testing.md
---
name: testing
description: 负责编写与运行测试
tools: [bash, read, write, edit]
---

你是测试专家。任务:
1. 分析待测代码
2. 设计测试用例(覆盖边界)
3. 用 pytest 编写测试
4. 运行并修复失败
5. 输出覆盖率报告

4. 使用自定义 Agent

# 切换
/agent testing

# 或 CLI
opencode --agent testing "为 utils.py 写测试"

# 会话内临时指定
> 用 testing agent 的方式写测试

5. Agent 配置项

name:        agent 名
description: 描述(帮助 AI 理解用途)
tools:       允许使用的工具
model:       可选,指定模型
temperature: 可选,温度
prompt:      系统提示词内容

6. 最佳实践

1. 为常见任务建专属 agent
2. description 写清楚适用场景
3. 限制工具防止误操作
4. 团队共享 agent 定义
5. plan agent 用于复杂任务的方案先行

OpenCode 主题

OpenCode 支持自定义 TUI 主题与外观。

1. 内置主题

# 切换主题
/theme

# 直接指定
/theme catppuccin
/theme dracula
/theme nord

内置: opencode(默认)、dracula、catppuccin、nord、github 等

2. 配置默认主题

{
  "theme": "catppuccin"
}

3. 自定义主题

# .opencode/themes/mytheme.json
{
  "id": "mytheme",
  "name": "My Theme",
  "colors": {
    "primary": "#6366f1",
    "secondary": "#8b5cf6",
    "accent": "#22d3ee",
    "error": "#ef4444",
    "success": "#22c55e",
    "warning": "#f59e0b",
    "text": "#e2e8f0",
    "muted": "#94a3b8",
    "background": "#1e293b",
    "surface": "#334155",
    "border": "#475569"
  }
}

4. 主题应用

# 使用自定义主题
/theme mytheme

# 配置文件
{
  "theme": "mytheme"
}

5. 排版与界面设置

{
  "ui": {
    "showToolMessages": true,    // 显示工具调用
    "wordWrap": true,            // 自动换行
    "fontSize": 14,              // 字体大小
    "lineNumbers": true          // 行号
  }
}

6. 最佳实践

1. 深色主题保护眼睛,适合长时间开发
2. 自定义主题可分享给团队
3. 高对比度配色利于演示
4. 主题只影响界面,不影响功能

OpenCode 快捷键

掌握快捷键大幅提升 TUI 使用效率。

1. 基本操作

Enter         发送消息
Shift+Enter   换行
Ctrl+C        中断生成/取消
Ctrl+D        退出输入
Ctrl+L        清屏
Ctrl+R        重新生成回复
Ctrl+U        清空输入框
Ctrl+W        删除一个词
Esc           关闭弹窗

2. 会话管理

Ctrl+N    新建会话
Ctrl+O    切换会话
Ctrl+W    关闭当前会话
Ctrl+Shift+N 会话列表
Tab       切换焦点(输入框/输出)

3. 文本编辑

Ctrl+A      行首
Ctrl+E      行尾
Alt+Left    前一个词
Alt+Right   后一个词
Ctrl+K      删除到行尾
Alt+Backspace 删除一个词
Ctrl+Y      粘贴剪贴板

4. 导航

↑ / ↓       历史命令
PageUp      向上翻页
PageDown    向下翻页
Ctrl+Home   顶部
Ctrl+End    底部
Ctrl+F      搜索(部分版本)

5. 自定义快捷键

# 配置文件
{
  "keybindings": {
    "send": "Enter",
    "interrupt": "Ctrl+C",
    "newSession": "Ctrl+N",
    "modelSwitch": "Ctrl+M"
  }
}

# 查看当前绑定
/help

6. 效率组合

1. Ctrl+N 快速开新会话(任务隔离)
2. Ctrl+R 重新生成(不满意重试)
3. Ctrl+C 中断错误生成方向
4. ↑ 快速重发修改后的指令
5. Tab 快速切换焦点(边看边写)

OpenCode 自定义命令

自定义命令把常用任务固化成斜杠命令,一键触发。

1. 创建命令

# 命令目录
.opencode/commands/
# 每个命令一个 markdown 文件

# .opencode/commands/commit.md
---
description: 根据改动生成规范的提交信息
---
查看 git status 和 git diff,
生成符合 conventional commits 规范的提交信息,
直接输出,不要执行 commit。

2. 使用命令

# 在对话中
/commit

# 命令支持参数与文件引用
/test utils          # 测试 utils 模块
/review src/         # 审查目录

3. 命令模板变量

# .opencode/commands/review.md
---
description: 审查指定文件的代码
---
审查以下文件,输出问题清单与建议:
{{path}} 或 $ARGUMENTS

4. 带脚本的命令

# .opencode/commands/deploy.md
---
description: 部署到测试环境
---
执行: bash scripts/deploy.sh --env test
分析输出,如有错误给出修复建议。

5. 内置命令

/model      切换模型
/agent      切换 agent
/undo       撤销
/redo       重做
/compact    压缩上下文
/permissions 权限
/theme      主题
/session    会话信息
/help       帮助
/config     配置
/tools      工具管理

6. 最佳实践

1. description 帮助 OpenCode 识别用途
2. 命令内描述完整任务流程
3. 复杂流程拆成多个命令
4. 团队共享命令(入 Git)
5. 定期清理无用命令

OpenCode 格式化工具

OpenCode 集成了代码格式化与补全工具,让 AI 输出符合项目规范。

1. 格式化配置

# OpenCode 使用项目的格式化配置
# 自动识别:
# - .prettierrc / prettier.config.js
# - .editorconfig
# - biome.json
# - rustfmt.toml 等

# 也可在配置中指定
{
  "formatter": {
    "enabled": true,
    "command": "prettier --write"
  }
}

2. 格式化行为

OpenCode 写入文件时自动格式化:
1. 修改代码后按项目规范格式化
2. 保持现有文件风格
3. 不破坏已有格式
4. 尊重 .editorconfig 缩进/换行

3. 关闭格式化

{
  "formatter": {
    "enabled": false
  }
}

# 会话内
/format off
/format on

4. 代码补全

# OpenCode 支持代码补全(需模型支持)
# 配置
{
  "autocomplete": true,
  "completionModel": "deepseek-coder"   # 补全专用小模型
}

5. 与其他工具配合

# 可在规则中要求
规则: "所有生成的代码必须通过 npm run lint"

# 或自定义命令
# .opencode/commands/lint.md
运行 npm run lint,修复所有问题后输出结果。

6. 常见问题

1. 格式化破坏代码: 关闭 formatter,手动格式化
2. 大文件格式化慢: 仅格式化改动部分
3. 与团队规范冲突: 统一项目配置
4. 模板文件别格式化: 在规则中排除

OpenCode 权限配置

权限系统控制 AI 可执行的工具与命令,是安全使用的基础。

1. 权限模式

默认行为:
- 写入文件前需要确认
- 执行命令前需要确认
- 危险操作明确警告

# 会话内控制
/permissions             查看当前权限
/permissions allow bash  允许 bash
/permissions deny bash   拒绝 bash

2. 配置文件权限

{
  "permissions": {
    "allow": ["bash", "edit", "read", "grep"],
    "deny": ["webfetch"],
    "ask": ["write"],          // 询问
    "bash": {
      "allow": ["git*", "npm*", "python*"],
      "deny": ["rm -rf*", "sudo*"]
    }
  }
}

3. 会话内授权

# 一次性授权
> 允许执行 npm test

# 永久(写入配置)
> 记住: 允许执行 npm test
OpenCode: 已添加白名单

4. 项目级权限

# .opencode/config.json(项目)
{
  "permissions": {
    "allow": ["bash"],
    "bash": { "deny": ["git push"] }   // 禁止推送
  }
}

# 团队安全策略入 Git 共享

5. 审计

# 查看本次会话操作记录
/audit

# 日志位置
~/.local/share/opencode/logs/

# 权限变更也会记录

6. 安全最佳实践

1. 不信任项目: 禁止 bash 与 write
2. 生产环境: 关键操作保持确认
3. 白名单优于黑名单(allow 优先)
4. 危险命令全局 deny
5. 定期查看审计日志
6. 环境变量中的密钥勿泄露给 AI

OpenCode LSP 服务器配置

LSP(Language Server Protocol)支持让 AI 获得语言级代码理解能力。

1. 什么是 LSP 支持

通过 LSP,OpenCode 可以:
- 获取符号定义与引用
- 代码诊断(错误/警告)
- 跳转到定义
- 重命名符号
- 补全建议

让 AI 更准确地理解代码库

2. 配置 LSP

# 配置文件
{
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"]
    },
    "python": {
      "command": ["pylsp"]
    }
  }
}

# 常用 LSP
TypeScript: typescript-language-server
Python:     pylsp / pyright
Go:         gopls
Rust:       rust-analyzer
Java:       jdtls

3. 会话中使用

# 需要 LSP 分析时
"用 LSP 找到 getUser 的所有引用"
"用 LSP 检查当前文件的错误"

# 工具自动调用
OpenCode 在需要时自动使用 LSP

4. 安装 LSP 服务器

# TypeScript
npm install -g typescript-language-server typescript

# Python
pip install python-lsp-server

# Go
go install golang.org/x/tools/gopls@latest

# Rust
rustup component add rust-analyzer

5. 问题排查

1. LSP 未启动: 检查命令是否在 PATH
2. 大型项目慢: 限制索引范围
3. 语言不支持: 确认 LSP 已配置
4. 日志: opencode --log-level debug

OpenCode MCP 服务器配置

MCP(Model Context Protocol)让 OpenCode 连接外部工具与服务,极大扩展能力。

1. 什么是 MCP

MCP 是模型上下文协议(Anthropic 提出):
- 统一方式连接外部数据源与工具
- OpenCode 作为 MCP 客户端
- 服务端提供工具/资源/提示

示例: 数据库、浏览器、GitHub、内部 API

2. 配置 MCP 服务器

# 配置文件
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    },
    "database": {
      "command": "node",
      "args": ["/path/to/db-mcp-server.js"],
      "env": { "DB_URL": "mysql://..." }
    }
  }
}

3. 使用 MCP 工具

# 配置后自动加载 MCP 工具
"查询数据库中的用户表结构"
"用 GitHub MCP 创建 issue"
"搜索公司内部文档"

# 查看已连接的 MCP
/mcp

4. 常见 MCP 服务器

官方示例:
- github: 仓库与 issue 操作
- filesystem: 文件系统访问
- fetch: 网页抓取
- playwright: 浏览器自动化
- memory: 持久记忆

社区:
- 数据库(Postgres/MySQL)
- 搜索引擎
- 内部 API
- 设计工具

5. 安全注意

1. MCP 工具能力=AI 能力,权限最小化
2. 敏感服务器(数据库)用只读账号
3. Token/密码放 env,勿写入代码
4. 定期审计 MCP 使用
5. 不连接不可信来源的 MCP

OpenCode Skills

Skills 是可复用的能力单元,把特定任务的指令、脚本与参考打包,供 AI 按需加载。

1. Skills 是什么

类似 Claude Code 的 Skills:
- SKILL.md: 任务指令
- scripts/: 辅助脚本
- 按需加载,不占上下文
- 可分享、可安装

2. 内置 Skills

opencode 自带一批 skill:
- web-fetch: 网页抓取
- docs: 文档搜索
- agent: agent 管理
- 等(随版本更新)

3. 创建 Skill

# .opencode/skills/my-skill/
# SKILL.md
---
name: my-skill
description: 描述用途与触发场景
---
任务说明:
1. 步骤一
2. 步骤二
...

# 可附脚本
# scripts/run.sh

4. 使用 Skill

# 自动触发(描述匹配)
"帮我做 XXX"

# 手动
/skill my-skill

# 查看
/skills

5. Skills vs 规则 vs 命令

规则(Rules):  常驻指令,约束行为
命令(Commands): 固定任务,一键触发
技能(Skills): 按需加载的能力包,可带脚本

规则 > 命令 > Skills 的"常驻程度"
Skills 适合重量级、可打包的能力

6. 最佳实践

1. description 写清适用场景(触发关键)
2. 指令具体、可执行
3. 需要时附脚本与参考文档
4. 团队共享放 .opencode/skills
5. 保持 Skills 精简聚焦

OpenCode Skills 使用指南

详细介绍 OpenCode Skills 的安装、管理与实际使用。

1. 查看与安装

# 查看所有 skill
/skills

# 安装(从市场/仓库)
/skill install web-fetch
/skill install github.com/user/my-skill

# 手动放置
# 全局: ~/.config/opencode/skills/
# 项目: .opencode/skills/

2. SKILL.md 格式

---
name: code-review
description: 执行代码审查,找出 bug、安全问题与改进建议
---

# 代码审查

当用户要求审查代码时:
1. 读取相关文件
2. 检查: 逻辑错误、边界情况、安全问题
3. 输出: 按严重程度列出问题,附修复建议
4. 给出示例修复代码

## 注意事项
- 不要修改文件,只输出报告
- 不确定时标注"需人工确认"

3. 带脚本的 Skill

# .opencode/skills/deploy/SKILL.md
---
name: deploy
description: 一键部署到测试环境
---

执行部署脚本并分析结果:
bash scripts/deploy.sh

# scripts/deploy.sh
#!/bin/bash
echo "部署到测试环境..."
npm run build
rsync -av dist/ user@server:/opt/app

4. 技能触发机制

触发条件(满足其一):
1. 用户明确要求(/skill name)
2. AI 判断任务匹配 description(自动)
3. 上下文中出现触发词

OpenCode 会读取 SKILL.md 并执行指令

5. 开发调试 Skill

# 快速测试
1. 创建 SKILL.md
2. /skills 刷新
3. 触发并观察行为
4. 调整 description 与指令

# 调试提示
- 看 AI 是否加载了 skill(工具调用日志)
- description 写得太泛会误触发
- 太窄则不会触发,需手动

6. 团队协作

1. 项目级 skills 入 Git,团队共享
2. 统一命名与格式
3. 版本管理(文档注明变更)
4. 轮值维护,避免过期
5. 新人上手更快(技能即文档)

OpenCode 自定义工具

自定义工具让 OpenCode 获得专属能力,如调用内部系统、专有 API。

1. 工具定义方式

# 方式一: MCP 服务器(推荐,复用生态)
# 方式二: 配置文件内嵌工具
# 方式三: 编写本地工具脚本

# 配置文件内嵌示例
{
  "tools": [
    {
      "name": "search_products",
      "description": "搜索商品库",
      "type": "http",
      "config": {
        "url": "http://internal-api/search",
        "method": "GET",
        "headers": { "Authorization": "Bearer xxx" }
      }
    }
  ]
}

2. 工具参数定义

{
  "tools": [{
    "name": "get_stock_price",
    "description": "查询股票实时价格",
    "parameters": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "股票代码,如 600519"
        }
      },
      "required": ["code"]
    },
    "type": "http",
    "config": {
      "url": "http://api.example.com/stock/{code}",
      "method": "GET"
    }
  }]
}

3. 脚本型工具

# .opencode/tools/report.py
#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
# 生成报表
print(json.dumps({"rows": 10, "total": 1234}))

# 配置
{
  "tools": [{
    "name": "gen_report",
    "description": "生成销售报表",
    "type": "script",
    "config": { "command": ["python3", ".opencode/tools/report.py"] }
  }]
}

4. 使用自定义工具

# 配置后重启,AI 自动识别
"查询股票 600519 的价格"
"生成上个月销售报表"

# 工具列表
/tools

5. 工具开发要点

1. description 详细,利于 AI 正确调用
2. 参数 schema 明确必填与可选
3. 返回结构化 JSON
4. 错误返回友好信息
5. 超时与限流处理
6. 敏感操作需权限确认

6. 安全注意

1. 内部系统暴露给 AI = 暴露给所有用户
2. 工具访问控制与审计
3. 返回数据脱敏
4. 不可信输入校验
5. 定期审查工具清单

OpenCode oh-my-openagent

oh-my-openagent 是 OpenCode 生态的配置增强方案,提供一键配置与常用预设。

1. 是什么

类似 oh-my-zsh 之于 zsh:
- 预设配置集合
- 常用 agent/skill/主题
- 一键安装配置
- 社区维护

2. 安装

# 拉取仓库
git clone https://github.com/your/oh-my-openagent
cd oh-my-openagent

# 安装配置
./install.sh
# 或复制到 ~/.config/opencode/

3. 包含内容

典型包含:
- 常用 agent(测试/审查/部署等)
- 常用 skills
- 主题集合
- 规则模板
- 快捷键预设

# 查看
/skills
/agents
/theme

4. 自定义扩展

# 在 oh-my-openagent 基础上添加
# 自己的 agent/skill/主题
# 放到对应目录即可

5. 更新与维护

# 更新
git pull
./install.sh

# 或手动同步目录
rsync -av .opencode/ ~/.config/opencode/

6. 注意事项

1. 安装前备份自己的配置
2. 脚本来源要可信(检查内容)
3. 不需要的组件可删除
4. 团队可维护私有版本

OpenCode 生态系统

OpenCode 的开源生态提供丰富的扩展与集成方案。

1. 核心生态组件

Agent 集合: 社区共享的角色定义
Skills:    可安装能力包
主题:      界面外观
工具/MCP:  外部能力接入
配置预设:  oh-my-openagent 等

2. 获取资源

# GitHub 搜索
opencode agent / opencode skill / opencode theme

# 社区仓库(示例)
github.com/awesome-opencode(社区精选)

# 分享自己的作品
- 发布到 GitHub
- 写 README 说明用途与安装
- 打 tag 方便发现

3. 与编辑器生态集成

VS Code 扩展: 官方支持
Neovim: 社区插件
Emacs: 社区支持
终端: 任何支持 TUI 的终端

4. 自托管与团队

企业场景:
1. 自托管 Web 服务
2. 私有模型(vLLM/私有化 API)
3. 统一配置与权限
4. 审计日志
5. 内部技能库

5. 贡献方式

1. 提交 agent/skill 到社区
2. 报告 bug / 提功能需求
3. 改进文档与教程
4. 本地化(中文文档)
5. 赞助开源项目

6. 学习资源

官方文档: opencode.ai/docs
GitHub:   github.com/sst/opencode
社区:     Discord / GitHub Discussions
教程:     中文博客与视频(持续增多)

OpenCode 总结

回顾 OpenCode 的核心能力与最佳实践,快速上手建议。

核心能力回顾

1. 多界面: TUI / CLI / VS Code / Web
2. 多模型: OpenAI / DeepSeek / Anthropic / 本地
3. 工具系统: bash/edit/write/read/grep/git
4. Agent 角色: code/debug/plan/review + 自定义
5. 可扩展: 规则、命令、Skills、工具、MCP、LSP
6. 安全: 权限控制、白名单、审计
7. 生态: 主题、配置预设、社区资源

推荐工作流

日常开发:
  opencode → TUI → "实现 XX 功能"
  → 写代码 → 跑测试 → 提交

代码审查:
  opencode "审查未提交的改动"
  → AI 分析 → 修复问题

调试排错:
  /agent debug → 报错日志
  → AI 定位 → 修复 → 验证

项目初始化:
  opencode "搭建 Python 项目结构"
  → 目录/依赖/配置/README

最佳实践清单

✓ 项目写规则(rules)约束行为
✓ 常用任务建命令(command)
✓ 团队沉淀 Skills
✓ 配置权限白名单
✓ 敏感操作保持确认
✓ 长对话及时 /compact
✓ 复杂任务先用 plan agent
✓ 定期审查审计日志
✓ API Key 严格保密

下一步学习

1. 深入: 自定义 agent 与 skill 开发
2. 进阶: MCP 接入团队内部系统
3. 团队: 统一配置与规则入库
4. 企业: 自托管 + 私有模型 + 审计
5. 关注: OpenCode 版本更新与社区动态