beginner⏱45 minLição 5 de 5

Configuração Básica com opencode.json

Configure o OpenCode usando opencode.json. Aprenda o schema de configuração, agentes, provedores, permissões e como personalizar o comportamento para seus projetos.

Configuração Básica com opencode.json

Localizações de Arquivos de Configuração

O OpenCode procura configuração nesta ordem:

Prioridade	Localização	Finalidade
1	`.opencode/config.json`	Específico do projeto (preferido)
2	`opencode.json`	Específico do projeto (legado)
3	`~/.config/opencode/config.json`	Padrões do usuário

💡Tip

Para novos projetos, use .opencode/config.json. O opencode.json na raiz é mantido por compatibilidade retroativa.

Estrutura de Configuração Básica

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {},
  "providers": {},
  "permissions": [],
  "skills": {}
}

Configurando Agentes

Agentes são assistentes de IA com modelos e comportamentos específicos.

Agente Simples

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Assistente de codificação de propósito geral"
    }
  }
}

Múltiplos Agentes

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Assistente de codificação de propósito geral"
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Especialista em revisão de código"
    },
    "fast": {
      "model": "gpt-4o-mini",
      "description": "Tarefas rápidas e perguntas simples"
    }
  }
}

Agente com Prompt Personalizado

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Engenheiro de software sênior",
      "prompt": "Você é um engenheiro de software sênior com mais de 10 anos de experiência. Foque em código limpo e manutenível. Sempre considere casos extremos e tratamento de erros."
    }
  }
}

Configurando Provedores

Provedores definem como o OpenCode se conecta a serviços LLM.

OpenAI

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    }
  }
}

Anthropic

json

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Múltiplos Provedores

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "google": {
      "apiKey": "${GOOGLE_API_KEY}"
    }
  }
}

Configurando Permissões

Permissões controlam quais ações os agentes podem realizar.

Permissões Básicas

json

{
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pip *"],
      "deny": ["rm -rf /", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "docs/**"],
      "deny": [".env", "secrets/**"]
    }
  ]
}

Regras de Permissão

Regra	Descrição
`tool`	A ferramenta a ser controlada
`allow`	Padrões que são permitidos
`deny`	Padrões que são bloqueados
Ordem	Regras de negação são verificadas primeiro

Configurando Habilidades

Habilidades são pacotes de instruções reutilizáveis.

json

{
  "skills": {
    "react-component": {
      "manifest": "skills/react-component/skill.yaml",
      "autoLoad": true,
      "matchPattern": "react component|jsx"
    },
    "python-helper": {
      "manifest": "skills/python-helper/skill.yaml",
      "autoLoad": false
    }
  }
}

Opção	Descrição
`manifest`	Caminho para o arquivo de manifesto da habilidade
`autoLoad`	Carregar automaticamente quando o padrão corresponder
`matchPattern`	Padrão regex para acionar carregamento automático

Configurando Servidores MCP

Servidores MCP conectam o OpenCode a ferramentas e serviços externos.

json

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["mcp-server-fs.js"],
      "env": {
        "ALLOWED_PATHS": "/home/user/projects"
      }
    },
    "database": {
      "command": "python",
      "args": ["mcp-server-db.py"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Exemplo Completo

Aqui está um opencode.json completo para um projeto típico:

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Assistente de codificação principal",
      "prompt": "Você é um desenvolvedor sênior. Foque em código limpo e testável."
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Especialista em revisão de código"
    }
  },
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pytest *"],
      "deny": ["rm -rf *", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "tests/**", "docs/**"],
      "deny": [".env", "secrets/**", "*.key"]
    }
  ],
  "skills": {
    "customize-opencode": {
      "manifest": ".opencode/skills/customize-opencode/skill.yaml"
    }
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Validação

O OpenCode valida sua configuração na inicialização. Erros comuns:

Erro	Causa	Solução
"Invalid JSON"	Erro de sintaxe	Verifique a formatação JSON
"Unknown provider"	Provedor não suportado	Verifique a documentação do provedor
"Invalid model"	Nome do modelo incorreto	Verifique se o modelo existe
"Permission conflict"	Regras sobrepostas	Revise a ordem das permissões

Substituição de Variáveis de Ambiente

Use ${VARIABLE_NAME} para referenciar variáveis de ambiente:

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
}

Isso mantém dados sensíveis fora dos seus arquivos de configuração.

Practice Questions

Practice Question

Qual localização de configuração é recomendada para novos projetos?

Practice Question

Como você referencia variáveis de ambiente no opencode.json?

Practice Question

O que acontece quando um comando de permissão corresponde a regras de allow e deny ao mesmo tempo?

Practice Question

O que a opção autoLoad faz para habilidades?

Practice Question

Qual campo é necessário para definir um agente?

✅Success

Key Takeaways

Use .opencode/config.json para novos projetos (preferido em relação ao opencode.json na raiz)
Agentes requerem pelo menos os campos model e description
Variáveis de ambiente são referenciadas usando a sintaxe ${VARIABLE_NAME}
Regras de deny sempre têm precedência sobre regras de allow nas permissões
Habilidades podem ser carregadas automaticamente quando a entrada do usuário corresponde a um padrão
Servidores MCP rodam como processos separados e comunicam via JSON-RPC
OpenCode valida sua configuração na inicialização e reporta erros

Progresso100%

Entendendo a Interface CLI

Voltar aos Cursos

Contéudo do Curso

1. O que é o OpenCode e por que usá-lo 2. Instalação e Primeira Configuração 3. Sua Primeira Sessão de Codificação com IA 4. Entendendo a Interface CLI 5. Configuração Básica com opencode.json