夜雨聆风
OpenClaw 安装接入飞书 + LiteLLM 模型接入实操手册
OpenClaw 安装接入飞书 + LiteLLM 模型接入实操手册
面向小白的一步步实操指南，轻概念重操作。跟着做就行。
第一部分：安装 OpenClaw
1.1 系统要求
●macOS / Linux / Windows（WSL2）
●Node.js 22+（安装脚本会自动处理）
1.2 一键安装
macOS / Linux：
●●●bash curl -fsSL https://openclaw.ai/install.sh | bash
Windows PowerShell：
●●●powershell iwr -useb https://openclaw.ai/install.ps1 | iex
安装脚本会自动检测 Node 环境、安装 CLI、启动引导向导。
1.3 如果已有 Node 22+，手动安装
●●●bash npm install -g openclaw@latestopenclaw onboard --install-daemon
1.4 验证安装
●●●bash openclaw doctoropenclaw status
看到 gateway 状态正常即可。
1.5 安装后 PATH 找不到 openclaw？
●●●bash # 检查node -vnpm prefix -g# 修复：把下面这行加到 ~/.zshrc 或 ~/.bashrcexport PATH="$(npm prefix -g)/bin:$PATH"source ~/.zshrc
第二部分：创建飞书应用
2.1 创建应用
1.打开飞书开放平台：https://open.feishu.cn/app
2.点击 创建企业自建应用
3.填写应用名称和描述，上传图标
4.创建完成后，进入应用详情页
2.2 复制凭证
在 凭证与基础信息 页面，复制：
●App ID（格式：cli_xxx）
●App Secret
⚠️ App Secret 要保密，不要提交到代码仓库。
2.3 配置权限
在 权限管理 页面，点击 批量导入，粘贴以下 JSON：
●●●json {"scopes": {"tenant": ["im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","im:message","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource" ],"user": ["im:chat.access_event.bot_p2p_chat:read" ] }}
如果你还需要 OpenClaw 帮你创建/管理飞书文档，额外添加：
●●●json {"scopes": {"tenant": ["docx:document","docx:document:readonly","docs:permission.member:create" ] }}
2.4 开启机器人能力
在 应用能力 → 机器人：
1.开启机器人能力
2.设置机器人名称
2.5 配置事件订阅
⚠️ 注意：先完成下面的”第三部分”配置 OpenClaw 并启动 gateway，再回来做这一步。
在 事件与回调 页面：
1.选择 使用长连接接收事件（WebSocket 模式）
2.添加事件：im.message.receive_v1
2.6 发布应用
1.在 版本管理与发布 中创建版本
2.提交审核并发布
3.企业自建应用通常自动审批通过
第三部分：OpenClaw 接入飞书
3.1 安装飞书插件
●●●bash openclaw plugins install @openclaw/feishu
3.2 添加飞书通道（推荐用向导）
●●●bash openclaw channels add
选择 Feishu，粘贴你的 App ID 和 App Secret。
3.3 或者手动编辑配置文件
编辑 ~/.openclaw/openclaw.json，在 channels 下添加：
●●●json {"channels": {"feishu": {"enabled": true,"dmPolicy": "pairing","accounts": {"default": {"appId": "cli_xxx（替换成你的 App ID）","appSecret": "xxx（替换成你的 App Secret）","botName": "我的AI助手" } } } }}
3.4 启动 gateway
●●●bash openclaw gateway start
确认状态：
●●●bash openclaw gateway status
3.5 配置事件订阅（回到飞书开放平台）
现在 gateway 已启动，回到 2.5 步骤，配置事件订阅。
3.6 发送测试消息
在飞书中找到你的机器人，发送任意消息。
3.7 审批配对
首次发消息，机器人会返回一个配对码。在终端执行：
●●●bash # 查看待配对列表openclaw pairing list feishu# 审批配对（替换 CODE 为实际的配对码）openclaw pairing approve feishu CODE
审批后就可以正常对话了。
3.8 群聊配置
默认情况下，群聊中需要 @机器人 才会响应。
如果想让机器人在群里不需要 @就响应：
●●●json {"channels": {"feishu": {"groups": {"oc_xxx（群聊ID）": {"requireMention": false } } } }}
获取群聊 ID：启动 gateway 后在群里 @机器人，然后看日志：
●●●bash openclaw logs --follow
日志中会出现 chat_id: oc_xxx。
第四部分：通过 LiteLLM 接入模型
为什么需要 LiteLLM？
OpenClaw 只认 OpenAI 协议。你的模型可能是 Azure、Anthropic、或公司内部代理。LiteLLM 做协议转换：
●●●code OpenClaw → (OpenAI 协议) → LiteLLM → (Azure/Anthropic/其他协议) → 你的模型
4.1 安装 LiteLLM
●●●bash pip install litellm[proxy]
4.2 创建 LiteLLM 配置文件
创建 ~/.openclaw/litellm_config.yaml：
●●●yaml model_list: # ===== Azure OpenAI 示例 ===== - model_name: gpt-5.2 litellm_params: model: azure/gpt-5.2 api_base: https://your-resource.openai.azure.com api_key: your-azure-api-key api_version: "2024-05-01-preview" # ===== Anthropic Claude 示例（直连官方） ===== - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-5-20250514 api_key: your-anthropic-api-key # ===== 公司内部 Claude 代理示例 ===== - model_name: aws-claude-opus-4-6 litellm_params: model: anthropic/aws-claude-opus-4-6 api_base: https://your-company-proxy.com/llm-gateway api_key: os.environ/ANTHROPIC_API_KEYgeneral_settings: master_key: sk-openclaw-litellm-key-12345
配置要点：
|
|
|
|---|---|
model_name |
|
model |
provider/model-id
azure/ = Azure 协议，anthropic/ = Anthropic 协议 |
api_base |
|
api_key |
os.environ/ENV_VAR_NAME 读环境变量 |
master_key |
|
⚠️ 踩坑提醒：
1.model 字段必须带 provider 前缀（如 azure/、anthropic/），否则报 LLM Provider NOT provided
2.如果用 Anthropic 协议，api_base不要带 /v1/messages 后缀，LiteLLM 会自动拼接
3.anthropic/ 前缀会被 LiteLLM 自动剥离后再发给上游，所以 anthropic/aws-claude-opus-4-6 发出去的 model 名是 aws-claude-opus-4-6
4.3 设置环境变量（如果用了 os.environ）
在 ~/.zshrc 中添加：
●●●bash # Azureexport AZURE_API_KEY="your-azure-key"# 如果接入公司 Claude 代理export ANTHROPIC_API_KEY="your-jwt-token-or-api-key"
生效：
●●●bash source ~/.zshrc
4.4 启动 LiteLLM
●●●bash # 停止已有实例pkill -9 -f litellm || true# 后台启动nohup litellm --config ~/.openclaw/litellm_config.yaml --port 4000 > /tmp/litellm.log 2>&1 &# 等待启动sleep 3# 确认启动成功tail -20 /tmp/litellm.log
确认日志中有 LiteLLM: Proxy initialized with Config, Set model list，无报错。
4.5 验证 LiteLLM
●●●bash curl -s http://localhost:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-openclaw-litellm-key-12345" \ -d '{"model": "gpt-5.2","messages": [{"role": "user", "content": "说一个字"}],"max_tokens": 50 }'
返回包含 choices[0].message.content 就说明 LiteLLM 到模型的链路通了。
调试模式（看完整请求）：
●●●bash litellm --config ~/.openclaw/litellm_config.yaml --port 4000 --detailed_debug
第五部分：OpenClaw 对接 LiteLLM
5.1 编辑 openclaw.json 添加 LiteLLM Provider
在 ~/.openclaw/openclaw.json 中添加 models 部分：
●●●json {"models": {"mode": "merge","providers": {"litellm": {"baseUrl": "http://localhost:4000","apiKey": "sk-openclaw-litellm-key-12345","api": "openai-completions","models": [ {"id": "gpt-5.2","name": "GPT-5.2 (Azure via LiteLLM)","reasoning": true,"input": ["text", "image"],"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},"contextWindow": 200000,"maxTokens": 16000 }, {"id": "aws-claude-opus-4-6","name": "AWS Claude Opus 4.6 (via LiteLLM)","reasoning": true,"input": ["text", "image"],"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},"contextWindow": 200000,"maxTokens": 16000 } ] } } }}
字段说明：
|
|
|
|---|---|
baseUrl |
http://localhost:4000 |
apiKey |
|
api |
openai-completions |
models[].id |
model_name 一致 |
models[].name |
|
models[].reasoning |
|
models[].input |
["text"] 或 ["text", "image"] |
cost |
|
5.2 添加模型别名（可选但推荐）
在 agents.defaults.models 中添加别名，方便切换：
●●●json {"agents": {"defaults": {"models": {"litellm/gpt-5.2": {"alias": "GPT-5.2 (Azure)" },"litellm/aws-claude-opus-4-6": {"alias": "AWS Claude Opus 4.6 (via LiteLLM)" } } } }}
5.3 设置默认模型
●●●bash openclaw models set litellm/aws-claude-opus-4-6
5.4 设置 fallback（推荐）
在配置文件中添加降级策略，主模型挂了自动切换：
●●●json {"agents": {"defaults": {"model": {"primary": "litellm/aws-claude-opus-4-6","fallbacks": ["litellm/gpt-5.2", "litellm/gpt-5.4"] } } }}
5.5 重启 gateway 使配置生效
●●●bash openclaw gateway restart
5.6 验证全链路
●●●bash # 确认当前模型openclaw status# 查看日志openclaw logs --follow
然后在飞书给机器人发消息测试。
第六部分：日常运维速查
Gateway 管理
●●●bash openclaw gateway status # 查看状态openclaw gateway start # 启动openclaw gateway stop # 停止openclaw gateway restart # 重启openclaw logs --follow # 实时日志openclaw logs --limit 50 --plain # 最近50条日志
模型管理
●●●bash openclaw models set litellm/gpt-5.2 # 切换默认模型openclaw gateway restart # 切模型后必须重启openclaw status # 确认当前模型
LiteLLM 管理
●●●bash # 启动pkill -9 -f litellm || truenohup litellm --config ~/.openclaw/litellm_config.yaml --port 4000 > /tmp/litellm.log 2>&1 &sleep 3tail -20 /tmp/litellm.log# 查看日志tail -100 /tmp/litellm.log# 调试模式启动litellm --config ~/.openclaw/litellm_config.yaml --port 4000 --detailed_debug
飞书配对管理
●●●bash openclaw pairing list feishu # 查看待配对openclaw pairing approve feishu CODE # 审批配对
Skills 管理
●●●bash clawhub install <skill-slug> # 安装技能clawhub update --all # 更新所有技能clawhub list # 查看已安装技能
常见聊天命令（在飞书中发给机器人）
|
|
|
|---|---|
/status |
|
/reset |
|
/model |
|
附录：常见问题排查
问题：openclaw 命令找不到
●●●bash export PATH="$(npm prefix -g)/bin:$PATH"
加到 ~/.zshrc，然后 source ~/.zshrc。
问题：机器人不回复消息
1.检查 gateway 是否启动：openclaw gateway status
2.检查飞书事件订阅是否配了 im.message.receive_v1
3.检查是否选了”长连接”模式
4.检查应用是否已发布
5.看日志：openclaw logs --follow
问题：LiteLLM 报 LLM Provider NOT provided
model 字段没加 provider 前缀。改成 azure/model-name 或 anthropic/model-name。
问题：LiteLLM 报 AuthenticationError
检查 API Key 是否正确：
●●●bash echo $ANTHROPIC_API_KEYecho $AZURE_API_KEY
问题：公司代理返回”模型尚未接入”
发给代理的 model 名和代理支持的不匹配。确认代理接受的模型名列表，调整 LiteLLM 配置中 anthropic/ 后面的部分。
问题：切了模型但没生效
切模型后必须重启 gateway：
●●●bash openclaw models set litellm/your-modelopenclaw gateway restart
然后新开对话（旧会话可能仍绑旧模型）。
问题：LiteLLM 挂了 / 端口被占
●●●bash pkill -9 -f litellm || truesleep 2nohup litellm --config ~/.openclaw/litellm_config.yaml --port 4000 > /tmp/litellm.log 2>&1 &
附录：完整配置文件模板
~/.openclaw/litellm_config.yaml
●●●yaml model_list: - model_name: gpt-5.2 litellm_params: model: azure/gpt-5.2 api_base: https://your-resource.openai.azure.com api_key: your-azure-key api_version: "2024-05-01-preview" - model_name: aws-claude-opus-4-6 litellm_params: model: anthropic/aws-claude-opus-4-6 api_base: https://your-company-proxy.com/llm-gateway api_key: os.environ/ANTHROPIC_API_KEYgeneral_settings: master_key: sk-openclaw-litellm-key-12345
~/.openclaw/openclaw.json（核心部分）
●●●json {"models": {"mode": "merge","providers": {"litellm": {"baseUrl": "http://localhost:4000","apiKey": "sk-openclaw-litellm-key-12345","api": "openai-completions","models": [ {"id": "gpt-5.2","name": "GPT-5.2 (Azure via LiteLLM)","reasoning": true,"input": ["text", "image"],"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},"contextWindow": 200000,"maxTokens": 16000 }, {"id": "aws-claude-opus-4-6","name": "AWS Claude Opus 4.6 (via LiteLLM)","reasoning": true,"input": ["text", "image"],"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},"contextWindow": 200000,"maxTokens": 16000 } ] } } },"channels": {"feishu": {"enabled": true,"dmPolicy": "pairing","accounts": {"default": {"appId": "cli_xxx","appSecret": "your-app-secret","botName": "我的AI助手" } } } },"agents": {"defaults": {"model": {"primary": "litellm/aws-claude-opus-4-6","fallbacks": ["litellm/gpt-5.2"] },"models": {"litellm/aws-claude-opus-4-6": {"alias": "AWS Claude Opus 4.6" },"litellm/gpt-5.2": {"alias": "GPT-5.2 (Azure)" } } } }}
~/.zshrc（环境变量部分）
●●●bash # OpenClaw PATHexport PATH="$(npm prefix -g)/bin:$PATH"# 模型 API Keysexport AZURE_API_KEY="your-azure-key"export ANTHROPIC_API_KEY="your-anthropic-key-or-jwt"