How I Configure OpenCode: AGENTS.md, Permissions, and More
I’ve been fine-tuning OpenCode’s various configurations for some time now. In this article, I’ll go over my settings.
AGENTS.md
AGENTS.md is probably the most important part of the configuration. This file serves as the soul and memory of OpenCode, and is permanently preloaded into every OpenCode conversation.
Two Prohibitions
Initially, I only specified two prohibitions in this file: 1. Any dangerous commands must first be approved by the user; 2. Uploading local personal data, files, etc., to the internet or external services without the user’s consent is strictly prohibited. I believe these two points are most important and should be set first. Since I’ve installed OpenCode on my local machine—which is convenient but also poses security risks—although mainstream AI agents generally handle security quite well these days, explicitly adding these prohibitions should provide even greater assurance. Many people recommend installing personal assistant AI tools like Hermes on a VPS or a dedicated machine, which is indeed safer but also introduces inconvenience and increased costs. I currently don’t feel this is necessary; all my AI agents are installed locally, and I’ve added these two prohibitions to each of them—I haven’t encountered any serious security issues so far.
Continuous Learning
Due to the limitations of AI models, errors in understanding, execution, and other areas frequently occur when performing various tasks. When an error is sufficiently typical and specific, you can let the AI add a description of the error and the correct solution to AGENTS.md. This way, the next time the AI encounters a similar scenario while executing a task, it will proactively suggest updating the list of rules in AGENTS.md. As the tool is used continuously, AGENTS.md will accumulate more lessons learned. Its capabilities will also gradually improve.
Keep It Simple
AGENTS.md must be preloaded into every session; if it becomes too large, it will consume a significant number of tokens on its own. Worse still, based on my observations, the more content there is in AGENTS.md, the more likely the AI is to forget certain details—especially for less capable models. So, in a sort of counterpoint to the previous point, I’ve added a rule to AGENTS.md that suggests users streamline the file’s content when it exceeds 100 lines. Keeping it simple also makes AGENTS.md easier to maintain.
Communication and Writing
Whether the configurations mentioned above take effect depends crucially on the quality of the instructions written in AGENTS.md. Writing is also one of the AI’s fundamental capabilities; it can help you compose all sorts of content. Communication is another fundamental skill of AI; it’s not only closely tied to solving your problems but also directly impacts your experience using AI tools. I believe that an AI can only be considered high-quality if it not only correctly understands your needs during communication and uses precise wording when writing, but also remains gentle and polite. Unfortunately, even when considering paid plans, such AI systems are rare. Furthermore, the user experience with AI may vary based on personal preferences, so ultimately, you’ll have to explore and decide for yourself which model suits you best. However, to ensure the experience is as pleasant as possible when using any AI, you may set some relevant restrictions in AGENTS.md—such as prohibited words and writing guidelines. Yet, no matter how I configure these settings, I haven’t been able to strike a balance between simplicity and effectiveness. It seems this issue requires further consideration; if any of you know how to address it, feel free to contact me anytime to discuss.
Skill of Skill
When certain tasks need to be repeated, or when lessons learned involve complex operations, you can write a corresponding skill so that OpenCode knows to follow the same procedure when encountering a similar scenario in the future. This serves as a useful reminder in itself and can be added to AGENTS.md. At the same time, knowing how to write a skill is a skill in itself—specifically, how to craft a skill that the AI can trigger precisely and execute efficiently. Fortunately, there are already some ready-made skills available for this purpose that can be used right away. I selected one of them, and it works quite well.
Skill or MCP
The fundamental difference between agent-based tools and chat-based AIs is that the former can interact with the real world. For example, interacting with the terminal is the most basic yet powerful form of interaction. Therefore, using agent-based tools can significantly enhance your ability to operate OSes like GNU/Linux, as I’ve talked about in the previous article.
Another extremely common form of interaction is browsing the web. OpenCode already comes with two built-in tools for this: webfetch and websearch. webfetch fetches content from a specified URL and converts it to Markdown, text, or HTML for the AI to read. It’s used for viewing documentation and specific web pages. websearch uses the Exa AI search engine to retrieve information. These two tools are convenient and powerful, and OpenCode can invoke them autonomously while performing tasks. However, their limitation is that they cannot execute JavaScript. Therefore, to truly interact with a browser (clicking, taking screenshots, filling out forms, etc.), you need to configure OpenCode—for example, through Skills or MCP. I explored numerous solutions on the market and settled on using agent-browser. And when configuring this tool, you inevitably face a choice: Skill or MCP. I tried both, and the results matched my intuition: the skill performed slightly better. This was an informal test, though; I may need to write test cases in the future to quantify the results. For now, however, I’m quite satisfied with how agent-browser is performing.
Another obvious application is interacting with mobile devices. This field is developing rapidly, with many tools available, but after trying so many products, I found that mobilecli is the only one that works well. Similarly, I configured this tool for OpenCode using the “skill” method.
opencode.jsonc
Ultimately, the configurations above are all read by the AI, so the quality of the AI model determines the final effectiveness of the configuration. For this reason, it’s important to have a place where configurations aren’t influenced by the AI—namely, a traditional software configuration file. For OpenCode, this file is opencode.jsonc. I primarily configured the following two items in this file.
Permissions
Although I initially set two restrictions in AGENTS.md, whether the AI actually respects these settings depends on the AI itself. In contrast, the jsonc file allows for hard constraints. My configuration principle is to strictly deny access to directories containing personal data, while allowing access to everything else. In my experience, using OpenCode with this configuration is convenient and doesn’t introduce many security concerns.
LLMs
To use a model, you obviously need to set it up first. As I’ve mentioned in my previous article, choosing a model is a science in itself. But recently, I’ve felt that this issue has become even more critical. Just in the past few days, I suddenly realized that nearly all free models on the market have deteriorated to the point where they’re practically unusable. Hmm, the battle for market share seems to be drawing to a close, I thought.
I had already prepared myself to switch entirely to paid models—until the name of a new model caught my eye: Ox Alpha. I’d never heard of it before; it’s a “stealth” model. But after trying it out, I mean, It’s just insane! I couldn’t imagine a free model coming so close in capability to top-tier paid models. When using it, it supported my configuration far better than any free model I’d used before.
Conclusion
Overall, I’m quite satisfied with my current experience using OpenCode, and these settings should work for any AI agent. But at the end of the day, I feel that the quality of the AI model is still what matters most!