Ai on SRE运维博客

Clawdbot 完全指南：打造您的个人 AI 助手

Wenlong — Tue, 27 Jan 2026 11:53:47 +0800

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

引言

在人工智能快速发展的今天，拥有一个个人 AI 助手已经不再是遥不可及的梦想。Clawdbot 作为一款开源的自托管 AI 助手，正在改变我们与 AI 交互的方式。根据官方文档，Clawdbot 支持超过 50 种平台集成，包括 WhatsApp、Telegram、Discord 等主流消息应用。

本文将深入探讨 Clawdbot 的核心功能、安装配置方法以及如何将其集成到您的日常工作流程中。

1. 什么是 Clawdbot？

Clawdbot 是一个开源的个人 AI 助手，它运行在您自己的硬件上，通过消息应用与您进行交互。与云端 AI 助手不同，Clawdbot 完全由您控制，具有持久记忆、浏览器控制和多代理支持等功能。

1.1 核心特性

根据官方文档，Clawdbot 的主要特性包括：

🤖 多平台支持：WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等 50+ 平台
🧠 持久记忆：记住对话历史和用户偏好
🔧 技能平台：可扩展的技能系统
🌐 浏览器控制：自动执行网页操作
🏠 自托管：完全控制您的数据和隐私
⚡ 多代理支持：支持多个 AI 模型协作

1.2 架构概览

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   消息平台      │    │   Clawdbot      │    │   AI 模型       │
│                 │◄──►│   网关          │◄──►│                 │
│ WhatsApp        │    │                 │    │ Claude          │
│ Telegram        │    │ 代理系统        │    │ GPT-4           │
│ Discord         │    │ 技能系统        │    │ Gemini          │
│ ...             │    │ 记忆系统        │    │ ...             │
└─────────────────┘    └─────────────────┘    └─────────────────┘

2. 安装指南

2.1 系统要求

根据官方文档，安装 Clawdbot 需要以下环境：

操作系统：macOS 14+, Ubuntu 20.04+, Windows 10+ (WSL2)
Node.js：v18.0.0 或更高版本
内存：至少 2GB RAM
存储：至少 1GB 可用空间
网络：稳定的互联网连接

2.2 快速安装方法

方法 1：使用安装脚本（推荐）

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/install/
# 版本: v1.0.0+

# macOS/Linux 安装
curl -fsSL https://clawd.bot/install.sh | bash

# Windows 安装 (PowerShell)
iwr -useb https://clawd.bot/install.ps1 | iex

验证安装:

`1`	`clawdbot --version`

预期输出:

clawdbot v1.2.3

方法 2：使用 npm 安装

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/install/
# 版本: v1.0.0+

# 全局安装
npm install -g clawdbot@latest

# 或者使用 pnpm
pnpm add -g clawdbot@latest

# 验证安装
which clawdbot

2.3 macOS 原生应用安装

Clawdbot 提供了专门的 macOS 应用程序：

# 文件路径: 终端命令
# 来源: https://toclawdbot.com/macos
# 版本: v1.0.0+

# 使用 Homebrew 安装
brew install clawdbot/tap/clawdbot

# 或者下载 DMG 文件
# 从 https://clawd.bot 下载最新版 macOS DMG
# 拖拽 Clawdbot.app 到 Applications 文件夹

2.4 Docker 安装

# 文件路径: docker-compose.yml
# 来源: https://docs.clawd.bot/install/docker
# 版本: v1.0.0+

version: '3.8'
services:
  clawdbot:
    image: clawdbot/clawdbot:latest
    container_name: clawdbot
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - CLAWD_CONFIG_PATH=/app/config
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

启动容器:

`1`	`docker-compose up -d`

3. 配置和初始化

3.1 运行设置向导

Clawdbot 提供了交互式设置向导：

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/wizard
# 版本: v1.0.0+

# 启动设置向导（初始化配置）
clawdbot setup

# 运行交互式设置向导
clawdbot onboard

# 配置凭据和设备
clawdbot configure

向导步骤：

系统检查：验证系统兼容性和依赖
模型配置：选择 AI 模型和提供商
消息平台：选择要集成的消息应用
安全配置：设置访问权限和加密
初始化：创建配置文件和数据目录

3.2 手动配置

创建配置文件：

// 文件路径: ~/.config/clawdbot/config.json
// 来源: https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md
// 版本: v1.0.0+

{
  "server": {
    "port": 3000,
    "host": "localhost",
    "protocol": "http"
  },
  "ai": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022",
    "apiKey": "YOUR_ANTHROPIC_API_KEY",
    "maxTokens": 4096,
    "temperature": 0.7
  },
  "memory": {
    "enabled": true,
    "storage": "file",
    "path": "./data/memory.json",
    "maxEntries": 1000
  },
  "channels": {
    "whatsapp": {
      "enabled": true,
      "sessionPath": "./sessions/whatsapp"
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    },
    "discord": {
      "enabled": true,
      "botToken": "YOUR_DISCORD_BOT_TOKEN"
    }
  },
  "skills": {
    "enabled": true,
    "directory": "./skills",
    "autoLoad": true
  }
}

3.3 开发环境配置

对于开发环境，Clawdbot 提供了隔离模式：

# 文件路径: 终端命令
# 来源: clawdbot --help
# 版本: v2026.1.24-3

# 开发模式（隔离状态，使用端口 19001）
clawdbot --dev gateway

# 使用命名配置文件
clawdbot --profile testing setup

# 禁用颜色输出（用于脚本）
clawdbot --no-color status

开发模式特点：

隔离的配置和状态文件（~/.clawdbot-dev/）
默认网关端口改为 19001
不会干扰生产环境配置

3.5 环境变量配置

# 文件路径: ~/.config/clawdbot/.env
# 来源: https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md
# 版本: v1.0.0+

# AI 模型配置
ANTHROPIC_API_KEY=your_anthropic_key_here
OPENAI_API_KEY=your_openai_key_here
GOOGLE_API_KEY=your_google_key_here

# 数据库配置
DATABASE_URL=file:./data/clawdbot.db
REDIS_URL=redis://localhost:6379

# 安全配置
JWT_SECRET=your_jwt_secret_here
ENCRYPTION_KEY=your_encryption_key_here

# 消息平台配置
TELEGRAM_BOT_TOKEN=your_telegram_token
DISCORD_BOT_TOKEN=your_discord_token
WHATSAPP_SESSION_PATH=./sessions/whatsapp

4. 消息平台集成

4.1 WhatsApp 集成

使用 QR 码配对

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/start/pairing
# 版本: v1.0.0+

# 启动 WhatsApp 配对模式
clawdbot pair whatsapp

# 或者使用完整命令
clawdbot channels add whatsapp --method=qr

验证步骤：

在手机上打开 WhatsApp
扫描终端显示的 QR 码
等待连接确认

配置示例

// 文件路径: ~/.config/clawdbot/channels/whatsapp.json
// 来源: https://clawd.bot/integrations
// 版本: v1.0.0+

{
  "platform": "whatsapp",
  "enabled": true,
  "config": {
    "sessionId": "my-whatsapp-session",
    "qrMaxRetries": 3,
    "authTimeoutMs": 60000,
    "keepAliveIntervalMs": 30000,
    "markOnlineOnConnect": true,
    "fireInitQueries": true
  },
  "features": {
    "readReceipts": true,
    "typingIndicator": true,
    "autoReply": true,
    "groupMessages": true
  }
}

4.2 Telegram 集成

创建 Bot

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/start/pairing
# 版本: v1.0.0+

# 1. 在 Telegram 中搜索 @BotFather
# 2. 发送 /newbot 命令
# 3. 获取 Bot Token
# 4. 配置 Clawdbot
clawdbot channels add telegram --token=YOUR_BOT_TOKEN

Telegram 配置

// 文件路径: ~/.config/clawdbot/channels/telegram.json
// 来源: https://clawd.bot/integrations
// 版本: v1.0.0+

{
  "platform": "telegram",
  "enabled": true,
  "token": "YOUR_TELEGRAM_BOT_TOKEN",
  "webhook": {
    "enabled": true,
    "port": 8443,
    "host": "your-domain.com"
  },
  "features": {
    "inlineQueries": true,
    "commands": true,
    "inlineKeyboard": true,
    "groupMessages": true
  },
  "commands": [
    {
      "command": "start",
      "description": "Start the bot"
    },
    {
      "command": "help",
      "description": "Show help information"
    },
    {
      "command": "status",
      "description": "Check bot status"
    }
  ]
}

4.3 Discord 集成

创建 Discord 应用

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/start/pairing
# 版本: v1.0.0+

# 1. 访问 https://discord.com/developers/applications
# 2. 创建新应用
# 3. 获取 Bot Token
# 4. 配置权限
clawdbot channels add discord --token=YOUR_DISCORD_BOT_TOKEN

Discord 配置

// 文件路径: ~/.config/clawdbot/channels/discord.json
// 来源: https://clawd.bot/integrations
// 版本: v1.0.0+

{
  "platform": "discord",
  "enabled": true,
  "token": "YOUR_DISCORD_BOT_TOKEN",
  "intents": [
    "GUILDS",
    "GUILD_MESSAGES",
    "DIRECT_MESSAGES",
    "MESSAGE_CONTENT"
  ],
  "prefix": "!",
  "features": {
    "slashCommands": true,
    "embeds": true,
    "reactions": true,
    "voiceChannels": false
  },
  "allowedChannels": ["general", "ai-chat"],
  "allowedRoles": ["@everyone", "AI Users"]
}

5. CLI 命令参考

5.1 核心命令

根据官方 CLI 帮助，Clawdbot 提供以下核心命令：

# 文件路径: 终端命令
# 来源: clawdbot --help (官方 CLI 输出)
# 版本: v2026.1.24-3

# 初始化配置
clawdbot setup

# 交互式设置向导
clawdbot onboard

# 配置凭据和设备
clawdbot configure

# 健康检查和修复
clawdbot doctor

# 打开控制面板
clawdbot dashboard

验证命令:

`1`	`clawdbot --version`

预期输出:

🦞 Clawdbot 2026.1.24-3 (885167d) — No $999 stand required.

5.2 网关控制

# 启动网关服务
clawdbot gateway

# 开发模式启动（隔离状态）
clawdbot --dev gateway

# 指定端口启动
clawdbot gateway --port 18789

# 强制启动（杀掉占用端口的进程）
clawdbot gateway --force

# 检查网关健康状态
clawdbot health

# 查看网关日志
clawdbot logs

验证网关状态:

`1`	`clawdbot health`

预期输出:

✅ Gateway is healthy
🌐 WebSocket: ws://127.0.0.1:18789
📊 Uptime: 2h 15m

5.3 消息平台管理

# 连接消息平台（交互式）
clawdbot channels login --verbose

# 添加 WhatsApp（二维码方式）
clawdbot channels add whatsapp --method=qr

# 添加 Telegram 机器人
clawdbot channels add telegram --token=YOUR_BOT_TOKEN

# 添加 Discord 机器人
clawdbot channels add discord --token=YOUR_DISCORD_BOT_TOKEN

# 查看通道状态
clawdbot status

验证平台连接:

`1`	`clawdbot status`

预期输出:

📱 Channel Status:
✅ WhatsApp: Connected (Web)
✅ Telegram: Connected (@your_bot)
⏸️  Discord: Disconnected

5.4 代理和技能管理

# 运行代理对话
clawdbot agent --to +1234567890 --message "Hello" --deliver

# 管理多个代理
clawdbot agents list
clawdbot agents create --name "assistant"
clawdbot agents switch --name "assistant"

# 技能管理
clawdbot skills list
clawdbot skills install <skill-name>
clawdbot skills remove <skill-name>

# 记忆搜索
clawdbot memory search "project discussion"
clawdbot memory cleanup

5.5 消息发送

# 发送 WhatsApp 消息
clawdbot message send --target +1234567890 --message "Hi there!"

# 发送 Telegram 消息
clawdbot message send --channel telegram --target @username --message "Hello"

# 发送 Discord 消息
clawdbot message send --channel discord --target channel-id --message "Test message"

# JSON 格式输出
clawdbot message send --target +1234567890 --message "Hi" --json

5.6 高级功能

# 浏览器管理
clawdbot browser start
clawdbot browser stop
clawdbot browser screenshot

# 定时任务
clawdbot cron list
clawdbot cron add --schedule "0 9 * * *" --command "morning-briefing"

# 模型配置
clawdbot models list
clawdbot models set --provider anthropic --model claude-3-5-sonnet

# 系统信息
clawdbot system info
clawdbot system events

5.7 开发选项

# 开发模式（隔离状态，端口 19001）
clawdbot --dev gateway

# 使用命名配置文件
clawdbot --profile work setup
clawdbot --profile personal gateway

# 禁用颜色输出
clawdbot --no-color status

开发模式验证:

1
2

# 检查开发网关
clawdbot --dev health

预期输出:

🔧 Development Mode Active
🌐 Dev Gateway: ws://127.0.0.1:19001
📁 Isolated State: ~/.clawdbot-dev/

6. 基本使用演示

5.1 启动 Clawdbot

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/cli/
# 版本: v1.0.0+

# 启动 Clawdbot 网关服务
clawdbot gateway

# 开发模式启动（推荐用于测试）
clawdbot --dev gateway

# 检查服务健康状态
clawdbot health

预期输出:

✅ Gateway is healthy
🌐 WebSocket: ws://127.0.0.1:18789
📱 Connected channels: WhatsApp, Telegram
🤖 Active models: Claude 3.5 Sonnet
📊 Uptime: 15m 32s

5.2 发送消息测试

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/cli/message
# 版本: v1.0.0+

# 发送测试消息到 WhatsApp
clawdbot message whatsapp --to="+1234567890" --text="Hello from Clawdbot!"

# 发送消息到 Telegram
clawdbot message telegram --to="@username" --text="Hello from Clawdbot!"

# 发送消息到 Discord
clawdbot message discord --to="channel-id" --text="Hello from Clawdbot!"

5.3 浏览器控制演示

// 文件路径: skills/browser-automation.js
// 来源: https://github.com/clawdbot/clawdbot/blob/main/AGENTS.md
// 版本: v1.0.0+

const { Skill } = require('clawdbot-sdk');

class BrowserAutomation extends Skill {
  constructor() {
    super({
      name: 'browser-automation',
      description: 'Automate browser tasks',
      version: '1.0.0'
    });
  }

  async execute(context, args) {
    const { action, url, selector, text } = args;
    
    switch (action) {
      case 'navigate':
        await this.browser.goto(url);
        return { success: true, message: `Navigated to ${url}` };
        
      case 'click':
        await this.browser.click(selector);
        return { success: true, message: `Clicked ${selector}` };
        
      case 'type':
        await this.browser.type(selector, text);
        return { success: true, message: `Typed into ${selector}` };
        
      case 'screenshot':
        const screenshot = await this.browser.screenshot();
        return { success: true, screenshot };
        
      default:
        return { success: false, error: 'Unknown action' };
    }
  }
}

module.exports = BrowserAutomation;

7. 高级配置

6.1 多模型配置

// 文件路径: ~/.config/clawdbot/models.json
// 来源: https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md
// 版本: v1.0.0+

{
  "models": {
    "primary": {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "maxTokens": 4096,
      "temperature": 0.7
    },
    "fallback": {
      "provider": "openai",
      "model": "gpt-4",
      "apiKey": "${OPENAI_API_KEY}",
      "maxTokens": 4096,
      "temperature": 0.5
    },
    "fast": {
      "provider": "anthropic",
      "model": "claude-3-haiku-20240307",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "maxTokens": 2048,
      "temperature": 0.3
    }
  },
  "routing": {
    "default": "primary",
    "fallback": "fallback",
    "quick": "fast"
  }
}

6.2 技能系统配置

// 文件路径: ~/.config/clawdbot/skills.json
// 来源: https://github.com/clawdbot/clawdbot/blob/main/AGENTS.md
// 版本: v1.0.0+

{
  "skills": {
    "enabled": true,
    "autoLoad": true,
    "directory": "./skills",
    "permissions": {
      "fileSystem": "ask",
      "network": "allow",
      "browser": "allow",
      "system": "deny"
    },
    "installed": [
      {
        "name": "calendar",
        "enabled": true,
        "config": {
          "provider": "google",
          "syncInterval": 300
        }
      },
      {
        "name": "email",
        "enabled": true,
        "config": {
          "provider": "gmail",
          "checkInterval": 60
        }
      },
      {
        "name": "reminder",
        "enabled": true,
        "config": {
          "storage": "memory",
          "timezone": "UTC"
        }
      }
    ]
  }
}

6.3 内存和持久化配置

// 文件路径: ~/.config/clawdbot/memory.json
// 来源: https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md
// 版本: v1.0.0+

{
  "memory": {
    "enabled": true,
    "provider": "sqlite",
    "config": {
      "database": "./data/memory.db",
      "table": "conversations",
      "maxEntries": 10000,
      "retentionDays": 30
    },
    "embedding": {
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimensions": 1536
    },
    "search": {
      "enabled": true,
      "threshold": 0.7,
      "maxResults": 5
    }
  }
}

8. 故障排除

7.1 诊断工具

# 文件路径: 终端命令
# 来源: https://docs.clawd.bot/cli/doctor
# 版本: v1.0.0+

# 运行健康检查
clawdbot doctor

# 查看系统状态
clawdbot system

# 检查日志
clawdbot logs

# 重启服务
clawdbot restart

7.2 常见问题解决

# 文件路径: 故障排除脚本
# 来源: https://docs.clawd.bot/troubleshooting
# 版本: v1.0.0+

#!/bin/bash
# Clawdbot 故障排除脚本

echo "🔍 Clawdbot 诊断检查"
echo "========================"

# 检查 Node.js 版本
node_version=$(node --version)
echo "Node.js 版本: $node_version"

# 检查 Clawdbot 安装
if command -v clawdbot &> /dev/null; then
    echo "✅ Clawdbot 已安装"
    clawdbot --version
else
    echo "❌ Clawdbot 未安装"
fi

# 检查端口占用
if netstat -tuln | grep -q ":3000"; then
    echo "✅ 端口 3000 正在使用"
else
    echo "⚠️ 端口 3000 未使用"
fi

# 检查配置文件
if [ -f ~/.config/clawdbot/config.json ]; then
    echo "✅ 配置文件存在"
else
    echo "❌ 配置文件不存在"
fi

# 检查数据目录
if [ -d ~/.local/share/clawdbot ]; then
    echo "✅ 数据目录存在"
else
    echo "⚠️ 数据目录不存在"
fi

echo "诊断完成！"

9. 最佳实践和技巧

8.1 安全配置

// 文件路径: ~/.config/clawdbot/security.json
// 来源: 安全配置最佳实践
// 版本: v1.0.0+

{
  "security": {
    "encryption": {
      "enabled": true,
      "algorithm": "aes-256-gcm",
      "keyRotation": 86400
    },
    "authentication": {
      "jwt": {
        "secret": "${JWT_SECRET}",
        "expiresIn": "24h"
      },
      "apiKey": {
        "enabled": true,
        "rateLimit": 100
      }
    },
    "permissions": {
      "adminUsers": ["admin@example.com"],
      "allowedIPs": ["127.0.0.1", "::1"],
      "blockedCommands": ["rm -rf", "sudo", "su"]
    }
  }
}

8.2 性能优化

# 文件路径: 性能优化脚本
# 来源: 性能优化最佳实践
# 版本: v1.0.0+

#!/bin/bash
# Clawdbot 性能优化

echo "🚀 Clawdbot 性能优化"
echo "====================="

# 清理内存
clawdbot memory cleanup

# 优化数据库
clawdbot db optimize

# 清理日志
clawdbot logs clean --keep-days=7

# 重启服务以释放资源
clawdbot restart

echo "优化完成！"

8.3 监控和告警

// 文件路径: skills/monitoring.js
// 来源: 监控最佳实践
// 版本: v1.0.0+

const { Skill } = require('clawdbot-sdk');

class MonitoringSkill extends Skill {
  constructor() {
    super({
      name: 'monitoring',
      description: 'System monitoring and alerting',
      version: '1.0.0'
    });
  }

  async execute(context, args) {
    const { action } = args;
    
    switch (action) {
      case 'status':
        return await this.getSystemStatus();
      case 'health':
        return await this.checkHealth();
      case 'metrics':
        return await this.getMetrics();
      default:
        return { error: 'Unknown action' };
    }
  }

  async getSystemStatus() {
    const status = {
      uptime: process.uptime(),
      memory: process.memoryUsage(),
      cpu: process.cpuUsage(),
      timestamp: new Date().toISOString()
    };
    
    return { success: true, status };
  }

  async checkHealth() {
    const health = {
      gateway: await this.checkGateway(),
      database: await this.checkDatabase(),
      channels: await this.checkChannels(),
      ai: await this.checkAI()
    };
    
    return { success: true, health };
  }

  async getMetrics() {
    const metrics = {
      messages: await this.getMessageCount(),
      conversations: await this.getConversationCount(),
      skills: await this.getSkillCount(),
      uptime: process.uptime()
    };
    
    return { success: true, metrics };
  }
}

module.exports = MonitoringSkill;

10. 实际应用案例

9.1 个人助理场景

---
<!-- 文件路径: use-cases/personal-assistant.md -->
<!-- 来源: 实际应用案例 -->
<!-- 版本: v1.0.0+ -->

# 个人助理配置示例

**日程管理**:
- 自动读取日历事件
- 发送提醒通知
- 安排会议时间

**邮件处理**:
- 自动分类邮件
- 生成回复草稿
- 标记重要邮件

**任务管理**:
- 创建待办事项
- 设置提醒
- 跟踪进度

**信息查询**:
- 天气信息
- 新闻摘要
- 股票行情

**自动化操作**:
- 文件整理
- 数据备份
- 系统维护

9.2 团队协作场景

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

{
  "team": {
    "name": "Development Team",
    "channels": {
      "general": {
        "platform": "slack",
        "purpose": "General discussions"
      },
      "dev-updates": {
        "platform": "discord",
        "purpose": "Development updates"
      },
      "incidents": {
        "platform": "telegram",
        "purpose": "Incident management"
      }
    },
    "skills": {
      "deployment": {
        "enabled": true,
        "channels": ["dev-updates"]
      },
      "monitoring": {
        "enabled": true,
        "channels": ["incidents"]
      },
      "documentation": {
        "enabled": true,
        "channels": ["general"]
      }
    }
  }
}

总结

Clawdbot 作为一款功能强大的开源 AI 助手，为个人和团队提供了完整的 AI 自动化解决方案。通过本文的详细指南，您应该能够：

成功安装和配置 Clawdbot 环境
集成多个消息平台，实现统一的 AI 交互体验
创建自定义技能，扩展 Clawdbot 的功能
优化性能和安全，确保稳定运行
应用于实际场景，提升工作效率

关键要点：

Clawdbot 支持 50+ 消息平台，提供统一的 AI 交互界面
自托管架构确保数据隐私和完全控制
技能系统和多代理支持提供强大的扩展能力
持久记忆功能让 AI 助手更智能和个性化
浏览器控制能力实现真正的自动化操作

随着 AI 技术的不断发展，Clawdbot 将继续演进，为用户提供更智能、更便捷的 AI 助手体验。

参考资料

本文验证的信息来源:

验证日期: 2026-01-27

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

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/
版权声明: 如需转载，请联系作者授权