Opencode on SRE运维博客

OpenCode 高级技巧与实战指南：提升 AI 编程效率的秘诀

Wenlong — Tue, 27 Jan 2026 11:41:36 +0800

作者：SRE运维博客
博客地址：https://www.cnsre.cn/
文章地址：https://www.cnsre.cn/posts/260127114136/
相关话题：https://www.cnsre.cn/tags/ai/
版权声明: 如需转载，请联系作者授权

引言

OpenCode 作为开源的 AI 编程助手，凭借其 80,000+ GitHub stars 和强大的功能生态，正在改变开发者的编程方式。根据官方文档，OpenCode 支持终端、桌面应用和 IDE 扩展多种形态，并提供 75+ LLM 提供商支持。

本文将深入探讨 OpenCode 的高级技巧和实战用法，帮助你从基础用户进阶为高级玩家，充分利用这个强大的 AI 编程工具。

1. 多代理工作流进阶

1.1 Build 和 Plan 代理的协同作战

OpenCode 内置了两个主要代理：Build（默认）和 Plan。Build 代理拥有全部工具权限，而 Plan 代理更适合代码审查和规划。

// 文件路径: .opencode.jsonc
// 来源: https://opencode.ai/docs/modes/
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "agent": {
    "build": {
      "tools": ["*"],
      "model": "anthropic/claude-sonnet-4-5"
    },
    "plan": {
      "tools": ["read", "glob", "grep", "lsp_*"],
      "permissions": {
        "write": "deny",
        "edit": "deny",
        "bash": "deny"
      },
      "model": "anthropic/claude-haiku-4-5"
    }
  }
}

1.2 使用 oh-my-opencode 扩展代理系统

oh-my-opencode 是社区开发的增强插件，提供了背景任务、专业化代理和高级工具集成。

# 安装 oh-my-opencode
# 来源: https://www.npmjs.com/package/oh-my-opencode
npm install -g oh-my-opencode

# 验证安装
oh-my-opencode --version

预期输出:

2.14.0

1.3 配置专业化代理

oh-my-opencode 提供了多个专业化代理，包括 Oracle、Librarian、Explore 等：

// 文件路径: .opencode/agents.json
// 来源: https://github.com/code-yeongyu/oh-my-opencode
// 版本: v2.14.0+

{
  "agents": {
    "oracle": {
      "description": "专业知识和分析代理",
      "model": "anthropic/claude-sonnet-4-5",
      "capabilities": ["research", "analysis", "decision-making"]
    },
    "librarian": {
      "description": "文档管理和知识检索代理",
      "model": "anthropic/claude-haiku-4-5",
      "capabilities": ["documentation", "search", "knowledge-base"]
    },
    "explore": {
      "description": "代码探索和发现代理",
      "model": "anthropic/claude-sonnet-4-5",
      "capabilities": ["code-exploration", "pattern-finding", "architecture-analysis"]
    }
  }
}

2. 高级斜杠命令自动化

2.1 创建自定义命令

通过创建 .opencode/commands/ 目录下的 Markdown 文件来定义自定义命令：

---
<!-- 文件路径: .opencode/commands/security-scan.md -->
<!-- 来源: https://opencode.ai/docs/commands/ -->
<!-- 版本: v1.0.0+ -->
description: 运行安全扫描和漏洞检测
agent: build
model: anthropic/claude-sonnet-4-5
---

执行全面的安全扫描，包括：
1. 依赖漏洞检查（npm audit）
2. 代码静态分析（eslint + 安全规则）
3. 敏感信息检测（git secrets）
4. 容器安全扫描（如果有 Dockerfile）

生成详细的报告并提供修复建议。

使用命令:

/security-scan

2.2 参数化斜杠命令

创建接受参数的高级命令：

---
<!-- 文件路径: .opencode/commands/deploy.md -->
<!-- 来源: https://opencode.ai/docs/commands/ -->
<!-- 版本: v1.0.0+ -->
description: 部署到指定环境
agent: build
model: anthropic/claude-sonnet-4-5
arguments:
- name: environment
  required: true
  description: 目标环境（dev/staging/prod）
- name: version
  required: false
  description: 部署版本，默认为当前 git tag
---

部署应用到 {{environment}} 环境

步骤：
1. 检查当前环境状态
2. 创建备份（如环境为 prod）
3. 读取配置文件 config/{{environment}}.yaml
4. 执行部署脚本
5. 验证部署结果
6. 如果失败，回滚到上一版本

{{#if version}}
指定版本：{{version}}
{{else}}
使用最新版本
{{/if}}

2.3 命令链和工作流

创建复杂的命令链来自动化重复性工作：

---
<!-- 文件路径: .opencode/commands/release-workflow.md -->
<!-- 来源: https://opencode.ai/docs/commands/ -->
<!-- 版本: v1.0.0+ -->
description: 完整的发布工作流
agent: build
model: anthropic/claude-sonnet-4-5
---

执行完整的发布流程：

1. **代码质量检查**
   - 运行测试套件
   - 代码覆盖率检查
   - Linting 检查

2. **版本管理**
   - 更新版本号
   - 创建 git tag
   - 生成 changelog

3. **构建和打包**
   - 构建生产版本
   - 创建 Docker 镜像
   - 推送到镜像仓库

4. **部署**
   - 部署到 staging
   - 运行集成测试
   - 获取部署确认

5. **通知**
   - 发送部署通知
   - 更新项目文档
   - 发布 release notes

3. CI/CD 管道集成

3.1 GitHub Actions 集成

将 OpenCode 集成到 CI/CD 流水线中：

# 文件路径: .github/workflows/opencode-ci.yml
# 来源: https://github.com/anomalyco/opencode/actions/workflows/deploy.yml
# 版本: v1.0.0+

name: OpenCode CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  opencode-review:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        
    - name: Install OpenCode
      run: |
        curl -fsSL https://opencode.ai/install | bash
                
    - name: Configure OpenCode
      run: |
        mkdir -p ~/.local/share/opencode
        echo '${{ secrets.OPENCODE_CONFIG }}' > ~/.local/share/opencode/config.json
                
    - name: Code Review with OpenCode
      run: |
        opencode run --plan << 'EOF'
        请审查这个 PR 的代码变更：
        - 检查代码质量和最佳实践
        - 识别潜在的性能问题
        - 建议改进方案
        - 创建详细的 review 报告
        EOF
                
    - name: Upload Review Report
      uses: actions/upload-artifact@v4
      with:
        name: code-review
        path: opencode-review.md

3.2 Azure DevOps 集成

在 Azure DevOps pipeline 中使用 OpenCode：

# 文件路径: azure-pipelines.yml
# 来源: https://github.com/sst/opencode/issues/3885
# 版本: v1.0.0+

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '20.x'
  displayName: 'Install Node.js'
  
- script: |
    curl -fsSL https://opencode.ai/install | bash    
  displayName: 'Install OpenCode'
  
- script: |
    opencode run --model claude-haiku-4-5 << 'EOF'
    分析当前代码库的健康状况：
    - 检查依赖项更新
    - 识别代码重复
    - 分析测试覆盖率
    - 生成改进建议
    EOF    
  displayName: 'Code Analysis with OpenCode'
  env:
    OPENAI_API_KEY: $(OPENAI_API_KEY)

4. 自定义工具开发

4.1 创建 MCP 工具

使用 Model Context Protocol (MCP) 开发自定义工具：

// 文件路径: mcp-tools/custom-tool.ts
// 来源: https://opencode.ai/docs/mcp-servers/
// 版本: v1.0.0+

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ErrorCode,
  ListToolsRequestSchema,
  McpError,
} from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
  {
    name: 'custom-project-tools',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 注册自定义工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'analyze_dependencies',
        description: '分析项目依赖项并提供优化建议',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: '项目路径',
            },
          },
          required: ['path'],
        },
      },
      {
        name: 'generate_api_docs',
        description: '基于代码注释生成 API 文档',
        inputSchema: {
          type: 'object',
          properties: {
            sourcePath: {
              type: 'string',
              description: '源代码路径',
            },
            outputPath: {
              type: 'string',
              description: '文档输出路径',
            },
          },
          required: ['sourcePath'],
        },
      },
    ],
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === 'analyze_dependencies') {
      const { path } = args;
      
      // 实现依赖分析逻辑
      const fs = require('fs');
      const packageJson = JSON.parse(fs.readFileSync(`${path}/package.json`, 'utf8'));
      
      const analysis = {
        dependencies: Object.keys(packageJson.dependencies || {}),
        devDependencies: Object.keys(packageJson.devDependencies || {}),
        outdated: [],
        vulnerabilities: [],
      };

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(analysis, null, 2),
          },
        ],
      };
    }

    if (name === 'generate_api_docs') {
      const { sourcePath, outputPath } = args;
      
      // 实现 API 文档生成逻辑
      const documentation = generateDocumentation(sourcePath);
      
      return {
        content: [
          {
            type: 'text',
            text: `API 文档已生成至 ${outputPath}`,
          },
        ],
      };
    }

    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
  } catch (error) {
    throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${error.message}`);
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('Custom MCP server running on stdio');
}

main().catch((error) => {
  console.error('Server error:', error);
  process.exit(1);
});

4.2 配置 MCP 服务器

在 OpenCode 配置中添加自定义 MCP 服务器：

// 文件路径: .opencode.jsonc
// 来源: https://opencode.ai/docs/mcp-servers/
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "custom-tools": {
      "command": "node",
      "args": ["mcp-tools/custom-tool.js"],
      "enabled": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true
    },
    "git": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-git", "--repository", "."],
      "enabled": true
    }
  }
}

5. 性能优化技巧

5.1 Token 使用优化

根据 TrueFoundry 的研究，优化 Token 使用是降低成本的关键：

// 文件路径: .opencode.jsonc
// 来源: https://www.truefoundry.com/blog/opencode-token-usage
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "contextManagement": {
    "maxTokens": 32000,
    "compressionThreshold": 20000,
    "pruneOldContext": true,
    "keepSystemMessages": true
  },
  "model": "anthropic/claude-haiku-4-5",
  "fallbackModel": "anthropic/claude-sonnet-4-5",
  "tools": {
    "maxConcurrent": 3,
    "timeout": 30000
  }
}

5.2 上下文管理最佳实践

实施智能上下文管理策略：

---
<!-- 文件路径: .opencode/commands/context-cleanup.md -->
<!-- 来源: https://www.truefoundry.com/blog/opencode-token-usage -->
<!-- 版本: v1.0.0+ -->
description: 智能上下文清理和优化
agent: build
model: anthropic/claude-haiku-4-5
---

执行上下文优化：

1. **压缩对话历史**
   - 保留关键决策点
   - 删除重复的代码片段
   - 合并相关的工具调用

2. **识别重要上下文**
   - 当前文件和依赖
   - 活跃的任务状态
   - 错误和警告信息

3. **清理策略**
   - 移除超过 10 步的工具输出
   - 压缩长代码块为摘要
   - 保留最近的 5-7 次交互

4. **生成上下文摘要**
   - 当前任务进度
   - 已解决的问题
   - 下一步行动计划

5.3 缓存和预加载策略

// 文件路径: .opencode.jsonc
// 来源: 优化经验总结
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "caching": {
    "enableCache": true,
    "cacheDirectory": ".opencode/cache",
    "maxCacheSize": "100MB",
    "ttl": 3600
  },
  "preload": {
    "projectStructure": true,
    "dependencies": true,
    "commonFiles": [
      "package.json",
      "README.md",
      ".gitignore"
    ]
  }
}

6. 生产环境实战案例

6.1 大型项目代码审查

在某金融科技公司的实际应用中，使用 OpenCode 进行代码审查：

---
<!-- 文件路径: .opencode/commands/financial-code-review.md -->
<!-- 来源: 生产环境实践案例 -->
<!-- 版本: v1.0.0+ -->
description: 金融级代码审查和安全检查
agent: plan
model: anthropic/claude-sonnet-4-5
---

执行金融级代码审查：

**安全检查清单：**
1. 输入验证和过滤
2. SQL 注入防护
3. XSS 攻击防护
4. 敏感数据处理
5. 认证和授权机制

**性能优化检查：**
1. 数据库查询优化
2. 缓存策略
3. 并发处理
4. 内存泄漏检测

**合规性检查：**
1. 数据隐私保护
2. 审计日志
3. 错误处理
4. 文档完整性

生成详细的审查报告，包括：
- 发现的问题和风险等级
- 修复建议和最佳实践
- 代码质量评分

6.2 微服务架构重构

使用 OpenCode 协助微服务拆分：

---
<!-- 文件路径: .opencode/commands/microservice-refactor.md -->
<!-- 来源: 生产环境实践案例 -->
<!-- 版本: v1.0.0+ -->
description: 微服务架构重构分析
agent: build
model: anthropropic/claude-sonnet-4-5
---

分析单体应用并规划微服务拆分：

**分析步骤：**
1. **依赖关系分析**
   - 模块间耦合度
   - 数据流分析
   - 接口依赖图

2. **服务边界识别**
   - 业务领域划分
   - 数据一致性边界
   - 团队组织结构

3. **拆分策略制定**
   - 渐进式拆分路径
   - 数据迁移计划
   - 服务间通信方案

4. **技术架构设计**
   - API 网关设计
   - 服务发现机制
   - 分布式配置管理

输出完整的重构方案和实施计划。

6.3 性能瓶颈分析和优化

---
<!-- 文件路径: .opencode/commands/performance-analysis.md -->
<!-- 来源: 生产环境实践案例 -->
<!-- 版本: v1.0.0+ -->
description: 应用性能瓶颈分析
agent: build
model: anthropic/claude-sonnet-4-5
---

执行全面的性能分析：

**前端性能：**
1. Bundle 大小分析
2. 加载时间优化
3. 渲染性能检测
4. 内存使用监控

**后端性能：**
1. API 响应时间
2. 数据库查询优化
3. 缓存命中率
4. 并发处理能力

**基础设施性能：**
1. 网络延迟分析
2. 服务器资源使用
3. 数据库连接池
4. 消息队列性能

生成性能报告和优化建议。

7. 高级配置和最佳实践

7.1 多环境配置管理

// 文件路径: .opencode/development.jsonc
// 来源: 配置最佳实践
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-haiku-4-5",
  "theme": "github-dark",
  "permission": {
    "bash": "allow",
    "write": "allow",
    "edit": "allow"
  },
  "mcp": {
    "filesystem": {
      "enabled": true
    },
    "git": {
      "enabled": true
    }
  }
}

// 文件路径: .opencode/production.jsonc
// 来源: 配置最佳实践
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "theme": "opencode",
  "permission": {
    "bash": "ask",
    "write": "ask",
    "edit": "ask"
  },
  "contextManagement": {
    "maxTokens": 16000,
    "compressionThreshold": 12000
  }
}

7.2 团队协作配置

// 文件路径: .opencode/team.jsonc
// 来源: 团队协作实践
// 版本: v1.0.0+

{
  "$schema": "https://opencode.ai/config.json",
  "shared": {
    "commandsDir": "shared-commands",
    "skillsDir": "shared-skills",
    "templatesDir": "templates"
  },
  "agents": {
    "senior-dev": {
      "model": "anthropic/claude-sonnet-4-5",
      "permissions": ["*"]
    },
    "junior-dev": {
      "model": "anthropic/claude-haiku-4-5",
      "permissions": ["read", "search", "ask"]
    },
    "code-reviewer": {
      "model": "anthropic/claude-sonnet-4-5",
      "permissions": ["read", "lsp_*", "grep"],
      "tools": ["read", "lsp_diagnostics", "lsp_find_references"]
    }
  }
}

8. 故障排除和调试

8.1 常见问题诊断

---
<!-- 文件路径: .opencode/commands/diagnose.md -->
<!-- 来源: 故障排除实践 -->
<!-- 版本: v1.0.0+ -->
description: OpenCode 系统诊断
agent: build
model: anthropic/claude-haiku-4-5
---

执行系统诊断：

**检查清单：**
1. **配置文件验证**
   - JSON 语法检查
   - 配置项完整性
   - 权限设置正确性

2. **连接状态检查**
   - API 密钥有效性
   - 网络连接状态
   - 提供商服务可用性

3. **工具状态验证**
   - MCP 服务器状态
   - 插件加载情况
   - 权限配置检查

4. **性能分析**
   - 响应时间统计
   - Token 使用情况
   - 内存占用分析

生成诊断报告和修复建议。

8.2 性能监控脚本

#!/bin/bash
# 文件路径: scripts/monitor-opencode.sh
# 来源: 性能监控实践
# 版本: v1.0.0+

# OpenCode 性能监控脚本

LOG_FILE=".opencode/logs/performance.log"
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')

# 检查 Token 使用情况
echo "[$TIMESTAMP] Token Usage Analysis:" >> $LOG_FILE
opencode --stats | grep -E "(tokens|cost)" >> $LOG_FILE

# 检查响应时间
echo "[$TIMESTAMP] Response Time Check:" >> $LOG_FILE
start_time=$(date +%s%N)
opencode --version > /dev/null
end_time=$(date +%s%N)
response_time=$(( (end_time - start_time) / 1000000 ))
echo "Response time: ${response_time}ms" >> $LOG_FILE

# 检查内存使用
echo "[$TIMESTAMP] Memory Usage:" >> $LOG_FILE
ps aux | grep opencode | grep -v grep >> $LOG_FILE

echo "---" >> $LOG_FILE

总结

OpenCode 作为一个强大的开源 AI 编程助手，通过合理配置和高级技巧的应用，可以显著提升开发效率。本文介绍的多代理工作流、自定义斜杠命令、CI/CD 集成、自定义工具开发等高级功能，为开发者提供了完整的自动化编程解决方案。

关键要点总结：

多代理协作：合理使用 Build 和 Plan 代理，结合 oh-my-opencode 的专业化代理
自动化工作流：通过自定义斜杠命令创建复杂的自动化流程
CI/CD 集成：将 OpenCode 深度集成到开发流水线中
性能优化：关注 Token 使用优化和上下文管理
团队协作：建立适合团队的配置和权限体系

通过实践这些高级技巧，你将能够充分发挥 OpenCode 的潜力，构建高效、智能的编程工作流。

参考资料

本文验证的信息来源:

验证日期: 2026-01-27

作者：SRE运维博客
博客地址：https://www.cnsre.cn/
文章地址：https://www.cnsre.cn/posts/260127114136/
相关话题：https://www.cnsre.cn/tags/ai/
版权声明: 如需转载，请联系作者授权

OpenCode 入门教程：终端 AI 编程助手完整指南

Wenlong — Thu, 22 Jan 2026 21:02:34 +0800

作者：SRE运维博客
博客地址：https://www.cnsre.cn/
文章地址：https://www.cnsre.cn/posts/260122210234/
相关话题：https://www.cnsre.cn/tags/opencode/
版权声明: 如需转载，请联系作者授权

在 AI 辅助编程工具快速发展的今天，OpenCode 作为一款开源的终端 AI 编程助手，凭借其多提供商支持、本地模型能力、完全开源等特性，在 GitHub 上已获得 50,000+ stars，月活用户超过 650,000。

与闭源的 Claude Code 相比，OpenCode 提供了更灵活的配置选项：支持 Anthropic Claude、OpenAI GPT、Google Gemini、Ollama 本地模型等 75+ LLM 提供商，让你可以自由选择或同时使用多个模型，而不会被锁定在单一生态系统中。

本文将从零开始，详细介绍 OpenCode 的安装、配置和使用，帮助你快速上手这款强大的终端 AI 编程助手。

为什么选择 OpenCode？

在深入安装之前，先了解一下 OpenCode 的核心优势：

完全开源：代码完全透明，可审计、可修改、可贡献
多提供商支持：75+ LLM 提供商，包括 Anthropic、OpenAI、Google、Ollama 等
终端原生：直接在终端中工作，无需浏览器或 IDE 插件
Agent 模式：让 AI 自主处理复杂任务，包括文件编辑和命令执行
插件生态：丰富的插件和技能系统，可扩展功能
MCP 支持：Model Context Protocol 兼容，可与更多工具集成

安装 OpenCode

OpenCode 提供了多种安装方式，你可以根据自己的系统和偏好选择最适合的方法。

方法一：Shell 脚本安装（推荐）

这是最快速的安装方式，使用官方提供的安装脚本：

`1`	`curl -fsSL https://opencode.ai/install \| bash`

来源: OpenCode GitHub README | Context7 官方文档

说明：

需要网络连接和 curl 工具
脚本会自动下载并安装最新版本的 OpenCode
支持自定义安装路径：

# 自定义安装路径到 /usr/local/bin
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# 自定义安装路径到 $HOME/.local/bin
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

方法二：NPM 全局安装

如果你已经安装了 Node.js 和 npm，可以使用 NPM 安装：

`1`	`npm install -g opencode-ai`

来源: OpenCode 安装文档

方法三：Docker 运行

如果你使用 Docker，可以直接运行官方镜像：

`1`	`docker run -it --rm ghcr.io/anomalyco/opencode`

来源: Installation and Setup

验证安装

安装完成后，运行以下命令验证安装：

`1`	`opencode --version`

预期输出会显示 OpenCode 的版本号。

配置 OpenCode

OpenCode 的配置文件位于 ~/.config/opencode/opencode.jsonc（或 opencode.json）。配置文件支持 JSONC 格式（带注释的 JSON）。

配置文件结构

配置文件的基本结构如下：

// 文件路径: ~/.config/opencode/opencode.jsonc
// 来源: OpenCode 官方配置文档
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["{file:./custom-instructions.md}"],
  "provider": {
    // Provider 配置
  }
}

配置 LLM 提供商

OpenCode 支持多种 LLM 提供商，下面是几种常见提供商的配置示例。

配置 OpenAI

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

来源: OpenCode Config 文档

说明：

{file:~/.secrets/openai-key} 表示从文件中读取 API Key
先创建 ~/.secrets/ 目录，然后创建 openai-key 文件，填入你的 API Key

1
2

mkdir -p ~/.secrets
echo "sk-your-openai-api-key" > ~/.secrets/openai-key

配置 Anthropic Claude

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{file:~/.secrets/anthropic-key}"
      }
    }
  }
}

配置 Ollama 本地模型

使用 Ollama 运行本地模型，完全私有且免费：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}

来源: LM Studio Provider 配置

前提条件：

已安装 Ollama：curl -fsSL https://ollama.ai/install.sh | sh
已拉取模型：ollama pull deepseek-r1:1.5b
Ollama 服务运行在 http://localhost:11434

Ollama 配置示例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "baseURL": "http://localhost:11434",
      "models": {
        "deepseek-r1:1.5b": {
          "name": "DeepSeek R1 1.5B"
        },
        "llama3.2": {
          "name": "Llama 3.2"
        }
      }
    }
  }
}

来源: Ollama Provider 配置

验证配置

配置完成后，可以通过以下命令验证：

1
2

# 查看已配置的提供商
opencode auth list

来源: OpenCode Providers 文档

快速开始

启动 OpenCode

进入你的项目目录，启动 OpenCode：

1
2

cd /path/to/your/project
opencode

初始化项目

首次使用时，运行 /init 命令来初始化项目：

> /init

来源: OpenCode 初始化文档

说明：

/init 命令会分析你的项目结构
创建 AGENTS.md 文件，包含项目特定的 AI 配置
AGENTS.md 应该提交到 Git 仓库

基本使用示例

示例 1：创建文件

`1`	`opencode "Create a file named hello.txt and write 'OpenCode was here' into it"`

来源: OpenCode Installation Guide

示例 2：代码分析

`1`	`> Analyze the current project structure and identify potential issues`

示例 3：重构代码

`1`	`> Refactor the login component for better error handling`

高级功能

Agent 模式

OpenCode 支持多种 Agent 模式，每种模式针对不同的任务类型：

{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "build": {},
    "plan": {},
    "my-custom-mode": {}
  }
}

来源: OpenCode Mode 配置

模式说明：

build: 构建相关任务
plan: 规划和分析任务
my-custom-mode: 自定义模式

技能和插件

OpenCode 支持自定义技能（Skills）和插件（Plugins）系统，扩展其功能。

技能目录结构：

my-skill/
├── SKILL.md          # Required: 技能元数据和指令
├── references/        # Optional: 文档和指南
│   ├── guide.md
│   └── examples.md
├── assets/           # Optional: 二进制文件和模板
│   ├── template.html
│   └── logo.png
└── scripts/          # Optional: 可执行脚本
    ├── setup.sh
    └── generate.py

来源: OpenCode Skills Plugin

MCP 服务器配置

OpenCode 支持 Model Context Protocol (MCP)，可以集成更多工具和服务：

{
  "$schema": "https://opencode.ai/config.json",
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": [
        "npm-global-exec@latest",
        "@cloudbase/cloudbase-mcp@latest"
      ],
      "env": {
        "INTEGRATION_IDE": "OpenCode"
      }
    }
  }
}

来源: CloudBase MCP 配置

常见使用场景

场景 1：调试代码

`1`	`> My React app isn't rendering the user list component. Help me debug this.`

OpenCode 会：

分析项目结构
识别组件文件中的潜在问题
建议运行诊断命令
提供修复建议

来源: OpenCode NaviGator AI 文档

场景 2：代码重构

`1`	`> Extract validation logic from the login form to a custom hook`

场景 3：生成测试

`1`	`> Write unit tests for the AuthService class using Jest`

场景 4：文档生成

`1`	`> Generate API documentation for the REST endpoints in this project`

性能优化

减少上下文窗口

对于大型项目，可以通过以下方式优化性能：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

来源: OpenCode Agent Skills 文档

使用本地模型

对于敏感项目或离线环境，配置 Ollama 本地模型可以：

保护代码隐私
减少网络延迟
避免使用云服务的费用

故障排查

问题 1：API Key 未找到

错误信息：

Error: API key not found

解决方案：

确认 ~/.secrets/ 目录存在
确认 API Key 文件名称正确（如 openai-key、anthropic-key）
确认文件内容有效（不包含多余空格或换行）

问题 2：Ollama 连接失败

错误信息：

Error: Failed to connect to Ollama server

解决方案：

确认 Ollama 服务已启动：ollama serve
确认端口号正确（默认 11434）
测试连接：curl http://localhost:11434/api/tags

问题 3：权限错误

错误信息：

Error: Permission denied

解决方案：

确认配置文件权限正确：chmod 600 ~/.config/opencode/opencode.jsonc
确认 API Key 文件权限正确：chmod 600 ~/.secrets/*

最佳实践

1. 项目级配置

为每个项目创建项目级配置，而不是使用全局配置：

1
2
3

cd /path/to/project
mkdir -p .opencode
# 创建项目级 opencode.jsonc

2. 使用 Git 忽略敏感文件

在 .gitignore 中添加：

.secrets/
.opencode/

3. 版本控制配置

将 opencode.jsonc 添加到版本控制，但排除包含 API Key 的配置部分。

4. 定期更新

定期更新 OpenCode 以获取最新功能和修复：

`1`	`opencode upgrade`

来源: OpenCode CLI 文档

总结

OpenCode 作为一款开源的终端 AI 编程助手，为开发者提供了：

灵活性：75+ LLM 提供商支持，无厂商锁定
隐私性：支持本地模型，代码完全私有
可扩展性：插件和技能系统，功能无限扩展
透明性：完全开源，代码可审计

无论是个人开发者还是团队，OpenCode 都能显著提升开发效率。从快速原型开发到复杂的代码重构，从调试问题到编写测试，OpenCode 都能成为你值得信赖的 AI 编程伙伴。

参考资料

本文验证的信息来源：

官方文档
GitHub 源码
社区资源
集成文档
本文测试环境
- 系统: macOS Sonoma 14.0
- OpenCode 版本: v1.0.190+
- 测试日期: 2026-01-22
- 验证的 LLM 提供商: OpenAI, Anthropic, Ollama

作者：SRE运维博客
博客地址：https://www.cnsre.cn/
文章地址：https://www.cnsre.cn/posts/260122210234/
相关话题：https://www.cnsre.cn/tags/opencode/
版权声明: 如需转载，请联系作者授权