小黑书

Appearance

OpenClaw ​

OpenClaw 是奥地利开发者 somebody 于 2025 年起主导的开源自主 AI 代理项目，最初名为 Clawdbot，经历 Moltbot 等多次更名后于 2026 年正式定名，并以 MIT 许可开源。

Install & Uninstall ​

on macOS

  • install node (provides npm): brew install node
  • install OpenClaw: npm install -g openclaw@latest
  • uninstall: npm uninstall -g openclaw

Quick Start ​

Setup OpenClaw and install the background daemon:

shell
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

alias oc=openclaw

View tail -f style debug log openclaw logs --follow

Custom log level:

json
{
  "logging": {
    "level": "info"
  }
}

Manual gateway start, if you do not install the daemon:

shell
openclaw gateway run
openclaw dashboard

Configure the default model ​

OpenClaw 设置使用本地/线上模型

NOTICE: it is very slow if your hardware is not good enough. Recommended hardware: Mac mini M4 24G or more / RTX 32G or more.

use local ollama model

Install and start Ollama first, then pull the model:

shell
ollama pull qwen3.5:latest
shell
openclaw models list
openclaw models list --provider ollama

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://localhost:11434" \
  --custom-model-id "ollama/qwen3.5:latest" \
  --accept-risk

openclaw config set agents.defaults.model.primary "ollama/qwen3.5:latest"

use remote ollama model

shell
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://<your-host>:11434" \
  --custom-model-id "qwen3.5:latest" \
  --accept-risk

openclaw config set agents.defaults.model.primary "ollama/qwen3.5:latest"

use OpenAI model

shell

export OPENAI_API_KEY=sk-...
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai
openclaw config set agents.defaults.model.primary "openai/gpt-5.4-nano"

Configure the default model with API proxy ​

NOTICE: All following OpenClaw configuration sections are REQUIRED .

yml
# default model for channel
agents.defaults.model
agents.defaults.models

# custom list of agent & default model for control UI
agents.list

models.mode
models.providers.<provider_or_api_proxy>
models.providers.<provider_or_api_proxy>.baseUrl
models.providers.<provider_or_api_proxy>.apiKey
models.providers.<provider_or_api_proxy>.api
models.providers.<provider_or_api_proxy>.models

字段 models.providers.<provider_or_api_proxy>.api 支持的可用值，官网文档没有给出具体的说明。只能通过多个页面拼凑得知。

左侧为 api 值，右侧为哪些 provider 适用：

  • openai-completions , DeepSeek
  • openai-responses , LM Studio
  • openai-codex-responses
  • anthropic-messages , MiniMax
  • google-generative-ai , Gemini
  • github-copilot
  • bedrock-converse-stream
  • ollama , Ollama
  • azure-openai-responses

部份 provider 可以不填 api 字段值，比如 openai 。

See also

use OpenAI compatible

json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "<provider_or_api_proxy>/gpt-5-nano"
      },
      "models": {
        "<provider_or_api_proxy>/gpt-5.5": {},
        "<provider_or_api_proxy>/gpt-5-nano": {}
      }
    },
    "list": [
      {
        "id": "main",
        "model": "<provider_or_api_proxy>/gpt-5-nano"
      }
    ]
  },
  "models": {
    "mode": "merge",
    "providers": {
      "<provider_or_api_proxy>": {
        "baseUrl": "<http_or_https_provider_or_api_proxy>/v1",
        "apiKey": "sk-...",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.5",
            "name": "GPT 5.5",
            "input": ["text", "image"],
            "contextWindow": 1050000,
            "maxTokens": 128000
          },
          {
            "id": "gpt-5-nano",
            "name": "GPT 5 Nano",
            "input": ["text", "image"],
            "contextWindow": 1050000,
            "maxTokens": 128000
          }
        ]
      }
    }
  },
  "plugins": {
    "allow": ["ollama", "memory-core", "openai"]
  }
}

use Ollama compatible

json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "<provider_or_api_proxy>/gpt-5-nano"
      },
      "models": {
        "<provider_or_api_proxy>/gemini-3.1-pro-preview": {},
        "<provider_or_api_proxy>/gemini-2.5-flash-lite": {},
        "<provider_or_api_proxy>/gpt-5-nano": {},
        "<provider_or_api_proxy>/gpt-5.5": {}
      }
    },
    "list": [
      {
        "id": "main",
        "model": "<provider_or_api_proxy>/gpt-5-nano"
      }
    ]
  },
  "models": {
    "mode": "merge",
    "providers": {
      "<provider_or_api_proxy>": {
        "baseUrl": "<http_or_https_provider_or_api_proxy>",
        "apiKey": "sk-...",
        "api": "ollama",
        "models": [
          {
            "id": "gemini-3.1-pro-preview",
            "name": "Gemini 3.1 Pro Preview",
            "input": ["text", "image"],
            "contextWindow": 1048576,
            "maxTokens": 1048576
          },
          {
            "id": "gemini-2.5-flash-lite",
            "name": "Gemini 2.5 Flash Lite",
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 1048576
          },
          {
            "id": "gpt-5.5",
            "name": "GPT 5.5",
            "input": ["text", "image"],
            "contextWindow": 1050000,
            "maxTokens": 128000
          },
          {
            "id": "gpt-5-nano",
            "name": "GPT 5 Nano",
            "input": ["text", "image"],
            "contextWindow": 1050000,
            "maxTokens": 128000
          }
        ]
      }
    }
  },
  "plugins": {
    "allow": ["ollama", "memory-core", "openai"]
  }
}

Restart the gateway openclaw gateway restart

ref: docs.openclaw.ai/gateway/local-models

Test reply ​

After the gateway is running and the default model is configured, send a short test message from the OpenClaw UI or the configured channel:

txt
reply exactly: PONG

The expected reply is:

txt
PONG

Image generation ​

oc 2026.5.4 版本

  • 在对话中发出生图需求且不指定 model 时， oc 会自动调用 tool 和内部指定生图 model
    • 如不论你使用哪个 provider 都会尝试用 openai/gpt-image-2 生图，失败后再尝试其他。
  • oc imageGenerationModel 配置不能灵活支持 API 中转，只能支持有限的几个特定 provider 。不配置这个字段比配置效果更好。

ref: docs.openclaw.ai/tools/image-generation

笔记 ​

  • Mac mini M4 24G 配置运行 ollama + 本地运行的无论多少 B 的 LLM 都无法满足日常应用，会出现各种问题：如 context window 太小无法满足 openclaw 要求、无响应、卡死、响应慢等各种问题。必须使用在线付费 API 接口
  • 某个 agent 在 dashboard 左侧 Chat 导航栏进入，对应 openclaw.json agents.list.* 的一项配置
  • dashboard 中的 agent session model 三者之间是多对多关系，从左侧点击 Chat 进入后，页面顶部的三个下拉选项

FAQs ​

Disable tag line: openclaw config set cli.banner.taglineMode off

ref: docs.openclaw.ai/help/faq

qwen3:8b model does not work on M2 ​

⚠️ Agent failed before reply: Model context window too small (4096 tokens; source=modelsConfig). Minimum is 16000. OpenClaw is using the configured model context limit for this model. Raise contextWindow/contextTokens or choose a larger model.

Use better model and longer context length on better machine, such as ollama/qwen3.5 on Mac mini M4.

In Ollama.app, change context length 4k to 16k

openclaw models list

txt
Model                                      Input      Ctx      Local Auth  Tags
ollama/qwen3.5                             text       125k     yes   yes   default

Sender (untracked metadata) ​

Here's the OpenClaw runtime context for the immediately preceding user message:

json
Sender (untracked metadata):

{
      "schema": "openclaw.inbound_meta.v2",
      "channel": "xxx",
      "provider": "xxx",
      "os": "xxx 19.6.0 (arm64)",
      "model": "MacBookAir17,3",
      "default_model": "xxx 19.6.0 (arm64)"
}

use larger online cloud model instead.

NOTICE: You need to setup VPN global if you use OpenAI in mainland China.

Official site monospace font ​

The official site documentations uses a monospace font, which can cause discomfort after prolonged reading. You can use a Chrome browser extension Fontonic - Change Fonts to change it to non-monospace font.

scope upgrade pending approval ​

看到不断请求日志显示 scope upgrade pending approval ...

根因: 机器的 CLI 设备 和 gateway 的配对状态不同步：CLI 本地存着 token，gateway 的 paired.json 里却没有它。 每次 openclaw devices ... 调用，gateway 都拒绝 → CLI 重新发起 pairing → 又一个新 requestId → 死循环。 .env 里的 OPENCLAW_GATEWAY_TOKEN 是旧的，与 gateway 进程实际在用的 token 不一致。gateway 真正在用的 token 在 ~/.openclaw/service-env/ai.openclaw.gateway.env（launchd 启动时注入）。

解决： 比对 hash 发现 .env 和 service-env 的 token 不同，确认正确 token 在 service-env 文件里。source 正确的环境文件，让 OPENCLAW_GATEWAY_TOKEN 指向 gateway 实际在用的值：

set -a; . $HOME/.openclaw/service-env/ai.openclaw.gateway.env; set +a

用 --token 把这个 master token 显式传给 approve（仅放在环境变量里不够，CLI 的 WS 握手需要 --token 才会用它绕过 device pairing 检查）：

openclaw devices approve --token "$OPENCLAW_GATEWAY_TOKEN" xxx-...

Released under the CC-BY-NC-4.0

Copyright © 1997~present tony9527167