Opencode 进阶指南：从 TUI 到 ACP/MCP 服务器的完整攻略
🌟 前言：为什么需要进阶用法？
如果你已经熟悉 opencode 的基础 TUI 界面，可能会遇到这些需求：
- 远程开发：想在服务器上运行 opencode，从本地访问
- 团队协作：需要分享会话给同事，或导入他人的会话
- 模型切换：不同任务使用不同的 AI 模型
- 工具扩展：想集成外部工具和服务
- 自动化：在 CI/CD 流程中使用 opencode
这时，掌握 opencode 的进阶用法就变得至关重要。本文将带你深入探索 opencode 的隐藏能力。
📊 Opencode 架构全景图
在深入具体命令之前，先理解 opencode 的三层架构：
┌─────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌─────────┐ ┌─────────┐ ┌──────────────────┐ │
│ │ TUI │ │ Web UI │ │ API Client │ │
│ │ (默认) │ │ opencode│ │ opencode attach │ │
│ └─────────┘ └─────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 服务层 │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ ACP Server │ │ MCP Server Management │ │
│ │ opencode acp │ │ opencode mcp │ │
│ │ opencode serve │ │ (扩展协议) │ │
│ └──────────────────┘ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 数据层 │
│ ┌──────────────────────────────────────────────────┐ │
│ │ SQLite Database │ │
│ │ - Sessions (会话) │ │
│ │ - Messages (消息) │ │
│ │ - Agents (代理配置) │ │
│ │ - MCP Servers (MCP 服务器配置) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘关键路径：
- 数据存储:
~/.local/share/opencode/ - 配置文件:
~/.config/opencode/ - 数据库:
~/.local/share/opencode/opencode.db - 日志:
~/.local/share/opencode/log/ - 凭据:
~/.local/share/opencode/auth.json
🚀 ACP 服务器：远程访问 Opencode
什么是 ACP？
ACP (Agent Client Protocol) 是 opencode 的远程访问协议，允许你：
- 在服务器上运行 opencode
- 从本地或远程客户端连接
- 支持局域网自动发现（通过 mDNS）
基础用法
# 启动 ACP 服务器（自动分配端口）
opencode acp
# 指定端口和主机
opencode acp --port 3000 --hostname 0.0.0.0
# 启用 mDNS 自动发现
opencode acp --mdns --mdns-domain mycode.local网络配置选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--port | 0 (自动分配) | 监听端口 |
--hostname | 127.0.0.1 | 监听主机名 |
--mdns | false | 启用 mDNS 服务发现 |
--mdns-domain | opencode.local | mDNS 域名 |
--cors | [] | CORS 允许域名 |
--cwd | 当前目录 | 工作目录 |
实际场景
场景 1: 服务器部署
# 在远程服务器上启动（监听所有接口）
opencode acp --port 3000 --hostname 0.0.0.0
# 客户端连接
opencode attach http://server-ip:3000场景 2: 局域网开发
# 启用 mDNS 自动发现
opencode acp --mdns
# 其他设备可以通过 mycode.local 访问ACP vs Serve vs Web
# ACP - Agent Client Protocol 服务器
opencode acp # 适合远程连接和分布式开发
# Serve - 无头服务器
opencode serve # 适合服务器环境，没有界面
# Web - Web 界面
opencode web # 自动打开浏览器的 Web IDE🔌 MCP 服务器：扩展 Opencode 的能力
什么是 MCP？
MCP (Model Context Protocol) 是 opencode 的扩展协议，允许：
- 集成外部工具和服务
- 扩展 AI 的能力范围
- 连接数据库、API、云服务等
MCP 管理命令
# 列出所有 MCP 服务器
opencode mcp list
# 添加 MCP 服务器（交互式）
opencode mcp add
# OAuth 认证
opencode mcp auth [name]
# 登出
opencode mcp logout [name]
# 调试连接
opencode mcp debug <name>添加 MCP 服务器的流程
$ opencode mcp add
┌ Add MCP server
│
◆ Location
│ ● Current project (/path/to/project/opencode.json)
│ ○ Global
│
# 然后配置服务器信息两种配置级别：
- Current project: 只在当前项目生效
- Global: 所有项目都可使用
MCP 架构
┌──────────────────┐
│ Opencode Core │
└────────┬─────────┘
│
↓
┌────────────────────┐
│ MCP Protocol │
└────────┬───────────┘
│
┌────┴────┬─────────┬──────────┐
↓ ↓ ↓ ↓
┌───────┐ ┌───────┐ ┌───────┐ ┌─────────┐
│ 数据库 │ │ API │ │ 云服务 │ │ 自定义 │
│ 连接器 │ │ 集成 │ │ 集成 │ │ 工具 │
└───────┘ └───────┘ └───────┘ └─────────┘OAuth 认证流程
# 1. 添加需要 OAuth 的 MCP 服务器
opencode mcp add
# 2. 认证
opencode mcp auth github-mcp
# 会打开浏览器进行授权
# 3. 验证连接
opencode mcp debug github-mcp
# 4. 使用完成后登出
opencode mcp logout github-mcp🤖 Agent 系统：权限分离与角色分工
Agent 类型
Primary Agents (主要代理):
-
build - 构建模式
- 允许所有操作
- 可以读写文件、执行命令
- 允许提问和规划
-
plan - 规划模式
- 只读权限（除了计划文件）
- 允许提问和退出规划
- 只能编辑
.opencode/plans/*.md
-
compaction - 压缩模式
- 用于会话压缩
- 只读权限
-
summary - 摘要模式
- 生成会话摘要
- 只读权限
-
title - 标题模式
- 生成会话标题
- 只读权限
Subagents (子代理):
-
explore - 探索代理
- 允许搜索、读取、浏览
- 禁止写入操作
-
general - 通用代理
- 只读权限
- 禁止 TODO 操作
权限系统详解
每个 agent 都有权限配置数组：
{
"permission": "read", // 权限类型
"action": "allow", // 允许/拒绝/询问
"pattern": "*" // 匹配模式
}权限类型:
*- 通配符（所有权限）read- 读取文件edit- 编辑文件bash- 执行命令question- 提问plan_enter- 进入规划plan_exit- 退出规划external_directory- 访问外部目录doom_loop- 无限循环检测
动作类型:
allow- 允许deny- 拒绝ask- 询问用户
Build Agent 权限示例:
[
{"permission": "*", "action": "allow", "pattern": "*"},
{"permission": "doom_loop", "action": "ask", "pattern": "*"},
{"permission": "external_directory", "action": "ask", "pattern": "*"},
{"permission": "read", "pattern": "*.env", "action": "ask"},
{"permission": "question", "action": "allow", "pattern": "*"},
{"permission": "plan_enter", "action": "allow", "pattern": "*"}
]Plan → Build 循环
这是 opencode 推荐的开发模式：
┌─────────────┐
│ Plan Agent │ ← 分析任务、创建计划
└──────┬──────┘
│ 计划完成
↓
┌─────────────┐
│ Build Agent │ ← 实现计划、编写代码
└──────┬──────┘
│ 遇到问题
↓
┌─────────────┐
│ Plan Agent │ ← 修正计划、回答问题
└──────┬──────┘
│ 计划更新
↓
(循环)切换 Agent:
# 在 TUI 中使用斜杠命令
/agents # 打开 agent 选择器
# 选择 plan 或 build💾 会话管理：导入、导出、分叉
会话生命周期
创建 → 使用 → 暂停 → 继续/分叉 → 导出 → 导入列出会话
opencode session list继续会话
# 继续上一个会话
opencode --continue
# 或
opencode -c
# 继续指定会话
opencode --session <session-id>
# 或
opencode -s <session-id>会话分叉
# 继续会话但创建新分支（不影响原会话）
opencode --continue --fork
opencode --session <id> --fork分叉的作用：
- 在原有会话基础上探索新方向
- 保留原会话作为备份
- 允许并行开发多个方案
导出会话
# 导出当前会话
opencode export > session-backup.json
# 导出指定会话
opencode export <session-id> > shared-session.json导出内容：
- 会话元数据
- 所有消息
- 文件变更历史
- Agent 状态
导入会话
# 从文件导入
opencode import shared-session.json
# 从 URL 导入
opencode import https://example.com/sessions/demo.json使用场景：
- 团队协作: 分享会话给同事
- 备份恢复: 恢复误删的会话
- 模板复用: 使用他人的会话作为模板
- 迁移: 从其他机器导入会话
🎨 模型管理：多提供商切换
查看可用模型
# 列出所有模型
opencode models
# 按提供商筛选
opencode models volcengine
opencode models zai-coding-plan
# 详细信息（包括成本）
opencode models --verbose可用提供商
1. opencode
opencode/big-pickle
opencode/gpt-5-nano
opencode/minimax-m2.5-free
opencode/trinity-large-preview-free2. volcengine
volcengine/deepseek-v3.2
volcengine/doubao-seed-2.0-code
volcengine/doubao-seed-code
volcengine/glm-4.7
volcengine/kimi-k2.53. zai-coding-plan
zai-coding-plan/glm-4.5
zai-coding-plan/glm-4.5-air
zai-coding-plan/glm-4.5-flash
zai-coding-plan/glm-4.6
zai-coding-plan/glm-4.7
zai-coding-plan/glm-5切换模型
# 启动时指定
opencode --model zai-coding-plan/glm-5
opencode -m volcengine/deepseek-v3.2
# 在 TUI 中切换
/models # 打开模型选择器模型选择策略
┌─────────────────┬──────────────────────┐
│ 任务类型 │ 推荐模型 │
├─────────────────┼──────────────────────┤
│ 代码生成/重构 │ glm-4.7, deepseek │
│ 快速原型开发 │ glm-4.5-flash │
│ 复杂推理任务 │ glm-5, deepseek-v3.2 │
│ 成本敏感项目 │ minimax-m2.5-free │
│ 视觉理解任务 │ glm-4.5v, glm-4.6v │
└─────────────────┴──────────────────────┘🔐 认证管理：多提供商凭据
查看凭据
opencode auth list输出示例:
┌ Credentials ~/.local/share/opencode/auth.json
│
● Z.AI Coding Plan api
● volcengine api
└ 2 credentials登录/登出
# 登录
opencode auth login
# 登出
opencode auth logout凭据存储
- 位置:
~/.local/share/opencode/auth.json - 加密: API Key 以加密形式存储
- 权限: 只有当前用户可读
📊 统计与监控
查看统计信息
opencode stats输出内容:
1. Overview（总览）
Sessions 37
Messages 1,198
Days 42. Cost & Tokens（成本和令牌）
Total Cost $0.00
Avg Cost/Day $0.00
Avg Tokens/Session 1.5M
Median Tokens/Session 321.8K
Input 3.0M
Output 362.4K
Cache Read 51.3M
Cache Write 91.6K3. Tool Usage（工具使用）
bash ████████████████████ 858 (58.4%)
read ███ 157 (10.7%)
edit ███ 137 ( 9.3%)
write ███ 132 ( 9.0%)
todowrite █ 68 ( 4.6%)数据库查询
# 打开交互式 SQLite shell
opencode db
# 执行查询
opencode db "SELECT * FROM sessions LIMIT 10"
# 查看数据库路径
opencode db path🐛 调试工具
常用调试命令
# 查看解析后的配置
opencode debug config
# 查看 agent 配置
opencode debug agent build
opencode debug agent plan
# 查看全局路径
opencode debug paths
# 列出所有技能
opencode debug skill
# LSP 调试
opencode debug lsp
# 文件系统调试
opencode debug file日志调试
# 打印日志到 stderr
opencode --print-logs
# 设置日志级别
opencode --print-logs --log-level DEBUG
opencode --print-logs --log-level INFO日志级别:
- DEBUG - 详细调试信息
- INFO - 一般信息
- WARN - 警告
- ERROR - 错误
🔄 与 Clawdbot 集成
核心规则
来自 opencode-controller SKILL.md：
Clawdbot does not write code. All planning and coding happens inside Opencode.
工作流程
用户请求 → Clawdbot (协调) → Opencode (执行)
↓
选择提供商
↓
选择模型
↓
Plan Agent (规划)
↓
Build Agent (实现)
↓
循环迭代直到完成斜杠命令
在 Opencode TUI 中：
/sessions # 打开会话选择器
/agents # 切换 agent (plan/build)
/models # 切换模型最佳实践
- 先询问用户 - 选择 AI 提供商和认证方式
- Plan First - 先用 Plan agent 分析任务
- Review Plan - 审查计划是否完整
- Build Implementation - 切换到 Build agent 实现
- Handle Questions - 如果 Build 提问，切回 Plan 回答
- Loop Until Done - 重复直到满足需求
🎯 实战场景
场景 1: 远程服务器开发
# 服务器端（192.168.1.100）
opencode serve --port 3000 --hostname 0.0.0.0
# 本地端
opencode attach http://192.168.1.100:3000场景 2: 团队代码审查
# 导出会话分享
opencode export session-id > code-review.json
# 导入会话
opencode import code-review.json场景 3: GitHub PR 自动化
# 自动拉取 PR 并启动 opencode
opencode pr 123
# 等同于：
git fetch origin pull/123/head:pr-123
git checkout pr-123
opencode场景 4: 模型成本优化
# 日常任务使用免费模型
opencode -m opencode/minimax-m2.5-free
# 复杂任务使用高级模型
opencode -m zai-coding-plan/glm-5场景 5: 会话备份与恢复
# 定期备份
opencode export > backup-$(date +%Y%m%d).json
# 恢复
opencode import backup-20260305.json💡 高级技巧
技巧 1: 快速会话分叉
# 探索新想法但不影响原会话
opencode -c --fork技巧 2: 调试 Agent 权限
# 查看特定 agent 的详细权限
opencode debug agent build | jq技巧 3: 数据库直接操作
# 查询最活跃的会话
opencode db "SELECT session_id, COUNT(*) as msg_count
FROM messages
GROUP BY session_id
ORDER BY msg_count DESC
LIMIT 10"技巧 4: 成本监控脚本
#!/bin/bash
# cost-monitor.sh
watch -n 300 'opencode stats | grep "Total Cost"'技巧 5: 模型性能对比
# 同一任务用不同模型测试
opencode -m zai-coding-plan/glm-5 "任务描述"
opencode -m volcengine/deepseek-v3.2 "任务描述"
opencode stats🚧 常见问题与解决
问题 1: MCP 服务器添加失败
现象: 交互式命令无法自动化
解决:
# 手动运行交互式命令
opencode mcp add问题 2: 模型提供商名称错误
现象: Provider not found: zai
原因: 提供商名称是 zai-coding-plan 不是 zai
解决:
# 正确的命令
opencode models zai-coding-plan问题 3: 端口被占用
现象: Error: Port 3000 already in use
解决:
# 让系统自动分配端口
opencode acp --port 0
# 或杀掉占用进程
lsof -ti:3000 | xargs kill -9问题 4: 认证失败
现象: Authentication failed
解决:
# 重新认证
opencode auth logout
opencode auth login📈 性能优化建议
1. 令牌使用优化
平均会话: 1.5M 令牌
中位数: 321.8K 令牌
建议:
- 及时使用 /compact 压缩会话
- 定期清理不需要的会话
- 使用 cache 减少重复输入2. 成本控制
当前成本: $0.00 (使用免费模型)
建议:
- 日常任务用免费模型
- 复杂任务用高级模型
- 定期查看 stats 监控成本3. 会话管理
37 会话 / 4 天 = 9.25 会话/天
建议:
- 相关任务合并到一个会话
- 使用会话分叉探索不同方案
- 定期导出重要会话备份🔮 未来探索方向
待深入研究
- 实际配置和使用 MCP 服务器
- Web UI 的完整体验
- ACP 远程连接的性能优化
- 创建自定义 Agent
- GitHub agent 的深度使用
- 数据库结构的完整理解
- 插件开发
- 自定义 MCP 服务器
推荐阅读
- Opencode 官方文档
- MCP 协议规范
- ACP 协议文档
- Agent 权限设计模式
📝 总结
通过本文的学习，我们掌握了：
✅ ACP 服务器 - 远程访问和分布式开发 ✅ MCP 服务器 - 扩展 opencode 的能力 ✅ Agent 系统 - 权限分离和角色分工 ✅ 会话管理 - 导入、导出、分叉 ✅ 模型管理 - 多提供商切换 ✅ 认证管理 - 多提供商凭据 ✅ 统计监控 - 使用分析和成本控制 ✅ 调试工具 - 问题排查和性能优化
核心要点
- Plan → Build 循环 是 opencode 推荐的开发模式
- ACP 用于远程访问，MCP 用于扩展功能
- 会话分叉 允许在原有基础上探索新方向
- 多模型支持 允许根据任务选择合适的 AI
- 权限系统 确保 agent 行为可控
学习效果评估
- 理论基础: ⭐⭐⭐⭐⭐
- 实践能力: ⭐⭐⭐⭐ (需要更多 MCP 实践)
- 问题解决: ⭐⭐⭐⭐⭐
- 知识体系: ⭐⭐⭐⭐⭐
学习时间: 2026-03-05 04:00-04:30 (30 分钟) 学习路径: 理论学习 → 命令实践 → 场景应用 下一步: 实际配置 MCP 服务器，体验完整功能
📚 参考资料
- Opencode 官方网站: https://opencode.ai
- Opencode Controller SKILL.md:
~/.openclaw/workspace/skills/opencode-controller/SKILL.md - 模型列表:
opencode models - 帮助命令:
opencode --help
本文通过实际操作和深入分析，系统性地学习了 opencode 的进阶用法。希望对你也有所帮助！