10 min read ai-coding opencode openrouter setup-guide beginners free-tools tutorial

Setting Up Your First AI Coding Tool: OpenCode + OpenRouter (Free)

A step-by-step walkthrough for setting up OpenCode (a free AI coding tool) with OpenRouter (a free way to access AI models). No coding experience needed. Works on Windows, Mac, and Linux.

Last week we covered what AI coding agents are and why they matter. If you haven't read that yet, start here. Today we're getting your hands dirty.

By the end of this post, you'll have a working AI coding tool on your computer. It won't cost you anything. And you don't need to know how to code.

Let's go.

1. What You'll Need

A computer (Windows, Mac, or Linux -- any of them work) and an internet connection.

That's it. No coding experience. No paid software. No fancy hardware.

If you can download an app and copy-paste text, you can do this.

2. What Is OpenCode?

OpenCode is a free, open-source tool that lets you talk to AI inside your computer's terminal (or a desktop app). Think of it like a chat window where the AI can actually do things -- write files, edit code, run commands -- instead of just talking back to you.

It's the most popular open-source AI coding tool right now, with over 150,000 stars on GitHub and millions of people using it every month. That matters because it means the community is huge, bugs get fixed fast, and there are tons of tutorials out there.

What makes OpenCode different from ChatGPT in a browser:

  • It can read and edit files on your computer
  • It can run commands and see the results
  • It works with dozens of different AI models (not just one)
  • It's completely free and open source

You can use it in three ways: as a terminal tool, as a desktop app, or inside your code editor. For this tutorial, we'll use the desktop app because it's the most beginner-friendly.

3. What Is OpenRouter?

Here's the thing about AI models: there are hundreds of them, made by different companies (Anthropic, OpenAI, Google, Meta, and more), and each one has its own pricing and its own way to connect.

OpenRouter solves this. It's like a phone plan for AI. Instead of signing up separately with every AI company, you create one account on OpenRouter and get access to over 300 models from 60+ providers.

Why OpenRouter specifically:

  • Free models included. Several models on OpenRouter cost $0 to use. That means you can start without paying anything.
  • One API key for everything. You get one key that works with any model. Want to try Claude today and GPT tomorrow? Same key.
  • Pay-per-use for premium models. If you eventually want to use a paid model, you only pay for what you use. No subscription required.
  • It's what OpenCode supports natively. The setup is the simplest of any provider.

The numbers speak for themselves: OpenRouter processes over 70 trillion tokens per month and serves more than 5 million users. It's not some small startup -- it's infrastructure that works.

4. Create Your Free OpenRouter Account

This takes about two minutes.

  1. Open your browser and go to openrouter.com
  2. Click the Sign Up button in the top right
  3. You can sign up with Google, GitHub, or a MetaMask wallet. Pick whichever is easiest -- Google is probably the fastest if you have a Gmail account
  4. Complete any verification steps it asks for

That's it. You now have an OpenRouter account.

5. Get Your API Key

An API key is just a long string of letters and numbers that acts like a password. It tells OpenRouter "this is me, let me in." You'll plug this key into OpenCode later so it can talk to OpenRouter on your behalf.

Here's how to get it:

  1. Once you're logged into OpenRouter, look for your profile icon in the top right corner
  2. Click it and select API Keys from the dropdown
  3. Click Create Key
  4. Give it a name (anything works -- I called mine "opencode")
  5. Copy the key that appears

Important: You will only see this key once. Copy it somewhere safe right now. A notes app, a text file, anywhere you can find it again. If you lose it, you'll need to create a new one.

The key looks something like sk-or-v1-xxxxxxxxxxxxxxxxxxxx. That's normal.

6. Install OpenCode

OpenCode offers three ways to install. Pick the one that matches your setup.

Option A: Desktop App (Recommended for Beginners)

OpenCode has a desktop app in beta for macOS, Windows, and Linux.

  1. Go to opencode.ai
  2. Click Download now (you'll see the desktop beta button)
  3. Download the installer for your operating system
  4. Run the installer like you would any other app
  5. Open OpenCode from your applications folder or start menu

The desktop app gives you a clean window to chat with AI. No terminal needed.

Option B: Terminal (Mac and Linux)

If you're comfortable with the terminal, this is the fastest install:

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

Open your terminal (Command + Space, type "terminal" on Mac), paste that line, and press Enter.

Option C: Terminal (Windows)

On Windows, the easiest terminal install is through npm (Node Package Manager). If you have Node.js installed:

npm install -g opencode

If you don't have Node.js, I'd recommend the desktop app (Option A) instead. It skips the need for any extra tools.

Other Install Methods

OpenCode also supports installation through Homebrew (brew install opencode) and various Linux package managers like paru. Check the docs at opencode.ai if you prefer one of those.

7. Connect OpenCode to OpenRouter

Now we connect the two pieces.

If You're Using the Desktop App

  1. Open OpenCode
  2. It will prompt you to set up a provider on first launch
  3. Select OpenRouter from the list of providers
  4. Paste your API key (the one you copied in step 5)
  5. Pick a model -- for your first time, choose any model marked as free

If You're Using the Terminal

  1. Open your terminal
  2. Type opencode and press Enter
  3. On first run, it will ask you to configure a provider
  4. Select OpenRouter
  5. Paste your API key
  6. Pick a free model to start with

You can also set your API key as an environment variable, which means OpenCode will find it automatically every time:

Mac/Linux: Add this line to your ~/.zshrc or ~/.bashrc file:

export OPENROUTER_API_KEY="your-key-here"

Windows: Open PowerShell and run:

[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "your-key-here", "User")

Then restart your terminal.

8. Your First AI Conversation

You're set up. Time to talk to an AI.

Open OpenCode (either the desktop app or type opencode in your terminal). You should see a chat interface.

Type this:

Hello! I'm completely new to programming. Can you help me write a simple Python program that asks for my name and then says hello to me?

Press Enter and watch what happens.

The AI will write a small program for you. Something like:

name = input("What's your name? ")
print(f"Hello, {name}!")

It might also create the file for you, or tell you how to run it. Either way, you just had an AI write code for you. That's the whole point.

Try asking it follow-up questions:

  • "Can you add a feature where it also asks for my favorite color?"
  • "How do I run this on my computer?"
  • "What does each line do?"

The AI will explain everything. That's how you learn -- by asking questions and building things.

9. Free Alternatives to OpenCode + OpenRouter

OpenCode isn't the only option. Here are other free ways to get started with AI coding.

Claude Code (Free Tier)

Anthropic's own coding agent. Runs in the terminal. You get a limited free allowance each month, and if you already pay for Claude Pro or Max, you get more usage included.

  • Good if: You want the "official" Claude experience
  • Downside: Limited free usage; mostly Claude models only

Codex (OpenAI)

OpenAI's Codex CLI is a terminal-based coding agent. If you have a ChatGPT Plus or Pro subscription, you can log in with your OpenAI account and use your existing plan.

  • Good if: You already pay for ChatGPT Plus/Pro
  • Downside: Requires a paid ChatGPT subscription for meaningful usage

Gemini CLI (Google)

Google offers a free command-line tool that connects to Gemini models. You get free usage with a Google account.

  • Good if: You already use Google everything
  • Downside: Gemini models are hit-or-miss for coding compared to Claude and GPT

GitHub Copilot (Free Tier)

If you have a GitHub account, Copilot's free tier gives you limited monthly suggestions in your editor. It's more of an autocomplete tool than a full agent, but it's a start.

  • Good if: You're already in VS Code
  • Downside: Very limited free usage; not a full coding agent

10. Paid Alternatives

If you end up using AI coding tools every day (and you probably will), here are the paid options worth knowing about.

Claude Max ($100-200/month)

Anthropic's premium plan. You get Claude Code with much higher usage limits, plus access to their best models. This is what I use for most of my daily work.

If you're serious about AI coding and want the best experience, this is the one to get. The quality difference between free Claude and Max is noticeable, especially for complex tasks.

ChatGPT Plus ($20/month)

OpenAI's subscription. Gets you GPT-5.5 access in the browser, and you can use it with OpenCode or Codex. Good value if you also use ChatGPT for non-coding things.

Cursor Pro ($20/month)

Cursor is a code editor (like VS Code) with AI built in. The pro plan gives you unlimited AI completions and agent mode. It's the smoothest "AI inside your editor" experience I've tried.

GitHub Copilot Pro ($19/month or free for students)

Full Copilot access with higher limits. If you're a student, it's free with a .edu email. Worth every penny if you qualify.

11. Chinese Models as Budget Options

Here's something most people don't talk about: Chinese AI labs are putting out incredibly capable models at a fraction of the cost. If you're on a tight budget, these are worth a look.

GLM (Zhipu AI)

GLM is made by Zhipu AI, one of China's top AI labs. Their latest models are competitive with GPT-4 class performance on coding tasks. Available through OpenRouter at significantly lower prices than Western models.

  • Typically 5-10x cheaper than Claude or GPT for similar quality
  • Available on OpenRouter, so you can try it with the same API key
  • Good for: everyday coding tasks, especially if you're watching your spend

DeepSeek

DeepSeek made waves in early 2025 when they released models that matched or beat GPT-4 at a fraction of the cost. Their coding-focused model (DeepSeek-Coder) is genuinely excellent.

  • Very strong on coding benchmarks
  • Extremely cheap per token
  • Available on OpenRouter
  • Good for: anyone who wants near-frontier quality at budget prices

How to Try These

The beauty of OpenRouter is you can switch models with one click. Go to the models page on openrouter.com, search for "GLM" or "DeepSeek," and try them out. Same API key, same setup. You might be surprised at how good they are.

I'll do a full model comparison in the next post, including benchmarks. For now, just know these exist and they're worth exploring if cost matters to you.

12. Troubleshooting

Things go wrong. Here are the most common issues and how to fix them.

"Command not found: opencode"

OpenCode isn't installed or isn't in your PATH. Try the desktop app installer instead of the terminal method. If you used the terminal method, restart your terminal and try again.

"Unauthorized" or "Invalid API key"

Your OpenRouter API key is wrong or expired. Go back to openrouter.com, create a new key, and paste it in again. Make sure you copied the whole thing -- it's long and easy to miss a character.

"Insufficient credits"

You're trying to use a paid model without credits. Either switch to a free model or add credits on OpenRouter. Free models are clearly marked on the models page.

"Rate limit exceeded"

You're sending too many requests too fast. Wait a minute and try again. Free models have lower rate limits than paid ones.

The AI gives bad answers

This happens with weaker models. Try switching to a better one. In OpenCode, you can change models mid-conversation. If you're on a free model, upgrading to even a cheap paid model (like DeepSeek) can make a big difference.

I'm completely lost

That's fine. Seriously. This stuff has a learning curve and nobody gets it right on the first try. reply to the email I sent you. I read every reply.

13. What's Next

You have a working AI coding tool. That's a big deal. Most people reading this will never actually set one up -- they'll just keep reading about AI and never try it.

So you're already ahead.

Next week, I'm publishing a full AI model comparison. I tested every major model on the same coding tasks, timed them, graded the output, and tracked the cost. You'll see exactly which model is best for what, which free models punch above their weight, and where it's worth spending money.

The short version: free models are good enough to learn on. You don't need to spend anything until you're building real projects every day.

Subscribe to the newsletter if you want that comparison sent straight to your inbox when it drops. No spam, one email a week, and I read every reply.

See you next week.

This is post #2 in the AI with Kian beginner series. Post #1: What Are AI Coding Agents? | Post #3: AI Model Benchmarks (coming soon)

Get posts like this in your inbox.

Free newsletter. No spam. One unsubscribe click, ever.

Join Free →