goclaw: a Go AI agent framework that borrows OpenClaw's skill format

The problem goclaw solves, and for whom

goclaw is a Go framework for running an LLM agent that can read files, run shell commands, fetch web pages and drive a browser, then talk to you through a chat channel. The README describes it as the Go version of OpenClaw, and the topics list includes ai-agent, llm and openclaw-skills. That framing tells you where the audience is: teams that already run Go services and want the agent runtime in the same language rather than a Node or Python process beside it.

The concrete problem is skill distribution. A skill in goclaw is a directory containing SKILL.md, a markdown file with YAML front matter that gets injected into the system prompt. Because the format is compatible with OpenClaw and AgentSkills, the README states you can copy a skills directory from openclaw/skills and use it directly. That is the main reason to pick this over writing your own tool-calling loop: the skill catalog is portable, and the runtime is a compiled binary rather than an interpreter with a dependency tree.

It is not for someone who wants a hosted assistant. There is no hosted service described. You build the binary, supply model credentials, and run it.

How the agent loop, tools and channels fit together

The repository layout is the clearest documentation of the architecture. agent/loop.go holds the agent loop, agent/context.go builds context, agent/skills.go loads skills, and agent/tools/ splits the tool surface into filesystem.go, shell.go, web.go, browser.go and message.go. Channels live under channels/ with one file per platform, and a channels/manager.go plus channels/base.go interface sit above them. Messages move through bus/ (events.go and queue.go) rather than being passed directly between channel and agent.

Two design choices stand out. First, the browser tool is built on the Chrome DevTools Protocol, via the mafredri/cdp dependency in go.mod, so browser control is a real protocol client rather than an HTTP scraper. Second, sessions are stored as JSONL with full tool-call chains, which the README says allows recording and recovery. That is a meaningful difference from frameworks that keep conversation state only in memory: you can inspect what the agent actually did.

Memory is handled two ways according to the README: a built-in vector database and QMD, described as a Quick Markdown Database. The repository has a memory/ directory at the top level. The README does not explain when to choose one over the other, which is a gap if you plan to run long-lived sessions.

Model providers are behind providers/factory.go, with OpenAI, Anthropic and OpenRouter implementations listed. Qianfan is described as OpenAI-compatible, which is why it can share the openai-completions API path.

Building goclaw and running a first session

The README gives a clone-and-build path. Note that a plain go build produces only the Go binary; the README marks make build-full as the full build including the UI, and calls it recommended. The src-tauri/ and ui/ directories in the repository root are what that target pulls in.

git clone https://github.com/smallnest/goclaw.git
cd goclaw
go mod tidy
go build -o goclaw .
make build-full
go run main.go start

After starting, the README states the dashboard is reachable locally at http://localhost:28789/dashboard/. The Dockerfile, by contrast, exposes port 8080 and health-checks http://localhost:8080/health, so the container and the local run do not use the same port. If you deploy the image, that is the port to map.

Configuration resolution is the part most likely to trip you up. goclaw looks for ~/.goclaw/config.json first, then ./config.json, then GOSKILLS_* environment variables, and --config overrides all of it. The example config in the README sets workspace.path, agents.defaults with model.primary, max_iterations, temperature and max_tokens, and a models block with mode set to merge and a providers map. Here is the shape, trimmed to one provider:

{
  "agents": {
    "defaults": {
      "model": { "primary": "qianfan/kimi-k2.5" },
      "max_iterations": 15,
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "qianfan": {
        "baseUrl": "https://qianfan.baidubce.com/v2",
        "apiKey": "${QIANFAN_API_KEY}",
        "api": "openai-completions"
      }
    }
  }
}

The apiKey value uses ${QIANFAN_API_KEY}, so the secret is read from the environment rather than stored in the file. To see what the agent can do, list the loaded skills:

./goclaw skills list

Skills load from ~/.goclaw/skills/, then ${WORKSPACE}/skills/, then ./skills/, with later paths overriding earlier ones for skills of the same name. WORKSPACE defaults to ~/.goclaw/workspace. Writing a skill means creating a directory with a SKILL.md whose front matter declares the name, a description, and a metadata.openclaw.requires.bins list. The README's example gates a skill on python3 being installed.

Where goclaw gets in your way

The skill gating mechanism is a double-edged feature. A skill only loads when the binaries it declares are present, which prevents the agent from being told to use a tool that does not exist. But the check is on the host, and the README's example is a single bins list. There is no documented way to express a version constraint or a fallback skill, so a host with an old python3 and a host with a new one are treated identically.

Configuration precedence is another sharp edge. Because ~/.goclaw/config.json wins over ./config.json, a stale global file silently overrides the config checked into your project. The README documents the order but not a command to print which file was resolved. If behavior does not match your repository config, that is the first thing to check.

Operations are the weakest area. The README documents configuration, skills and the dashboard URL. It does not document rollback, backup of the JSONL session store, or what happens to in-flight sessions when the process restarts. The Dockerfile creates .goclaw/workspace and .goclaw/sessions inside the container's home directory, which means a container restart without a mounted volume loses both. That is a deployment detail you have to solve yourself.

Finally, the channel list is long but uneven. Telegram, Slack, Discord and Feishu have SDK dependencies in go.mod (telegram-bot-api, slack-go, discordgo, larksuite/oapi-sdk-go). Others, such as Weixin or Google Chat, appear in the channel file listing without a corresponding first-party SDK visible in the module requirements, so their maturity is not something the README establishes.

goclaw against OpenClaw and against writing your own loop

The obvious comparison is OpenClaw, and the search data shows people ask whether goclaw is the same thing. It is not. goclaw is a separate Go codebase that adopts OpenClaw's skill specification so that SKILL.md files and the skills directory are portable. What changes is the runtime: a compiled Go binary with a Go tool layer, versus whatever OpenClaw runs on. If you already have OpenClaw skills and a Go deployment target, the compatibility is the whole selling point. If your skills depend on OpenClaw runtime behavior beyond the markdown contract, portability is not guaranteed by the README.

The second alternative is building the loop yourself on top of langchaingo, which goclaw already depends on. That gives you full control over context construction and tool registration, at the cost of reimplementing session persistence, channel adapters and approval flows that goclaw ships. The cli/ directory includes approvals.go, so there is an approval path for tool use in the box. For a single internal tool with one chat surface, a smaller custom loop is defensible. For a dozen channels and a skill catalog, goclaw is the shorter path.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-03-27. The most recent release is v0.4.0 from 2026-03-20, preceded by v0.3.4 on 2026-03-01 and v0.3.3 on 2026-02-28. That is a burst of releases in March with no push since, so the project is best described as having been active through March 2026 rather than continuously developed. Treat the release cadence as something to re-check before you depend on it.

Upgrade cost is hard to estimate from what the repository documents. The go.mod pins Go 1.25.5 and a fairly wide dependency set including the Docker client, langchaingo, viper and cobra. The CHANGELOG.md at the repository root is the place to look for breaking changes between v0.3.x and v0.4.0; the README does not carry a migration section. Because sessions are JSONL and skills are markdown, the two things you author yourself survive a binary upgrade, which lowers the cost of staying current.

The licence is MIT, per the README badge and the LICENSE file. MIT is permissive and imposes no copyleft obligation on your own code. That is a statement about the licence text, not legal advice; if you redistribute goclaw inside a product, have counsel read the LICENSE file rather than this paragraph.

Editorial conclusion

Adopt goclaw if your services are already Go and you want agent skills as markdown files that load from ./skills/ without a plugin runtime. Do not adopt it if you need a documented upgrade path or a channel the repository has no implementation for. Before committing, verify that your model endpoint speaks the openai-completions API, that the binaries your SKILL.md files require are present on the host, and that the config file you intend to use is the one goclaw actually resolves first.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. smallnest/goclaw on GitHub