OpenClaw接入指南：三种方式打通本地AI Agent入口

OpenClaw 我第一次跑通的时候，说实话有点懵。项目装好、模型配置好、进程也起来了，日志里干干净净，看起来一切正常——但我愣是不知道该怎么跟它“说话”。后来才反应过来，OpenClaw 本身不是一个带界面的应用，它是一套本地跑的 AI Agent 框架，你得自己选一个入口接进去。这个“入口”选得对不对，直接影响后面好不好用。

这篇文章不聊怎么安装 OpenClaw，聊的是部署完成之后怎么接入。我把自己实际用过的三种方式完整梳理了一遍：命令行直连、HTTP API 接入、消息平台接入。三种方式解决三类问题，配套的场景、配置步骤、踩坑记录都在下面，照着抄基本能跑通。适合正在折腾本地 AI 部署的朋友，也适合已经跑起来了但不知道怎么把 OpenClaw 能力暴露给其他工具的人。

1. 接入的本质：先想清楚你要连的是哪个“口”

1.1 OpenClaw 本地部署后到底是一个什么东西

要搞懂怎么接入，先得明白部署完成后你面前摆了一个什么形态的服务。OpenClaw 本质是一个常驻进程。它启动之后会做三件事：读取配置（比如 openclaw.json 和 .env 里的环境变量）、加载模型后端、把各个通道（作者称之为 Channel）拉起来。

模型后端这一步很关键。OpenClaw 本身不含模型，它需要对接一个推理服务，最常见的就是本地 Ollama。你可以在配置里写 provider: ollama，然后指定模型名，比如 qwen2.5:7b 或者 llama3.1:8b。跑起来之后，OpenClaw 只是一个“大脑调度器”，真正干活的是背后的模型。所以接入 OpenClaw 之前，先确认模型服务是通的，这个我后面在准备章节里会具体说。

通道这层决定了你能从哪里喊它。CLI 通道就是终端；API 通道是一个本地 HTTP 服务；IM 通道则是企业微信、Telegram 这类平台。三种接入方式，本质上就是针对这三类通道做配置和调用。

1.2 三种接入方式的定位差异

我整理了一张表，方便你按需求直接选：

选型之前一定要想清楚一个问题：你到底想让谁用？如果只是自己调试，CLI 就够了，没必要开 API；如果想让笔记本上的脚本、家里的自动化任务调用它，API 是正路；如果是想让同事在微信上直接跟机器人说话，那必须走消息平台。三种方式可以同时启用，互不冲突，但每多开一个口就多一份暴露面，这一点到文章后面你们会看到我踩过的坑。

2. 接入前的准备：跑起来不等于能接入

2.1 确认 OpenClaw 进程和配置

开始之前，先把环境确认一遍。我的部署习惯是：先看日志确认进程是健康的，再看配置确认要用的通道是开的，最后才动手接。

OpenClaw 启动之后，终端会打印当前加载的配置摘要，包括模型、API 端口、各通道状态。如果你在 Windows 上用 WSL2 跑，启动时可能会碰到一个很经典的报错：could not safely verify the wsl2 environment。这个问题我放到后面排查章节细说，这里只想强调一点：在 WSL2 里部署和直接在 Linux 裸机上部署，遇到的接入问题完全不是一回事，Windows 用户务必先把这个环境校验过掉。

配置文件这块，我以我自己的 openclaw.json 为例。主配置里最重要的是三段：model 段决定模型后端，api 段决定是否开放 HTTP 接口，channels 段决定哪些 IM 平台被拉起来。确认这三个段都符合预期，再继续往下。如果你不确定当前配置是否生效，用 openclaw doctor 这类自检命令扫一遍，哪一环没就绪它会直接标红，省得自己猜。

2.2 打通模型后端，否则接进去也是哑巴

我见过太多人卡在这一步：OpenClaw 跑起来了，CLI 也能进，但问什么它都不回。查了半天发现是 Ollama 没起来，或者模型根本没下载。所以接入之前，务必先单独验证模型服务。

以 Ollama 为例，先确认服务在跑：

bash复制curl http://127.0.0.1:11434/api/tags

如果返回一个 JSON 列表，里面有模型名，说明服务正常。接着确认你要用的模型存在：

bash复制ollama list

如果没有，先拉一个。我个人在这台机器上用 qwen2.5:7b，日常问答和工具调用都够用。然后回到 OpenClaw 配置里，把模型名写成和本地模型完全一致的名字：

json复制{
  "model": {
    "provider": "ollama",
    "name": "qwen2.5:7b",
    "baseUrl": "http://127.0.0.1:11434"
  }
}

这里有个细节：baseUrl 在 OpenClaw 本机和 Ollama 同机部署时写 127.0.0.1 没问题，但如果 Ollama 跑在别的机器上，或者你用的是 Docker 里的 OpenClaw，就要写成宿主机 IP。我一开始在 Docker 场景下写 127.0.0.1，结果模型始终连不上，原因就是容器里的 127.0.0.1 是容器自己。这个坑非常典型，值得记住。

如果你不想用本地模型，配置里直接把 provider 换成云端 API 服务也是可以的，写法和 ollama 类似。但既然标题是本地部署，我默认你们是 Ollama 这类本地后端，后面的示例也以 Ollama 为准。

2.3 规划好要开放的端口和凭证

接入之前，把要用的端口和访问凭证规划好，能省掉很多事后麻烦。

• API 端口：我习惯用 8000，你可以在配置里改成任意空闲端口。注意端口不能被其他服务占用，用 lsof -i:8000（macOS/Linux）或者 netstat -ano | findstr 8000（Windows）先查一下。
• API Token：OpenClaw 开启 API 服务后，建议一定要配 token。这个 token 相当于钥匙，所有 HTTP 请求都要带，不带就返回 401。你可能会想“本地部署不用这么防吧”，但如果你后面打算用内网穿透把服务映射出去，没有 token 等于裸奔。
• IM 平台凭证：企业微信要准备 corpid、agentid、secret；Telegram 要准备 bot token。这些凭证在平台后台都能拿到，拿到之后直接填进 channels 段。

到这里，准备工作结束。下面进入正题，三种接入方式逐一实操。

3. 方法一：命令行 CLI 直连——最快看到效果的接入方式

3.1 交互式会话怎么进

命令行接入是最简单的一种方式，适合刚部署完做冒烟测试。启动 OpenClaw 之后，在终端里直接输入：

bash复制openclaw

如果你在配置里开了 CLI 通道，就会进入一个交互式 REPL，光标停在 > 后面等你输入。这时直接打字回车，OpenClaw 会走完整的 Agent 链路：接收问题、组织 prompt、调用模型、执行工具，最后把结果打印回终端。

我第一次测的时候输入“帮我算一下 23 乘以 17 等于多少”，它不但给出了结果，还打印出了它“打算用计算器工具”的思考过程。这个过程对调试特别有价值——你能亲眼看到它每一步在干什么，出了错也能立刻定位是模型理解问题还是工具调用问题。

交互式会话里常用的几个命令：

• /new：清空当前会话上下文，重新开一轮
• /model 模型名：临时切换模型，不用改配置文件
• /status：查看当前会话的上下文长度、模型、已用 token
• /exit：退出

3.2 非交互模式：在脚本里直接调

交互式适合人坐在电脑前，但更多时候我需要在脚本里调它。比如写个定时任务，每天早上让 OpenClaw 整理一遍待办清单。这时候用管道模式最方便：

bash复制echo "基于我上一条消息生成一份今日待办" | openclaw --once

--once 的意思是执行完这一次问答就退出，不进入交互循环。输出结果会打到 stdout，脚本可以直接捕获。这个模式我还用来做过简单的批量测试：写一个测试用例文件，逐行读出来丢给 OpenClaw，把输出存下来对比结果。对于验证 prompt 修改有没有效果，这个路子比反复在交互界面里敲快得多。

注意一点：--once 模式默认不带历史上下文，每次都是独立请求。如果你需要带上下文，得自己把历史消息拼进输入里，或者干脆用后面要讲的 HTTP API。

3.3 CLI 方式的适用边界

CLI 最大的优势是零额外配置、零网络暴露。你不需要开端口，不需要配 token，不需要考虑防火墙，本地进程起来就能用。但它也有明显的天花板：

• 只能本机用。OpenClaw 跑在哪台机器上，你就得在哪台机器的终端里敲命令；
• 没有会话持久化到外部系统。退出之后，想要找回之前的对话得靠日志；
• 没法给其他设备或其他程序复用。

所以我的建议是：CLI 用来做部署后的第一轮验证，以及日常调 prompt、调工具的时候用。等这些都稳定了，再开 API 或者消息平台，不要一上来就全开。

4. 方法二：HTTP API 接入——给所有外部系统提供统一入口

4.1 打开 API 服务并验证存活

HTTP API 是三种接入方式里最“工程化”的一种，也是我把 OpenClaw 和各种工具链串起来的主力通道。在 openclaw.json 里把 api 段打开：

json复制{
  "api": {
    "enabled": true,
    "port": 8000,
    "token": "sk-local-openclaw-demo"
  }
}

保存后重启 OpenClaw。启动日志里会打印 API 服务监听的地址，一般是 http://127.0.0.1:8000。先用一个探活接口确认服务活着：

bash复制curl http://127.0.0.1:8000/health

正常情况下会返回 {"status":"ok"} 之类的 JSON。如果返回 404，也别慌，可能是健康检查路径不叫这个，先去日志里看它到底注册了哪些路由。

4.2 用兼容接口接住所有客户端

这里要重点说一个设计：OpenClaw 的 HTTP API 提供了一组 OpenAI 风格兼容接口。什么意思？就是它把 OpenAI 的 /v1/chat/completions 协议复刻了一遍。这意味着所有原本面向 OpenAI 的客户端工具——SDK、命令行工具、IDE 插件——只要把 base_url 改一下，就能把请求打到本地 OpenClaw 上。

这个设计在我看来是整个 API 接入里最聪明的地方。你不需要为每个工具单独写集成代码，一个兼容层通吃。

用 curl 测试一下：

bash复制curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-local-openclaw-demo" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

返回的 JSON 结构和 OpenAI 一致：choices[0].message.content 就是模型回答。我本地测试时，首 token 延迟大概一两秒，取决于 7B 模型在你这台机器上的推理速度。

Python 这边更简单，用 requests 就行：

python复制import requests

resp = requests.post(
    "http://127.0.0.1:8000/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-local-openclaw-demo",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen2.5:7b",
        "messages": [{"role": "user", "content": "写一个 Python 快速排序"}],
    },
    timeout=120,
)
data = resp.json()
print(data["choices"][0]["message"]["content"])

如果你用的是 OpenAI 官方 SDK，把 base_url 指过来就行：

python复制from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="sk-local-openclaw-demo",
)

resp = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

4.3 把 API 暴露给其他 AI 工具

如果你手头有 Codex、Cline 或者 VS Code 里的各种 AI 插件，它们大多允许你在设置里填一个自定义接口地址。这时候把地址填成 http://127.0.0.1:8000/v1，模型名填 OpenClaw 配置里的那个，API Key 填你配的 token，就能让这些工具把 OpenClaw 当成模型后端来用。

不过这里有个区分要点：OpenClaw 暴露的兼容接口，底层走的到底是“直接调模型”还是“走 Agent 链路”？以我测过的版本来看，/v1/chat/completions 走的是偏纯模型的对话链路，而 OpenClaw 的 Agent 能力（工具调用、多步规划）更多体现在它自己的 CLI 和消息平台通道里。所以如果你是想把代码补全、聊天补全这类能力接进 IDE，用 /v1 接口即可；但如果你想在外部系统里触发完整的 Agent 行为，建议直接调它的原生 API（比如 /api/chat，具体路径看版本）。接之前先确认你用的版本里这些路由的实际情况，别拿旧的接口路径套新版本。

4.4 安全提醒：token 必须配

API 服务一旦开启，它就是一个真实的网络端口。如果你的机器在其他设备可访问的网络里，任何能连到这个端口的人都可以尝试调用。我之前有台测试机放在办公室内网，开了 API 忘了配 token，结果同事扫端口扫到了，问了一堆奇怪问题，虽然没什么实际损失，但当时确实吓一跳。从那之后我的规矩是：API 可以开，但 token 必须配，而且不要用默认值。局域网里传输还好，一旦涉及映射到公网，强烈建议只监听 127.0.0.1，再由前面的反向代理来转发。

5. 方法三：消息平台接入——把 OpenClaw 变成你的 IM 机器人

5.1 为什么最后才上消息平台

CLI 和 API 解决了“开发者怎么用”，消息平台解决的是“普通人怎么用”。把 OpenClaw 挂到 IM 之后，它才真正变成一个随叫随到的助理：不用开终端、不用写代码、手机上一句话就能触发。

但消息平台接入也是三种方式里最容易出幺蛾子的。原因很简单：它牵扯到外部平台的回调、验签、消息格式转换，链路最长。我见过的最典型问题是“OpenClaw 能主动发消息，但我在微信里回它没反应”——这个我放到排查章节详细讲。

5.2 企业微信接入实操

国内环境我会优先推荐企业微信。有两个原因：一是它有规范的机器人 API 和回调机制，不需要个人微信那种游走在灰色地带的方式；二是它的消息可靠性更稳。以下步骤以企业微信为例，其他平台的逻辑类似。

先在管理后台创建一个自建应用：进入“应用管理 -> 自建”，填一个应用名，拿到三个关键凭证：企业 ID（corpid）、应用 AgentId、应用 Secret。然后在“接收消息”配置里填一个回调 URL，这个 URL 用来接收用户发给机器人的消息，同时要设置一个 Token 和 EncodingAESKey 用于验签。

把这三样填进 OpenClaw 配置：

json复制{
  "channels": {
    "wecom": {
      "corpId": "ww1234567890",
      "agentId": "1000002",
      "secret": "你的应用Secret",
      "callback": {
        "token": "你设的Token",
        "encodingAESKey": "你设的EncodingAESKey"
      }
    }
  }
}

保存重启后，在企业微信里找到这个自建应用，给它发一条“你好”。正常情况下它会经过回调 URL 进到 OpenClaw，OpenClaw 调用模型，再通过企业微信 API 把回复推回来。

这里有一个非常关键的细节：回调 URL 必须是企业微信服务器能访问到的公网地址。本地部署的 OpenClaw 默认监听在 127.0.0.1，企业微信的服务器不可能连到你的电脑。所以你需要做一层映射，常见做法是在有公网 IP 的云服务器上跑一个 Nginx，把某个路径反向代理到家里或办公室内网机器的端口上。这属于网络接入层面的问题，frp、cloudflared 这类内网穿透工具都有人用，但注意一定要配合鉴权，别把没有 token 的 OpenClaw 直接暴露到公网。

5.3 Telegram 机器人接入

如果你在海外部署或者主用 Telegram，接入方式更简单——核心就是拿一个 bot token。

打开 Telegram 找 BotFather，发送 /newbot，按提示起名字，BotFather 会给你一个 123456:ABC-DEF... 格式的 token。然后把这个 token 填进 OpenClaw 的 channels 配置：

json复制{
  "channels": {
    "telegram": {
      "token": "123456:ABC-DEF..."
    }
  }
}

Telegram 的 bot 采用长轮询方式主动拉取消息，理论上不需要公网回调地址，这一点和企业微信完全不同。我在本地部署测试时，直接把 Telegram 通道打开，bot 就能收到消息，然后通过 OpenClaw 调用本地 Ollama 模型返回结果，整个过程不需要额外做端口映射。

虽然 Telegram 这条链路通常更省事，但国内网络环境下直连它的 API 有时不太稳定，如果你主要在国内用、目标用户也是国内同事朋友，企业微信是更稳妥的选择。具体网络条件大家按自己的实际情况判断，这里就不展开了。

5.4 消息平台的会话管理

消息平台接入还有个容易被忽略的点：会话管理。IM 里的每一条消息，本质上是一个新的 HTTP 请求或更新事件，OpenClaw 需要判断这条消息属于哪个会话——是同一个用户接着上一轮聊，还是一个新对话。

OpenClaw 的做法是按平台用户 ID 维护会话上下文。也就是说，同一个企业微信用户连续发消息，它会当作同一个上下文来回答；不同用户的消息互不相干。这个机制在大多数场景下够用，但注意上下文是存在内存里的，OpenClaw 进程一重启，所有聊天历史就清了。如果你需要长期记忆，得靠它外挂的记忆组件，这个话题可以单独再写一篇，这里先不展开。

6. 高频问题与排查实录

6.1 WSL2 环境校验失败

在 Windows 上部署的人，大概率见过这条报错：could not safely verify the wsl2 environment。我第一次遇到的时候一头雾水，OpenClaw 明明装好了，却卡在环境校验阶段。

排查思路是分层的。先确认 WSL 本身是正常的：

bash复制wsl -l -v

看输出里是否显示 VERSION 2。如果显示 1，说明发行版跑在旧版 WSL 上，在 PowerShell 里执行 wsl --set-version <发行版名> 2 升级。接着确认 WSL 内核是不是最新的，wsl --update 更新后再试。还有一类情况是 systemd 没开，OpenClaw 的守护进程管理依赖 systemd，需要在 /etc/wsl.conf 里加上：

ini复制[boot]
systemd=true

改完不要只重启 WSL，要彻底 wsl --shutdown 再重新进。说实话这个报错的信息量很少，它只说“无法安全验证”，但原因可能是上面的任何一种。我的经验是按 WSL 版本、systemd、内核顺序逐项排除，基本都是这几类问题。

6.2 “能发不能收”的微信消息问题

这个坑在社区里特别常见：OpenClaw 能通过企业微信主动推送消息，但你给机器人发消息它没反应。很多人以为是模型问题，其实链路根本不走到模型。

这类问题的排查顺序我整理成了一张表：

最坑的一种情况是：回调 URL 配成了 OpenClaw 服务的根路径，但企业微信的验签请求需要走到特定的回调端点。结果就是企业微信后台点“保存”时提示验证成功（因为验签请求被某个兜底处理了），但真正的消息内容却丢了。解决办法是确认配置里回调端点路径与 OpenClaw 文档保持一致，并在后台用“接收消息”里的 URL 精确填写。

6.3 API 能通但模型不回答

如果你用 HTTP API 测试时发现请求返回 200，但 choices 里的内容是空的，十有八九是模型后端的问题。先检查 Ollama 是否真的加载了目标模型，ollama list 确认模型存在；再看模型的上下文长度配置是否太小，如果请求里带了很长的历史消息，OpenClaw 可能因为超出上下文窗口而返回空。

还有一个容易被忽视的：超时。本地 7B 模型在小内存机器上首 token 可能要好几秒，如果你的客户端设置了很短的 timeout，会直接中断请求。我的做法是把 timeout 设到 120 秒，宁可多等也不能误杀。

6.4 Termux 部署的特殊场景

最后提一句 Termux。有不少人在安卓上用 Termux 原生部署 OpenClaw，这种方式不需要 root 也不需要 proot，属于轻量方案，但 Termux 环境有几个特殊性：一是它的调度方式和桌面 Linux 不一样，进程在后台容易被系统杀掉；二是端口监听默认可能只绑了 127.0.0.1，做 API 接入时局域网设备访问不到；三是 Termux 的目录结构和权限模型不同，配置文件的路径要格外注意。如果你在 Termux 里部署后接入不成功，优先检查这三项。手机外接其他设备访问的话，把监听地址改成 0.0.0.0，同时确保 token 配好。

这三种方式我现在同时在用，但分工很明确：日常调试和改 prompt 用 CLI，把 OpenClaw 能力接进自己的脚本和工具链用 HTTP API，给家里人用、手机上随手发消息则是企业微信的机器人。每次新版本升级后，我都会按同样的顺序把三个入口各测一遍，大概五分钟就能确认部署是否正常，这个习惯帮我省了不少排查时间。

最后再分享一个小细节：接入方式不在于多，而在于稳。如果你只给一个人用，CLI 完全够；如果只是想把本地模型能力暴露给你手头的 AI 工具，一个带 token 的 HTTP API 就到位了。消息平台是这些入口里链路最长、外部依赖最多的一个，务必在 CLI 验证通过之后再开启，能少踩一半的坑。希望这篇能帮你们少走点弯路。